feat: record volume stats for total seen

.github/workflows/bot-signoff.yaml

@@ -68,7 +68,7 @@ jobs:
           owner: ${{ github.repository_owner }}
           repositories: ${{ github.event.repository.name }}
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
         with:
           token: ${{ steps.generate-token.outputs.token }}
           ref: ${{ github.head_ref || github.ref }}

.github/workflows/buf.yaml

@@ -14,8 +14,8 @@ jobs:
   buf:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
-      - uses: bufbuild/buf-action@fd21066df7214747548607aaa45548ba2b9bc1ff # v1
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: bufbuild/buf-action@8c6a16e16f12ba20b6470afa9c2ba9b5ba8c97c3 # v1
         with:
           token: ${{ secrets.BUF_TOKEN }}
           github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/conventional-pr.yaml

@@ -36,7 +36,7 @@ jobs:
   lint-pr:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
       - name: Generate a token
         id: generate-token
         uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2.2.2

.github/workflows/release.yaml

@@ -28,7 +28,7 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
 
       - uses: cashapp/activate-hermit@cea9af7913204a965fd488637a8d1811bba2e616 # 1.1.5
 

.github/workflows/stale.yaml

@@ -27,7 +27,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@eb5cf3af3ac0a1aa4c9c45633dd1ae542a27a899 # v10.3.0
+      - uses: actions/stale@1e223db275d687790206a7acac4d1a11bd6fe629 # v10.4.0
         with:
           stale-pr-message: "This PR is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 7 days."
           close-pr-message: "This PR was closed because it has been stalled for 7 days with no activity."

buf.lock

@@ -5,5 +5,5 @@ deps:
     commit: c17df5b2beca46928cc87d5656bd5343
     digest: b5:648a01e0170d4512dea7d564016165decd1ed6e34bef79fe54753e51ad7e27545709ad9157d7551270147d551155c595a2fb0bf5bb33b1c83040ddbce915c604
   - name: buf.build/opentelemetry/opentelemetry
-    commit: 5f2c7d4f740541589805e0816dad4bb0
-    digest: b5:935626c896cfe0f5efda467869c65df49843190c1d16ad24957d62ae840aef5f5da2474ec5c766e730b2727c6a24b39b5a2a073da70cf3f2611ce7d3934def86
+    commit: 41ecbd638b414ccd893b285e3f587991
+    digest: b5:39976f28b39ef7949e9cdc3dd2dde118dd46890c9ba81342b38cfafbc5cbfdd938375e8913b6c73259ccf07920c3e366e944dfb9b346ef36441e437fb7823109

proto/tero/policy/v1/policy.proto

@@ -126,6 +126,34 @@ message PolicySyncStatus {
   TransformStageStatus add = 13;
 }
 
+// VolumeStats reports the total telemetry a client observed since the last
+// sync, regardless of whether any policy matched it. Counts are of records
+// entering policy evaluation, before any keep or transform stage runs, and are
+// reset on each successful sync.
+//
+// Reporting volume is optional, and every field is individually optional: an
+// implementation may report record counts without byte counts, or a subset of
+// signals. Any field left at 0 means "not tracked" as much as it means "none
+// seen", so consumers must not read 0 as an observation.
+//
+// Byte counts, when reported, are the uncompressed OTLP protobuf serialized
+// size of the records as received, and are an estimate; implementations that
+// cannot measure this cheaply may approximate it. A size in any other encoding
+// must not be reported here — leave the field at 0 instead.
+message VolumeStats {
+  // Log records seen, and their total size in bytes.
+  int64 log_records = 1;
+  int64 log_bytes = 2;
+
+  // Metric data points seen, and their total size in bytes.
+  int64 metric_data_points = 3;
+  int64 metric_bytes = 4;
+
+  // Spans seen, and their total size in bytes.
+  int64 spans = 5;
+  int64 span_bytes = 6;
+}
+
 // SyncRequest is sent by clients to request policy updates.
 message SyncRequest {
   // Client identification and capabilities
@@ -142,6 +170,10 @@ message SyncRequest {
 
   // Status of individual policies within this set.
   repeated PolicySyncStatus policy_statuses = 5;
+
+  // Optional. Total telemetry observed since the last sync, regardless of
+  // policy match. Clients that do not track volume omit this.
+  VolumeStats volume = 6;
 }
 
 enum SyncType {

spec.md

@@ -1088,6 +1088,53 @@ restrictive and causes the drop. `keep-info` records a miss because its intent
 was applied. The third record matches neither policy, so neither counter is
 incremented for either policy.
 
+### Volume Tracking
+
+Match tracking is per-policy and only counts records a policy matched. To report
+the denominator — everything the implementation processed — implementations MAY
+report total observed volume via `SyncRequest.volume`, a `VolumeStats` message
+counted **regardless of match status**. Volume tracking is entirely optional: an
+implementation that omits it is still conformant, and providers MUST NOT require
+it.
+
+When reported, volume is counted for every record entering policy evaluation,
+including records
+that match no policy and records with no policies loaded for their signal.
+Counting happens **before** the keep and transform stages, so dropped, sampled
+out, and redacted records are all included at their pre-policy size.
+
+`VolumeStats` reports records and bytes per signal:
+
+| Field                | Unit    | Counts                                        |
+| -------------------- | ------- | --------------------------------------------- |
+| `log_records`        | records | Log records seen.                             |
+| `log_bytes`          | bytes   | Total size of those log records.              |
+| `metric_data_points` | records | Metric data points seen (not metric streams). |
+| `metric_bytes`       | bytes   | Total size of those data points.              |
+| `spans`              | records | Spans seen.                                   |
+| `span_bytes`         | bytes   | Total size of those spans.                    |
+
+Record counts are in the same unit as `PolicySyncStatus.match_hits` and
+`match_misses`, so a policy's match rate is `(hits + misses) / <signal count>`.
+
+Byte counts are independently optional: an implementation MAY report record
+counts alone and leave the `*_bytes` fields at `0`. When reported, they are the
+uncompressed OTLP protobuf serialized size of the record as received, and are an
+estimate — an implementation that cannot measure this cheaply MAY approximate
+it. A byte count MUST NOT be reported in a different encoding (e.g. JSON, or a
+post-compression size); leave the field at `0` instead.
+
+Because `0` is both "not measured" and "measured as zero", a consumer MUST NOT
+infer that a field left at `0` means no volume was seen. Any field of
+`VolumeStats` MAY be left at `0` by an implementation that does not track it.
+
+Counters cover the interval since the last successful sync and MUST be reset
+once a sync succeeds. If a sync fails, the counters MUST be retained and
+included in the next attempt.
+
+Implementations that do not track volume at all SHOULD omit `SyncRequest.volume`
+rather than send a zero-valued message.
+
 ## YAML Representation
 
 While the canonical format is Protocol Buffers, policies MAY be represented in
@@ -1365,6 +1412,9 @@ An implementation conforms to this specification if it:
    batch, and reports compilation errors via `PolicySyncStatus.errors`.
 9. Handles [extensions](#extensions) per the stated rules for any extension
    `type` it supports, and documents which `type`/`version` pairs it supports.
+10. If it reports `SyncRequest.volume`, counts it per the
+    [volume tracking](#volume-tracking) semantics. Reporting volume, and
+    reporting byte counts within it, are both optional.
 
 Implementations MAY support a subset of features (e.g., omit rate limiting) but
 MUST clearly document unsupported features.