Files

T

kingwl e6a8ff2621 fix(telemetry): review fixes — flush/shutdown ordering, session retirement, whole-exporter passthrough

Three review findings, each pinned by a red test first:

- The OTel backend retains the latest turn-boundary flush promise and
  shutdown() awaits it before provider.shutdown(): the SDK's
  concurrent-flush guard makes the shutdown-internal flush return early
  while one is in flight, silently dropping everything enqueued after
  the flush snapshot (including the coordinator's dispose-time shutdown
  markers).
- The coordinator retires sessions from the adopted set on
  session/disposed (mirroring the persistence coordinator): a long-lived
  backend no longer retains closed sessions and their event logs, and
  final unload no longer stamps shutdown markers for dead sessions.
- The exporter config passes through whole to OTLPLogExporter and its
  type/JSDoc now advertise the full OTLPExporterNodeConfigBase shape:
  rebuilding url/headers only silently dropped documented SDK options
  (timeoutMillis, compression, keepAlive, ...).

2026-07-25 03:20:29 +08:00

3.6 KiB

Raw Blame History

@deepseek-ai/dsh-session-telemetry-otel

The OpenTelemetry backend for the telemetry seam — the only entry a deployment loads. It composes the OTel JS SDK as-is (LoggerProvider → BatchLogRecordProcessor → OTLP/HTTP log exporter) and maps each record the seam hands over onto logger.emit(), under two instrumentation scopes: ledger records on @deepseek-ai/dsh-session-telemetry-otel, operational records on @deepseek-ai/dsh-session-telemetry-otel/ops. Resource identity (service.name/service.version) comes from dsh-llm's APP_IDENTITY, the same source the attribution headers use.

Config

- id: telemetry-otel
  name: '@deepseek-ai/dsh-session-telemetry-otel'
  config:
    exporter:                # passed verbatim to the SDK's OTLP/HTTP log exporter
      url: https://collector.example.com/v1/logs
      headers:
        authorization: !!js `Bearer ${process.env.OTLP_TOKEN}`
    processor: {}            # optional; passed verbatim to BatchLogRecordProcessor

exporter.url is the one field this package validates itself — required, no default, must parse as http(s) — so a missing endpoint fails at plugin load. Everything else is the SDK's option shape, owned and documented by the SDK, and both blocks pass through whole: every OTLPExporterNodeConfigBase field (headers, timeoutMillis, compression, keepAlive, …) reaches the exporter, and batching, retry, queue bounds, and loss policy under sustained failure are the SDK's documented behavior, tuned through the processor passthrough. Removing this block from cordis.yml is the opt-out: no residual state, no enabled flag.

What leaves the machine

Records carry the complete event.data as the seam's telemetry/redact waterfall returns it — user and assistant message content, tool arguments and results (command output, file contents), the full system prompt and tool schemas (request/header), todo text, compaction summaries, hook stderrSummary, and the session cwd (a local path). The seam ships no redaction rules: with no telemetry/redact listener mounted, that is the raw captured copy, so a deployment exporting beyond a trusted boundary mounts its own rules (see the seam README). Provider credentials never appear regardless: adapter API keys are constructor parameters, not session events, so they are structurally absent from the log and therefore from telemetry.

Field mapping

Seam record → SDK log record: time → timestamp/observedTimestamp; severity → severityNumber/severityText (INFO 9 / WARN 13 / ERROR 17); body → the structured log body; attributes verbatim. Receivers dedupe on (session.id, event.seq), alert on severity, and detect crashes by shutdown-record staleness (a session with activity, no shutdown ops record, gone stale ended uncleanly).

Model Experience

None, as the backend only forwards the seam's redacted records into the OTel SDK pipeline; it never contributes to a model request.

KV Cache effect

None; this package neither assembles nor sends a provider request.

Known Limitations and Deferred Work

Upstream experimental tree — @opentelemetry/sdk-logs is still published from the upstream experimental tree; SDK API churn lands here and only here — the seam contract does not move.
No live-collector coverage — every test exports to a local mock collector; the keyless Loader-composition e2e (tests/loader-composition.e2e.ts) covers the wire shape on every run, and behavior against a real OTLP deployment (auth, TLS, throttling) is the SDK exporter's documented territory.

3.6 KiB Raw Blame History