From e472e6cd8f84300803ac22819b8f1279ed969ea4 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 20:56:13 -0700 Subject: [PATCH 1/3] chore(quest): claim quest/m1/api-audit/stats-naming.md Quest-Claim: 050ce8efe91db634 From b8aceda57322bd043f369e27d2123392fbfa9638 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Thu, 22 Oct 2026 21:40:48 -0700 Subject: [PATCH 2/3] refactor(stats): one name per stats track, reader, and CLI surface Rename the prefix track to /prefix.json, take an Encoding instead of a compressed bool, name the consume readers *Consumer like the aggregate ones, rename the CLI media report surfaces to import --report and export report, drop the relay --stats-* flags from moq, and make stats.interval a duration. Co-Authored-By: Claude Opus 5.5 --- doc/bin/cli.md | 23 +-- doc/bin/inspect.md | 2 +- doc/bin/relay/config.md | 2 +- doc/concept/stats.md | 20 +- quest/m1/api-audit/README.md | 1 - quest/m1/api-audit/stats-naming.md | 41 ----- quest/m2/e2ee/cli.md | 4 +- quest/m2/qos-lag-dashboard.md | 2 +- quest/m2/qos-publisher-timeliness.md | 2 +- quest/m2/qos/README.md | 2 +- quest/m2/qos/lag-histogram.md | 2 +- quest/m2/stats/rust.md | 14 +- quest/m3/README.md | 2 +- quest/m3/msf-publish-tracks.md | 2 +- rs/moq-cli/src/args.rs | 107 +++++------ rs/moq-cli/src/main.rs | 25 ++- rs/moq-cli/src/publish.rs | 29 +-- rs/moq-cli/src/report.rs | 8 +- rs/moq-cli/tests/integration/listen.rs | 57 +----- rs/moq-cli/tests/integration/main.rs | 2 +- .../tests/integration/{stats.rs => report.rs} | 24 +-- rs/moq-relay/MIGRATE.md | 6 + rs/moq-relay/src/cluster.rs | 5 +- rs/moq-relay/src/config.rs | 6 +- rs/moq-relay/src/relay.rs | 2 +- rs/moq-relay/src/settings.rs | 2 +- rs/moq-relay/src/stats.rs | 42 +++-- .../tests/integration/auth_embedder.rs | 2 +- rs/moq-relay/tests/integration/wire_stats.rs | 2 +- rs/moq-stats/MIGRATE.md | 7 + rs/moq-stats/benches/aggregate.rs | 4 +- rs/moq-stats/src/aggregate.rs | 38 ++-- rs/moq-stats/src/consume.rs | 84 +++++---- rs/moq-stats/src/lib.rs | 174 ++++++++++-------- rs/moq-stats/src/produce.rs | 99 +++++----- 35 files changed, 378 insertions(+), 466 deletions(-) delete mode 100644 quest/m1/api-audit/stats-naming.md rename rs/moq-cli/tests/integration/{stats.rs => report.rs} (95%) diff --git a/doc/bin/cli.md b/doc/bin/cli.md index b42a7222f3b..68a50ca3e77 100644 --- a/doc/bin/cli.md +++ b/doc/bin/cli.md @@ -59,13 +59,6 @@ open stdin pipe does not keep the process alive afterward. Admission is part of the handshake, so `--listen-timeout` bounds it too; `0s` leaves admission without a deadline. -Add `--stats-enabled` before the first stage to publish accepted-session and -traffic counters with the relay's `--stats-*` settings. An export-only listener -publishes nothing to its sessions, so they cannot read these stats. These -listener settings require a MoQ listener. Grants still scope which broadcasts -each session can publish or subscribe to, including stats; see the relay's -[statistics configuration](/bin/relay/config#stats). - `moq import --help` lists the sources and `moq import rtmp --help` a specific one; every flag is documented there. Flags renamed between releases are listed in [MIGRATE.md](https://github.com/moq-dev/moq/blob/main/rs/moq-cli/MIGRATE.md). @@ -483,11 +476,11 @@ default version every return is a replacement. An export that fails while the br a codec TS cannot carry, exits 1 without lingering. Only `ts` can mark a break, so the other formats refuse `--linger`. -## Stats and feedback +## Reports and feedback -`import --stats` names a stats track in the catalog and reports what each -rendition has written, about once a second while someone subscribes, with the -connection's RTT, estimated send rate, and loss. It covers the stdin imports; +`import --report` names a track in the catalog's `stats` section and reports +what each rendition has written, about once a second while someone subscribes, +with the connection's RTT, estimated send rate, and loss. It covers the stdin imports; capture, the gateways, `archive`, and `ts --program all` refuse it. `export --echo ` answers a publisher that solicits feedback: under the @@ -496,15 +489,15 @@ the export reads has received and its newest arrival, until the export ends. It covers the stdout container exports and needs a hang catalog, so MSF refuses it. -The `stats` and `echo` sinks print reports as JSON lines. `export stats` -follows one broadcast's stats track until the broadcast ends; `export echo` +The `report` and `echo` sinks print reports as JSON lines. `export report` +follows one broadcast's report track until the broadcast ends; `export echo` prints `{"broadcast", "feedback"}` for every `.echo` broadcast under `--broadcast` as they come and go, reading one that ends for 5 s more for its final report. Either sink stops reading a report that grows past 1 MiB. ```bash -moq ... --broadcast event import --stats ts < feed.ts -moq ... --broadcast event export stats +moq ... --broadcast event import --report ts < feed.ts +moq ... --broadcast event export report moq ... --broadcast event export --echo alice ts > out.ts moq ... --broadcast viewers export echo ``` diff --git a/doc/bin/inspect.md b/doc/bin/inspect.md index 7acd57a099c..94f55ce0f4b 100644 --- a/doc/bin/inspect.md +++ b/doc/bin/inspect.md @@ -77,7 +77,7 @@ The node name (`local/host` here) is `stats.node`. Each fetch returns the newest snapshot of cumulative counters. `totals.json` sums each tier's traffic and sessions, `publisher.json` is egress per broadcast path, `subscriber.json` is ingress, and `sessions.json` counts sessions per stats -label. A subscriber may also ask for `/traffic.json`, one broadcast +label. A subscriber may also ask for `/prefix.json`, one broadcast prefix rolled up with each child, produced only while held. Fetch twice and divide by the interval for a rate. The `.json.z` twins carry compressed patches, which these tools print as raw bytes. [Stats](/concept/stats) describes every field. diff --git a/doc/bin/relay/config.md b/doc/bin/relay/config.md index b76ef9e601c..ec0e06de39c 100644 --- a/doc/bin/relay/config.md +++ b/doc/bin/relay/config.md @@ -334,7 +334,7 @@ group of every track is always kept, even past `capacity`. [stats] enabled = true prefix = ".stats" # Broadcasts appear under /node/. -interval = 1 # Seconds between snapshots. +interval = "1s" # Time between snapshots. Default. node = "sjc/1" # Disambiguates relays sharing a cluster. depth = 1 # Also bucket by the first N path segments (per tenant). linger = "5m" # Keep an empty group's broadcast announced this long. Default. diff --git a/doc/concept/stats.md b/doc/concept/stats.md index 768e8bea138..18b429220e8 100644 --- a/doc/concept/stats.md +++ b/doc/concept/stats.md @@ -32,8 +32,8 @@ with unavailable transport measurements absent. Missing rendition counters mean zero, and JavaScript preserves omission. A known-zero gauge or transport measurement stays explicit, so it remains distinct from unavailable. -`moq import --stats` and `moq export --echo` report them from the -[CLI](/bin/cli#stats-and-feedback). An import counts the frames and payload +`moq import --report` and `moq export --echo` report them from the +[CLI](/bin/cli#reports-and-feedback). An import counts the frames and payload bytes it writes to each rendition, and video keyframes; an export counts what it reads and records its newest arrival. See the [hang draft](/draft/moq-hang#media-stats) for track framing, field units, and @@ -153,9 +153,9 @@ comes in two encodings: | `totals.json` | tier | [Totals](#totals) for the whole group | | `[/]publisher.json` | broadcast path | [Traffic](#traffic) this node sent (egress) | | `[/]subscriber.json` | broadcast path | [Traffic](#traffic) this node received (ingress) | -| `[/]sessions.json` | stats label | [Sessions](#sessions) connected now | -| `[