Module telemetry 

Pipeline telemetry — per-response event capture for adaptive tuning.

The pipeline emits one PipelineEvent per tool-result it handles. Events are anonymized by construction: no raw response text, no tool arguments, no user-facing strings leave this module. The schema carries just enough signal to drive the tuning rules described in docs/research/paper-2-mckp-format-adaptive.md §Adaptive Configuration.

Design

• Sink trait — TelemetrySink abstracts persistence. Default impl JsonlSink appends one JSON line per event to a per-session file; alternate impls can stream to stdout, discard for tests, or forward to an in-process aggregator.
• Zero-cost when disabled — sinks are dyn-dispatched via an Option<Arc<dyn TelemetrySink>>; setting None eliminates all per-call allocation.
• Append-only, crash-safe — JsonlSink opens with O_APPEND; no in-memory buffering beyond the default kernel write buffer.
• Schema additions only — PipelineEvent is non_exhaustive; downstream analyzers project specific fields.

Example

use std::sync::Arc;
use devboy_format_pipeline::telemetry::{
    JsonlSink, PipelineEvent, Shape, Layer, TelemetrySink,
};

let sink: Arc<dyn TelemetrySink> =
    Arc::new(JsonlSink::open("/tmp/devboy-telemetry/sess_abcd.jsonl").unwrap());

// PipelineEvent is #[non_exhaustive]; construct via Default + mutation.
let mut evt = PipelineEvent::default();
evt.session_hash = "abcdef01".into();
evt.tool_call_id_hash = "feed1234".into();
evt.tool_name_anon = "Read".into();
evt.endpoint_class = "Read".into();
evt.response_chars = 1234;
evt.shape = Shape::NumberedList;
evt.content_sha_prefix_hex = "0123456789abcdef".into();
evt.file_path_hash = Some("abc12345".into());
evt.layer_used = Layer::L3;
evt.tokens_baseline = 308;
evt.tokens_final = 308;
evt.ts_ms = 1_700_000_000_000;

sink.record(&evt).unwrap();

Structs

EnrichmentEffectiveness

Aggregate scoring of how well the Paper 3 enrichment planner served the agent during a session. Populated by the live pipeline (counters) plus the offline post-pass (cited_* numbers, see P-3-08).

JsonlSink

Append-only JSONL sink backed by a single file.

MemorySink

In-memory sink for unit tests — retains events for assertion.

NullSink

No-op sink for tests and for code paths where telemetry is explicitly disabled. Always returns Ok; records nothing.

PipelineEvent

Single pipeline decision — emitted once per tool-result.

SessionSummary

Session-level roll-up written on session close.

Enums

Layer

Which pipeline layer produced the terminal decision for this response.

Shape

Structural classification of a tool response.

TelemetryError

Traits

TelemetrySink

Persistence backend for telemetry events and summaries.

Type Aliases

Result