Crate moq_stats 

Publish and consume MoQ traffic stats.

moq-net collects per-session traffic counters in a stats::Registry; this crate turns that registry into MoQ broadcasts and back:

• Producer drains a registry on an interval and publishes the counters as JSON tracks on an origin.
• Consumer subscribes to one published stats broadcast and yields typed frames, for aggregators, dashboards, and billing meters.

Wire format

A Producer publishes one broadcast per node at <prefix>/node/<node> (default prefix .stats; the node suffix disambiguates relays sharing a cluster origin and may be multi-segment, e.g. sjc/1). A grouping depth splits that into one broadcast per leading broadcast-path segments at <prefix>/<group>/node/<node>, so a consumer can announce-scope to a single group. Parse announce paths back with parse_node_path.

Traffic is bucketed by Tier (an arbitrary label chosen by business logic: billing class, region, …). The default tier is unprefixed; a named tier prefixes its track names with its label. Each broadcast carries, per tier, a publisher (egress) and a subscriber (ingress) traffic track plus a sessions track, each in a plain and a compressed flavor:

• publisher.json / subscriber.json: each frame is a JSON object mapping broadcast path to a cumulative Traffic snapshot (TrafficFrame), one full snapshot per frame.
• sessions.json: each frame maps auth root to a cumulative Presence gauge (SessionsFrame), counting connected sessions regardless of data flow.
• <name>.json.z: a compressed sibling of each of the above, encoded with moq_json::snapshot (group-scoped DEFLATE plus RFC 7396 merge-patch deltas). Since successive stats frames are nearly identical, this is a fraction of the plain track’s bytes; read it with Consumer (or moq_json directly), not as raw JSON frames.

Named-tier tracks (<tier>/publisher.json, …) are created the first time traffic records under that label; default-tier tracks always exist and hold {} while idle. Compute names with traffic_track / sessions_track.

An entry appears in a frame while it is live (an open counter still exceeds its *_closed counterpart, so traffic could resume at any moment) or on the tick its snapshot changed, then is dropped once fully closed. Counters are cumulative and monotonic: a downstream aggregator computes rates from successive snapshots, and a counter going backwards means the relay restarted or the entry was garbage collected and re-created, so consumers should treat a decrease as a fresh segment.

Structs

Consumer

Reads one published stats broadcast (a <prefix>/node/<node> announce), yielding typed frames per track.

ConsumerConfig

Configuration for a Consumer. Construct with ConsumerConfig::new and chain the with_* setters.

Handle

Counter collection, re-exported from moq_net::stats so stats consumers can depend on this crate alone. Tier-scoped wrapper around Registry. What crate::Client::with_stats and crate::Server::with_stats accept. Cheap to clone.

NodePath

A parsed stats broadcast path: <prefix>[/<group>]/node[/<node>]. See parse_node_path.

Presence

Counter collection, re-exported from moq_net::stats so stats consumers can depend on this crate alone. Connected-session presence for one slice (an auth root on a tier, or any sum of such slices): cumulative connects and disconnects. sessions - sessions_closed is the current live session count.

Producer

Publishes a Registry’s counters as stats broadcasts. Cheap to clone.

ProducerConfig

Settings for a Producer. Construct with ProducerConfig::new and chain the with_* setters (e.g. ProducerConfig::new().with_origin(origin).with_prefix(".foo")), then hand it to Producer::new.

Registry

Counter collection, re-exported from moq_net::stats so stats consumers can depend on this crate alone. Counter collection registry. Cheap to clone (Arc inside for the shared state). One instance per relay; sessions get tier-scoped handles via Registry::tier. The moq-stats crate drains it with Registry::report to publish the counters as MoQ broadcasts.

SessionsConsumer

A typed reader over one sessions track; see TrafficConsumer.

Tier

Counter collection, re-exported from moq_net::stats so stats consumers can depend on this crate alone. Traffic-class label that selects which counter set a session’s bumps record in, so a single Registry can split customer-facing, cluster-peer, regional, etc. traffic. Each tracked broadcast keeps a per-tier counter set on both its publisher and subscriber sides.

Traffic

Counter collection, re-exported from moq_net::stats so stats consumers can depend on this crate alone. A cumulative traffic counter readout for one slice (a broadcast on a (tier, role), or any sum of such slices).

TrafficConsumer

A typed reader over one traffic track. Yields the latest TrafficFrame; intermediate frames a slow reader missed are collapsed, which is safe because the counters are cumulative.

Enums

Error

Errors produced while publishing or consuming stats.

Role

Counter collection, re-exported from moq_net::stats so stats consumers can depend on this crate alone. Publisher (egress) vs subscriber (ingress) side of a broadcast, used as a label on a Snapshot traffic row. The internal bump paths track the side statically, so this only surfaces on the aggregate read side.

Constants

COMPRESSED_SUFFIX

Suffix appended to a plain track name for its compressed sibling.

Functions

parse_node_path

Parse a stats broadcast announce path published under prefix with the given grouping depth, splitting it into its group and node parts.

sessions_track

The sessions track name for a tier: sessions.json on the default tier, <tier>/sessions.json on a named one, plus COMPRESSED_SUFFIX when compressed.

traffic_track

The traffic track name for a tier and role: <role>.json at the prefix root on the default tier (publisher.json / subscriber.json), <tier>/<role>.json on a named one, plus COMPRESSED_SUFFIX when compressed.

Type Aliases

Result

A Result using this crate’s Error.

SessionsFrame

One frame off a sessions track: connect/disconnect gauges keyed by auth root.

TrafficFrame

One frame off a traffic track: cumulative counters keyed by broadcast path.