Repository navigation
feat(cli): report import stats and export feedback #5848
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
c95a662
feat(cli): report import stats and export feedback
t0ms 2c66df3
fix(cli): address review on the stats reporters
t0ms 58ffb52
fix(cli): refuse --stats with --epoch and give feedback an epoch
kixelated 65cf0cf
Merge remote-tracking branch 'origin/main' into pr-5848
kixelated 90c4fbf
chore(cli): format, and name the --echo value
kixelated eafd7df
Merge remote-tracking branch 'origin/main' into pr-5848
kixelated c97bc23
fix(cli): attach --stats where the import's pipeline is collected
kixelated 3bbadc0
Merge origin/main into quest/m2/stats/rust
t0ms 39fa8f5
docs(cli): drop --epoch from what refuses --stats
t0ms 7bc5705
fix(cli): bound what the report sinks hold
t0ms d3c4b72
fix(cli): report live renditions past the cap; read the root and hidd…
t0ms bf2d693
Merge remote-tracking branch 'origin/main' into takeover-5848
kixelated 4b1952a
fix(cli): evict one ended rendition at the cap and reap drained echo …
kixelated File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,58 +1,45 @@ | ||
| # [M] The Rust CLI, players, encoders, and remuxes report stats and feedback | ||
| # [M] The Rust player, encoders, and gateways report stats and feedback | ||
|
|
||
| ## Goal | ||
|
|
||
| - `moq import --stats` and `moq publish --stats` announce a stats track in | ||
| the catalog and fill it with what they send. | ||
| - `moq play` and `moq export`, given `--echo <name>`, publish an `.echo` | ||
| broadcast under each watched catalog's echo path and fill its feedback | ||
| track. | ||
| - `moq export stats <broadcast>` prints a broadcast's stats snapshots, and | ||
| `moq export echo <prefix>` prints the feedback of every `.echo` broadcast | ||
| under a prefix, as JSON lines. | ||
| - `moq import capture --stats` 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`, `rtc`) and `archive` take | ||
| `--stats`. | ||
|
|
||
| ## 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` | ||
| 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 | ||
| lands. | ||
| - Counters come from the source, per track, as cumulative `stats()` | ||
| snapshots: no callback, no per-frame lock. | ||
| - Publisher: the `moq-video` and `moq-audio` encode producers count frames, | ||
| bytes, keyframes, and drops. The `moq-mux` importers count the frames and | ||
| bytes they write per track. A remux never encodes, so without them the | ||
| CLI would have nothing to report for `moq import`. | ||
| - Publisher: the `moq-video` and `moq-audio` encode producers create their | ||
| tracks directly on the broadcast, so they count frames, bytes, keyframes, | ||
| and drops themselves, and expose the target bitrate. | ||
| - Viewer: the decode and render paths count received, decoded, late, | ||
| stalled, underruns, and errors. The `moq-mux` exporters count the frames | ||
| and bytes they receive per track, so `moq export --echo` reports a row | ||
| for each rendition it remuxes. `underruns` in | ||
| stalled, underruns, and errors. `underruns` in | ||
| `rs/moq-audio/src/playback` is already counted privately. | ||
| - `moq-cli` folds the counters into `hang::stats::Snapshot` on the stats | ||
| interval and writes it through `moq_json::snapshot`, with the `.z` sibling. | ||
| `transport` comes from the connection's `ConnectionStats`. | ||
| Decided in the quest audit: this quest owns generic per-rendition reporting; | ||
| [TS health stats](/quest/m2/ts-health-stats.md) owns serializing and flattening | ||
| TS container counters under `mpegts` in publisher stats and export `.echo`. | ||
| That integration stays in m2 so this quest does not duplicate its work. | ||
| - Feedback: after reading a catalog with an `echo` section, the player | ||
| resolves the echo path against the broadcast, appends `<name>.echo`, and | ||
| publishes there with the fixed feedback | ||
| track, keyed by the catalog's rendition IDs. Each catalog update | ||
| reconciles it: a removed `echo` section, a changed path, or no longer | ||
| watching unannounces the old broadcast. A name that is not a single path segment is refused at | ||
| parse time. | ||
| - A viewer given `--echo` with `--catalog-format msf` refuses: the MSF | ||
| catalog does not carry an `echo` solicitation. Imports always emit the | ||
| MSF catalog beside hang, omitting `stats` and `echo` from MSF. | ||
| - `moq export stats` and `moq export echo` are sinks that skip `.hang` media | ||
| discovery, so they route around `catalog_format`. | ||
| - `doc/bin/cli.md` documents the flags and sinks. | ||
| - The media test publishes with `--stats` and plays with `--echo` against a | ||
| publisher that solicits feedback. It asserts that the publisher's frame | ||
| count matches what was sent and that the viewer's newest arrival advances. | ||
| - The gateways build their catalogs in their own crates, so each needs a way | ||
| to name the stats track before its first catalog. | ||
| - `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 | ||
| 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 | ||
| `--echo` when it adds one: they would publish rendition IDs and per-track | ||
| counters in plaintext beside it. | ||
|
|
||
| ## Related | ||
|
|
||
| - [TS health stats](/quest/m2/ts-health-stats.md) - adds TS-specific counters after this generic reporting plumbing lands | ||
| - [TS health stats](/quest/m2/ts-health-stats.md) - adds TS-specific counters to the reports | ||
| - [Encrypted native CLI](/quest/m2/e2ee/cli.md) - refuses stats and feedback on an encrypted broadcast |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.