Module obs

Available on crate feature tracker only.

Expand description

Observability hooks — metrics counters and tracing events.

Two independent feature gates:

metrics — emits Prometheus / OpenTelemetry-style counters, gauges, and histograms via the metrics crate. Behind a MetricRecorder install (handled by the consumer), the counters end up wherever the recorder routes them.
tracing — emits structured events at flow-lifecycle transitions via the tracing crate.

Both are zero-cost when off (every entry point is a no-op #[inline(always)] stub).

§Metric vocabulary

Metric	Type	Labels
`flowscope_flows_created_total`	counter	`l4` (`tcp`/`udp`/`other`)
`flowscope_flows_ended_total`	counter	`reason` (`fin`/`rst`/`idle`/`evicted`/`buffer_overflow`)
`flowscope_flows_active`	gauge	—
`flowscope_packets_unmatched_total`	counter	—
`flowscope_bytes_total`	counter	`side` (`initiator`/`responder`)
`flowscope_flow_duration_seconds`	histogram	—
`flowscope_flow_packets`	histogram	—
`flowscope_flow_bytes`	histogram	—
`flowscope_anomalies_total`	counter	`kind` (`buffer_overflow`/`ooo_segment`/`flow_table_eviction`)
`flowscope_reassembly_dropped_ooo_total`	counter	`side`
`flowscope_reassembly_bytes_dropped_oversize_total`	counter	`side`

All label values are &'static str enums. Never pass a flow key as a label value — that creates one time series per flow.

METRIC_ANOMALIES: flowscope_anomalies_total{kind=...} — counter of anomaly events emitted by FlowDriver when with_emit_anomalies(true).
METRIC_BYTES: flowscope_bytes_total{side=...} — total bytes per side (cumulative across all ended flows).
METRIC_FLOWS_ACTIVE: flowscope_flows_active — gauge of live flows in the tracker.
METRIC_FLOWS_CREATED: flowscope_flows_created_total — incremented on every new flow.
METRIC_FLOWS_ENDED: flowscope_flows_ended_total — incremented on every Ended event.
METRIC_FLOW_BYTES: flowscope_flow_bytes — histogram of per-flow byte totals.
METRIC_FLOW_DURATION_SECONDS: flowscope_flow_duration_seconds — histogram of per-flow durations.
METRIC_FLOW_PACKETS: flowscope_flow_packets — histogram of per-flow packet counts.
METRIC_PACKETS_UNMATCHED: flowscope_packets_unmatched_total — counter of packets the extractor couldn’t classify.
METRIC_REASSEMBLER_HIGH_WATERMARK: flowscope_reassembler_high_watermark_bytes{side=...} — histogram of peak buffer occupancy per ended flow.
METRIC_REASSEMBLY_BYTES_DROPPED_OVERSIZE: flowscope_reassembly_bytes_dropped_oversize_total{side=...} — cumulative bytes dropped due to per-side buffer cap.
METRIC_REASSEMBLY_DROPPED_OOO: flowscope_reassembly_dropped_ooo_total{side=...} — cumulative out-of-order segment drops.