@dawei008/dsh-session-telemetry-otlp-trace

English | 中文

OpenTelemetry GenAI trace provider for the DSH session telemetry service. It projects each turn into an invoke_agent root span, each model call into a chat <model> child span, and each tool execution into an execute_tool <name> child span, then exports OTLP/HTTP traces without depending on an observability vendor.

This is a standalone extraction of the DeepSeek Harness trace plugin.

Install

pnpm add github:dawei008/dsh-session-telemetry-otlp-trace

The host DeepSeek Harness supplies the DSH and Cordis peer dependencies. Some DSH internal packages are not published to npm, so this repository commits the verified JavaScript and type declarations required for direct GitHub installs. The TypeScript source and OTLP wire tests are retained for review; run those tests from a compatible DeepSeek Harness checkout.

Configuration

This package and @deepseek-ai/dsh-session-telemetry-otel provide the same sessionTelemetry service, so a profile enables exactly one. An explicit exporter URL is the full OTLP /v1/traces URL. When it is omitted, the plugin follows the standard OTEL_EXPORTER_OTLP_TRACES_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT environment variables.

- id: session-telemetry-otel
  disabled: true

- id: session-telemetry-otlp-trace
  disabled: false
  config:
    mode: FULL
    captureContent: false
    shutdownTimeoutMillis: 5000
    exporter:
      url: http://otel-collector.internal:4318/v1/traces
      compression: gzip
      timeoutMillis: 5000
    processor:
      scheduledDelayMillis: 2000
      maxQueueSize: 4096
      maxExportBatchSize: 512
      exportTimeoutMillis: 5000

AgentCore and other managed ADOT environments can provide the endpoint and resource identity without an exporter block:

export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
export OTEL_SERVICE_NAME=deepseek-harness
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=agentcore

An AgentCore adapter can set DSH_AGENTCORE_SESSION_ID and DSH_AGENTCORE_USER_PROMPT for the root span's evaluation session, task input, and agentcore.invocation.* aliases.

mode accepts FULL, FEEDBACK_ONLY, and DISABLED with the same capture policy as the log backend. captureContent defaults to false; enabling it exports system instructions, model output, tool definitions, tool arguments, tool results, and user-message events after the deployment's session-telemetry/record redaction rules run.

Span mapping

The root span uses gen_ai.operation.name=invoke_agent, gen_ai.conversation.id=<session id>, and session.id=<session id>. Inference spans use gen_ai.operation.name=chat, provider/model/request attributes, token usage, and a first-chunk event. Tool spans use gen_ai.operation.name=execute_tool, gen_ai.tool.name, gen_ai.tool.type=function, and gen_ai.tool.call.id. DSH correlation fields use the dsh.* namespace.

The provider maps DSH's amazon-bedrock and bedrock route names to the standard aws.bedrock value, and maps google and gemini to gcp.gemini. Other route names pass through as custom provider values permitted by the GenAI conventions.

Data handling

The package does not add redaction. FULL capture can include prompts, file contents, command output, local paths, and tool schemas. Mount session-telemetry/record redaction policies before enabling content capture or exporting outside a trusted network.

Model Experience

None, as the backend projects session telemetry into OpenTelemetry spans and never contributes to a model request.

KV Cache effect

None; tracing neither changes model requests nor adds tokens.

Known Limitations and Deferred Work

• Development semantic conventions — OpenTelemetry GenAI agent conventions are still marked Development, so attribute names may require coordinated updates as the specification stabilizes.
• Input history fidelity — the session telemetry record projection does not carry surface replacement metadata, so the exporter records new user messages as Span events instead of claiming a potentially incomplete gen_ai.input.messages attribute.
• Mid-turn backend reload — the telemetry handoff cursor prevents duplicate records after hot reload, but an in-progress span owned by the disposed provider cannot be continued by the replacement provider.