TLS Observer for DeepSeek Harness

@volcengine/tls-observer-dsh is a native Cordis observer plugin. It listens to the committed DeepSeek Harness session/event stream and maps EventLog boundaries onto live OpenTelemetry Span lifecycles. OpenTelemetry remains the in-process trace model; completed Spans are converted to TLS trace-envelope log records and written with TLS Producer SendLogs, not OTLP HTTP:

• turn/start → start the TLS-compatible agent.turn Agent root Span;
• step/start / assistant/message → start and end the TLS-compatible llm.request Span;
• llm/retry / llm/retry-started → annotate recoverable attempts on that LLM Span;
• tool/call / tool/result → start and end the TLS-compatible tool.call Span;
• turn/end → end the Agent root Span and schedule a non-blocking flush;
• session/disposed / plugin shutdown → close incomplete Spans and drain the SDK.

Raw assistant/chunk events are not sent individually. The first content chunk records gen_ai.response.time_to_first_chunk in seconds; the completed Span enters the SDK BatchSpanProcessor, which exports it independently from the still-open root Span. Child-agent sessions use their own Trace and carry an OpenTelemetry Link to the live parent turn when that context is available.

One-step install

npm exec -y \
  --package=@volcengine/tls-observer-dsh-install@latest -- \
  tls-observer-dsh-install install \
  --profile web \
  --region cn-beijing \
  --trace-topic-id <topic-id> \
  --api-key <api-key> \
  --capture-content true

The runtime is a formal DSH bundle. The installer uses the official Profile plugin manager and persists TLS settings under $DSH_HOME/.env, so later GUI/Web launches load the same observer. The default profile is web; restart DeepSeek Harness after installation.

For an ACP/custom Cordis runner, target its standalone composition instead of inventing an acp profile:

tls-observer-dsh-install install \
  --cordis-config /path/to/acp/cordis.yml \
  --observer-env-file /path/to/acp/observer.env \
  --region cn-beijing \
  --trace-topic-id <topic-id> \
  --api-key <api-key>

The installer adds one managed observer entry and an isolated sibling runtime. ACP-created agents still publish ordinary session EventLogs, so the projection and TLS Producer export path is the same as Web. No local collector or port 4318 is required.

Cordis configuration has the highest priority. The runtime then reads DEEPSEEK_HARNESS_TLS_*, followed by the compatible TLS_TRACE_* / TLS_* variables. exporter.endpoint is an alias of exporter.url; both identify the TLS Producer host rather than an OTLP /v1/traces URL. Legacy DEEPSEEK_HARNESS_TLS_OTEL_ENDPOINT values are accepted only as migration input: the runtime extracts the hostname and still uses SendLogs.

Content capture remains an explicit opt-in. The observability application command above enables it because the TLS Trace and Session views require gen_ai.input.messages and gen_ai.output.messages for Input, Output, First Input, and Last Output. Only enable it after confirming that prompts, model output, system instructions, tool arguments/results, and local paths may be exported. Timing, status, inclusive token usage, model, provider, session lineage, and Span hierarchy remain available when content is disabled.

The plugin keeps the registered GenAI attributes and adds the existing TLS UI compatibility contract: canonical Span names (agent.turn, llm.request, tool.call), Agent/LLM/Tool SpanKind (SERVER, CLIENT, CLIENT), and per-Span tls.app.type=DeepSeekHarness. Model and tool names remain in gen_ai.request.model, gen_ai.response.model, and gen_ai.tool.name.

Every Span also carries the TLS dashboard identity keys. DSH-native values populate session.id, session.name (from the latest session/title), gen_ai.agent.name/agent.name, tls.app.type, and tls.plugin.version. Fields unavailable from DSH (user.id, user.name, gen_ai.agent.version, and agent.version) are emitted as empty strings. Deployments can set or override any of them with repeatable installer arguments such as --span-attribute user.id=customer-123; explicit custom values win over auto-detected values.

The exported GenAI token contract is inclusive: input tokens equal DSH uncached input plus cache read and cache creation; output tokens already include reasoning. Dashboards must calculate total tokens as input plus output and must not add reasoning again.