dsh-o11y-plugin

Unified plugin-dimension observability (trace / log / metric) for
deepseek-harness (dsh).

中文文档

Overview

dsh ships session-level OTel telemetry but exposes no metric or plugin-scoped
observability to plugins. dsh-o11y-plugin converges that gap: it registers
global OpenTelemetry providers so any plugin using the standard
@opentelemetry/api exports traces, metrics, and logs through a single,
consistently configured pipeline, and it bridges dsh session telemetry into
OTel logs. It is intended for plugin authors who want standard,
community-compatible observability without implementing OTel per plugin.

Compatibility

Built on the official OpenTelemetry Node.js SDK, the same dependency family as
dsh's session-telemetry-otel.

Install / Uninstall

# install
dsh plugin --profile web add github:fly3366/dsh-o11y-plugin

# disable for one profile
dsh plugin --profile web remove dsh-o11y-plugin

# or disable at runtime via config: enabled=false

The plugin is stateless; removal requires no data cleanup.

Quick start

dsh plugin --profile headless add github:fly3366/dsh-o11y-plugin
# point exports at a collector (optional; silent without one)
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 dsh --profile headless "say hi"

Any plugin that calls trace.getTracer(...) / metrics.getMeter(...) /
logs.getLogger(...) from @opentelemetry/api is then exported automatically.
deepjit is the reference consumer,
emitting pipeline counters and GenAI (gen_ai.*) LLM spans.

Configuration

Sensitive: no credentials are read or stored; only the optional OTLP endpoint is
network-facing.

Permissions & data

• Files: none written; all telemetry is in-memory until exported.
• Network: OTLP/HTTP to the configured endpoint only; silent drop when no
  collector is reachable.
• Credentials: none.
• User data: session-telemetry records are observed in-memory (when
  bridging) and forwarded as OTel logs; nothing is persisted by this plugin.

Troubleshooting

• No collector at the endpoint → batches are dropped silently (expected).
• Export errors → surface via OTel diag; verify endpoint and collector
  availability.
• Roll back with dsh plugin --profile <p> remove dsh-o11y-plugin or set
  enabled=false.

Development

npm install
npm run typecheck
npm test
npm run build

Contributions welcome; keep the OTel SDK dependency family aligned with dsh's
session-telemetry-otel for community compatibility.

License & security

MIT. Report vulnerabilities privately per SECURITY.md.