DSH plugin session telemetry: capture, sharing, redaction
The hard part of telemetry is not wiring it up, but discovering afterwards that you exported what should never leave. DSH plugin splits capture, redaction, and handoff into three stages: the capture service normalizes records, the waterfall redacts, and the backend receives a processed copy. Misread any stage and the export side keeps the evidence.
Five fields, sharply separated duties
SessionTelemetryRecord has few fields because each one carries exactly one responsibility.(source)
sourceEvent— a normalized envelope without data; the payload lives in separately redactedbody. Operational records omit this field.channel—ledger(a session log mirror) orops(operational signals); backends place them in different instrumentation scopes.time— Unix milliseconds. Ledger uses the source event's append time; ops uses emit time.severity— a pre-mapped alert level decided at capture time.attributes— deliberately minimal identity attributes.body— the full payload, immutable after handoff.
The severity mapping is worth memorizing: if the event's own outcome flag says it is an error — a tool message's isError, a turn/end error reason, an agent-error operational record — it maps to error; other captured events default to info; warn is reserved for session-telemetry/record policies and backends.
Attributes have firm boundaries too: ledger records carry session.id, session.format_version, event.type, event.seq, optional session.cwd and session.parent_id, plus session.seed_length for seeded sessions. Ops records carry telemetry.op and session.id, with agent-error adding agent.id, turn, step, and error.name. Anything recoverable from body is deliberately not repeated in attributes.
ledger and ops are two channels with different dedup
One mirrors the log, the other raises alerts — do not consume them with the same assumptions.(source)
Every authoritative session event passes through as one ordered ledger record, including each assistant/message or assistant/attempt carrying its full compact stream, and types merged in by plugins that this seam has never heard of. Process-local agent/assistant-stream frames never enter the durable feed.
Boundary semantics are just as explicit: a new fork starts at the child session's own suffix, including inheritance markers and the fork end event; a resumed Session starts after the stored prefix, resumed forks included; a backend may opt into includeHistory to cover the full prefix; and re-adopting the same object continues after the handoff cursor.
Best-effort delivery means exactly that: the cursor marks handoff, not arrival. Records can be lost (crashes, reload windows) and can repeat (new-object replay, SDK retries). Receivers therefore dedupe ledger records by (session.id, session.format_version, event.seq). Ops records deliberately omit such identifiers — they are alert signals, not additive entries, and duplication is tolerated rather than reconciled.
sharing describes deployment policy, not delivery receipts
sharing answers "how much may this deployment export," not "did this record arrive."(source)
Each backend exposes a deployment-level mode through the required abstract sharing member on ctx.sessionTelemetry:
type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
Two clarifications matter: it is neither a per-session admission decision nor a delivery receipt, and the confirmation text from /feedback never consults it. So do not treat sharing as proof that a given record was reported.
The feedback side carries its own ownership facts: the feedback backend authorizes the session prefix and owns an independent queue, per-request scheduling, and a 4,000,000-byte limit. That cap belongs to the feedback backend, not to the capture service.
Capture policy: live versus on-demand
The two capture modes differ in when the log is read, not in how much data exists.(source)
type SessionTelemetryCapture = 'live' | 'on-demand'
capture defaults to live, following live events; on-demand waits for an explicit capture before reading the authoritative log. includeHistory defaults to false and allows stored and inherited records to be captured, but it does not itself authorize capture — two switches, two jobs, and neither substitutes for the other.
The OTel backend uses on-demand capture and requires new explicit feedback of its own; it releases only the complete prefix up to that feedback, and the rule applies to every provider. That explains "historical sessions never show up after wiring OTel": without explicit feedback, no prefix is released.
Backend contract: emit must not block
Only emit is required, and it must be a non-blocking enqueue.(source)
emit(record)— hands a record to the backend pipeline. The coordinator calls it synchronously from thesession/eventhot path, so anything slower than a queue push drags the agent loop. Errors thrown here are caught and logged by the coordinator and never return to the loop.flush()— an optional end-of-turn hint, fire and forget. Most backends should omit it and let the SDK's own batching decide export timing; implement it and you own its concurrency withshutdown()draining, which is why the OTel backend does not.shutdown()— forwards fiber destruction to the SDK: drain queues and reach quiescence. Anything emitted before the call must still be delivered, including records queued while aflushhint is in progress; the coordinator emits the shutdown marker immediately before calling it. Dispose awaits it, a rejection is logged as a warning, and app teardown never fails because of it.
Two assembly constraints remain: only one implementation per context, with duplicate loading throwing; and a backend wires its capture side by composing SessionTelemetryCoordinator in its own constructor. On-demand capture creates no ops records.
The redaction waterfall: no rules means no redaction
The seam ships no rules; export cleanliness depends entirely on what you attach.(source)
Every record passes the session-telemetry/record waterfall between the authoritative event copy and emit(). Four stacking rules:
- Stack by transforming the
next()result — listeners wrap layer by layer, and the innermost one passes the record through. - Returning without calling
next()replaces everything beneath — that is a short circuit, not an append. - Throwing withholds that record — fail-closed inside the coordinator's isolation boundary, never reaching the agent loop.
- Only exported copies are affected — the authoritative session log is never rewritten.
Dispatch timing depends on the mode: live capture dispatches synchronously on append, while on-demand capture dispatches when the authoritative log is read. The record is already the coordinator's deep copy, so listeners must return a new record and never mutate in place.
In practice this gives you control over redaction order: attach field-level masking first, whole-record dropping second, and backend adaptation last. Reverse that order and a masked field can be rebuilt underneath.
Verification: sensitive fields and repeated delivery
Telemetry verification must cover both exported content and duplicate consumption.(source)
- Attach a waterfall listener that only rewrites
bodyand assert the backend receives the rewritten value. - Attach a listener that returns without calling
next()and assert lower logic is replaced, not stacked. - Attach a throwing listener and assert the record is withheld while the agent loop is unaffected.
- Replay the same log twice and assert the receiver's count is unchanged after dedup by
(session.id, session.format_version, event.seq). - With
sharingset tofeedback-only, verify you never read a/feedbackconfirmation as proof of afulldelivery. - Queue a record during a
flushhint beforeshutdown()and assert it is still delivered.
For the overall integration, compare OTel observability and the session telemetry overview; the full event vocabulary behind those records lives in derived messages.
One line to close: ledger mirrors the log while ops only signals, the cursor means handoff, sharing is deployment policy, redaction comes from the waterfall you attach, and it touches exported copies only.
FAQ
No. DSH plugin states that exported data never enters model requests. Telemetry travels the export channel, and the authoritative session log is never rewritten by redaction, which touches only exported copies.
No. DSH plugin's cursor marks handoff only. Delivery is best effort, so records may be lost during crashes or reload windows and duplicated by object replay or SDK retries, so receivers dedupe by event identity.
Ledger records dedupe by session identity plus event sequence; ops records do not. DSH plugin deliberately omits the sequence from ops records because they are alert signals, not additive entries.
No. DSH plugin's waterfall carries no rules of its own. Without listeners the record reaches the backend unchanged, so export cleanliness depends entirely on what the deployment attaches.
Related Terms
- SessionTelemetryRecord
- SessionTelemetryRecord is the logical record handed to a backend: sourceEvent, channel, time, severity, attributes, and body.— packages/session/session-telemetry/src/index.ts
- ledger
- ledger is the telemetry channel mirroring the session log, one ordered record per authoritative event, deduplicable by event identity.— packages/session/session-telemetry/src/index.ts
- ops
- ops is the operational signal channel carrying agent-error and shutdown records with no log home, deliberately omitting event sequence.— packages/session/session-telemetry/src/index.ts
- session-telemetry/record
- session-telemetry/record is the waterfall every exported record passes; transform the next() result to stack, skip next to replace everything beneath.— packages/session/session-telemetry/src/index.ts
Sources
- DeepSeek Harness reference - Session telemetry· deepseek-ai
- packages/session/session-telemetry/src/index.ts· deepseek-ai