Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 8 additions & 15 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down Expand Up @@ -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 <name>` answers a publisher that solicits feedback: under the
Expand All @@ -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
```
Expand Down
2 changes: 1 addition & 1 deletion doc/bin/inspect.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<path>/traffic.json`, one broadcast
label. A subscriber may also ask for `<path>/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.
2 changes: 1 addition & 1 deletion doc/bin/relay/config.md
Original file line number Diff line number Diff line change
Expand Up @@ -334,7 +334,7 @@ group of every track is always kept, even past `capacity`.
[stats]
enabled = true
prefix = ".stats" # Broadcasts appear under <prefix>/node/<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.
Expand Down
20 changes: 10 additions & 10 deletions doc/concept/stats.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -153,9 +153,9 @@ comes in two encodings:
| `totals.json` | tier | [Totals](#totals) for the whole group |
| `[<tier>/]publisher.json` | broadcast path | [Traffic](#traffic) this node sent (egress) |
| `[<tier>/]subscriber.json` | broadcast path | [Traffic](#traffic) this node received (ingress) |
| `[<tier>/]sessions.json` | stats label | [Sessions](#sessions) connected now |
| `[<label>/]presence.json` | tier | [Sessions](#sessions) under one stats label |
| `[<path>/]traffic.json` | tier | [Prefix](#prefix) traffic under one broadcast prefix |
| `[<tier>/]sessions.json` | stats label | [Presence](#presence): sessions connected now |
| `[<label>/]presence.json` | tier | [Presence](#presence): sessions under one stats label |
| `[<path>/]prefix.json` | tier | [Prefix](#prefix) traffic under one broadcast prefix |

The default tier's per-tier tracks are unprefixed. A named tier prefixes each
name with its label and a slash: tier `region/sjc` publishes
Expand All @@ -173,7 +173,7 @@ for any stats label in the group (`presence.json` for the empty label). The rela
answers with the label's current sessions and counts from there, holding a label
with no sessions open at `{}`, and stops producing it once the last subscriber
leaves. A prefix track works the same way for any broadcast prefix in the
group: ask for `<path>/traffic.json` (`traffic.json` for the empty prefix). A
group: ask for `<path>/prefix.json` (`prefix.json` for the empty prefix). A
label or prefix outside the group, or any other name, is refused.

## Frames
Expand All @@ -186,7 +186,7 @@ writes only when a track's frame changed, so silence means nothing moved, not
that the producer is gone. The track ends when the producer does, or at
depth 1 or more when its group's broadcast is unannounced; the group may
return later as a new broadcast. A frame too large to cache (32 MB) ends its
track with a `FrameTooLarge` error. The `.z` flavor meets the same limit by its
track with a `FRAME_TOO_LARGE` error. The `.z` flavor meets the same limit by its
uncompressed size, since a reader inflates the whole group.

### Totals
Expand All @@ -200,7 +200,7 @@ uncompressed size, since a reader inflates the whole group.

Each tier that recorded anything in the group's epoch, with its egress
(`publisher`) and ingress (`subscriber`) [Traffic](#traffic) and its
[Sessions](#sessions), summed over every broadcast and stats label in the group.
[Presence](#presence), summed over every broadcast and stats label in the group.
Unlike the per-path tracks, an entry that ends stays counted, so the next
frame always carries everything since the epoch began: a reader that misses
frames loses nothing while the group stays announced. Billing reads this
Expand All @@ -220,7 +220,7 @@ zero; the totals keep what it counted. A sessions entry appears while a
session or HTTP request holds its context and on the tick its last one ends. While a group
lingers empty, these tracks hold `{}`.

### Presence
### Per-label tracks

A presence track's entries are cumulative from when it was first held: a
session that ends stays counted, and so does every one after it, while
Expand Down Expand Up @@ -300,7 +300,7 @@ The last six fields are legacy spellings of the `*_started` and `*_ended`
counters, still written so an older consumer reads a newer relay. A reader
should prefer the canonical name and fall back to the legacy one.

### Sessions
### Presence

```json
{
Expand Down
1 change: 0 additions & 1 deletion quest/m1/api-audit/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,6 @@ Rejected in planning:
- [One decode read](/quest/m1/api-audit/decode-read.md) - audio and video decoders yield the same `Frame`, `Gap`, `End` read as moq-mux containers
- [Watch and publish trim](/quest/m1/api-audit/watch-trim.md) - the clock is re-exported, unused watch outputs are gone, and derived publish state is read-only
- [Media surface trim](/quest/m1/api-audit/media-trim.md) - media crate items with no consumer go private, and Rust/JS media names agree
- [Stats names](/quest/m1/api-audit/stats-naming.md) - each stats track and reader has one name, and "stats" means one thing in the CLI
- [CLI and gst flags](/quest/m1/api-audit/cli-flags.md) - one flag name per meaning across CLI subcommands and gst elements, and `linger` means one thing
- [qmux shape](/quest/m1/api-audit/qmux-shape.md) - qmux binds framing at connect, shares flow-control names with moq-tokio, and JS drops the legacy wire
- [Transport config](/quest/m1/api-audit/transport-config.md) - moq-tokio and moq-quic configs have one meaning for unset, enums for modes, no order-dependent setters, and no leftover features
Expand Down
41 changes: 0 additions & 41 deletions quest/m1/api-audit/stats-naming.md

This file was deleted.

4 changes: 2 additions & 2 deletions quest/m2/e2ee/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,8 +19,8 @@ Existing plaintext commands remain the default; an explicit application credenti
existing selection, and suppress every plaintext Hang or MSF catalog
representation.
- Refuse any path that hands an encrypting publisher an epoch it did not mint, before connecting (maintainer, 2026-10-08): a shared epoch repeats AES-GCM nonces. `moq` has no `--epoch` flag.
- Refuse `--stats` and `--echo` together with a credential: they would publish rendition IDs and per-track counters in plaintext beside the protected broadcast. This quest owns the refusal (decided 2026-10-08), since the stats quests have no encrypted mode to refuse until this credential exists.
- Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, `--stats` or `--echo` with a credential refused, clean authentication errors, and both lite and IETF transports.
- Refuse `--report` and `--echo` together with a credential: they would publish rendition IDs and per-track counters in plaintext beside the protected broadcast. This quest owns the refusal (decided 2026-10-08), since the stats quests have no encrypted mode to refuse until this credential exists.
- Cover native audio/video publication and playback, late subscription, a restarted publisher under a new epoch, `--report` or `--echo` with a credential refused, clean authentication errors, and both lite and IETF transports.

## Required

Expand Down
2 changes: 1 addition & 1 deletion quest/m2/qos-lag-dashboard.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ and per node like the existing counters.
## Plan

- Read both from the stats totals and prefix tracks
(`<path>/traffic.json`) rather than the `publisher.json` rows they sit on today (decided in the
(`<path>/prefix.json`) rather than the `publisher.json` rows they sit on today (decided in the
2026-10-06 audit; the rows stay for existing readers, 2026-10-12); [viewer lag histogram](/quest/m2/qos/lag-histogram.md)
lands them on the egress side of its per-group totals and prefix tracks
(decided 2026-10-08). `lag` is a cumulative byte count per bucket keyed
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/qos-publisher-timeliness.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Document the window length beside the bucket edges.

Aggregate as a byte-weighted cumulative histogram of drift on the ingress
(`Role::Subscriber`) side of the stats totals and prefix tracks
(`<path>/traffic.json`) rather than the per-path rows (decided in the 2026-10-06 audit), with the same
(`<path>/prefix.json`) rather than the per-path rows (decided in the 2026-10-06 audit), with the same
bucket edges and the same monotonic contract as the egress `lag` histogram. Beside it keep two cumulative
counters: `timestamp_regressions`, frames whose timestamp is below the
previous group's newest timestamp, and `stalls`, gaps between complete frames
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/qos/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ The per-broadcast verdict combining client reports, the relay's starvation,
and publisher timeliness lives downstream. This line only reports the
counters.

Decided (2026-10-06 audit): stats prefix tracks (`<path>/traffic.json`)
Decided (2026-10-06 audit): stats prefix tracks (`<path>/prefix.json`)
landed first in #5811, since they are a prerequisite of the lag API; the lag
histogram was deferred to m2 by the maintainer on 2026-10-15 and lands on the
stats totals and
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/qos/lag-histogram.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The relay's `moq-stats` egress side reports, per broadcast, how far behind
its viewers are according to what the network has acknowledged: a
byte-weighted cumulative `lag` histogram and `dropped` counters (duration,
bytes, and groups dropped before they were acknowledged), on the stats totals
and prefix tracks (`<path>/traffic.json`). A spliced subscription
and prefix tracks (`<path>/prefix.json`). A spliced subscription
stays exact across a route switch, and a closing subscription records its
last partial interval.

Expand Down
14 changes: 7 additions & 7 deletions quest/m2/stats/rust.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,23 +2,23 @@

## Goal

- `moq import capture --stats` announces a stats track in the catalog and
- `moq import capture --report` announces a stats track in the catalog and
fills it with what its encoders send, `skipped` and `bitrate` included.
- `moq play`, given `--echo <name>`, publishes an `.echo` broadcast under each
watched catalog's echo path and fills its feedback track with what it
received, decoded, and played.
- The gateway imports (`hls`, `rtmp`, `srt`, `rtsp`, `rtc`) and `archive` take
`--stats`.
`--report`.
- `moq import --echo-path <path>` solicits feedback: it sets the catalog's
`echo` section, named apart from the viewer's `--echo <name>`.

## Plan

- `moq import --stats` for the stdin imports, `moq export --echo`, and the
`export stats` and `export echo` sinks already report what the `moq-mux`
- `moq import --report` for the stdin imports, `moq export --echo`, and the
`export report` and `export echo` sinks already report what the `moq-mux`
importers write and exporters read (`rs/moq-mux/src/stats.rs`,
`rs/moq-cli/src/report.rs`). This quest adds the counters they lack and
reuses the rest; `import --stats` refuses capture and the gateways until it
reuses the rest; `import --report` refuses capture and the gateways until it
lands.
- Counters come from the source, per track, as cumulative `stats()`
snapshots: no callback, no per-frame lock.
Expand All @@ -33,11 +33,11 @@
- `moq play --echo` reconciles each watched catalog's `echo` section as
`export --echo` does, and refuses `--catalog-format msf` the same way: the
MSF catalog does not carry an `echo` solicitation.
- The media test captures with `--stats` and plays with `--echo` against a
- The media test captures with `--report` and plays with `--echo` against a
publisher that solicits feedback. It asserts the encoder's frame count and
that the player's newest arrival advances.
- Decided 2026-10-08: no E2EE refusal here. The CLI has no encrypted
broadcast yet, so [Encrypted native CLI](/quest/m2/e2ee/cli.md) refuses `--stats` and
broadcast yet, so [Encrypted native CLI](/quest/m2/e2ee/cli.md) refuses `--report` and
`--echo` when it adds one: they would publish rendition IDs and per-track
counters in plaintext beside it.

Expand Down
2 changes: 1 addition & 1 deletion quest/m3/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ m4's upstream waits in here and moved m2 work with no consumer.
- [ID3 catalog section](/quest/m3/id3.md) - timed ID3 as a first-class container-neutral catalog section
- [FLV script tags](/quest/m3/flv-script.md) - onMetaData and AMF data messages survive RTMP and FLV import
- [Half and quarter rate AC-3](/quest/m3/ac3-low-rate.md) - bsid 9 and 10 AC-3 parse through TS and FLV instead of being refused
- [MSF feedback tracks](/quest/m3/msf-publish-tracks.md) - `--stats` and `--echo` work under `--catalog-format msf` through `publishTracks`, once a consumer asks
- [MSF feedback tracks](/quest/m3/msf-publish-tracks.md) - `--report` and `--echo` work under `--catalog-format msf` through `publishTracks`, once a consumer asks
- [MSFTS convergence](/quest/m3/msfts-convergence.md) - the demultiplexed TS lane converges on MSFTS where they differ, once an MSFTS implementer engages
- [#2279](/quest/m3/2279-hang-typed-scte-35-ad-cue-signaling-carried-opaquely.md) - hang: SCTE-35 cues arrive immediately on an independent metadata track, optionally associated with a rendition
- [CEA-608/708](/quest/m3/captions-cea.md) - captions carried inside video SEI become a real text rendition at import
Expand Down
2 changes: 1 addition & 1 deletion quest/m3/msf-publish-tracks.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

## Goal

`--stats` and `--echo` work under `--catalog-format msf`: a soliciting
`--report` and `--echo` work under `--catalog-format msf`: a soliciting
catalog's `echo` maps onto an MSF `publishTracks` entry (draft-ietf-moq-msf
§5.1.5), and a viewer publishes the hang `.echo` snapshot there. Start once a
consumer asks.
Expand Down
Loading
Loading