feat(telemetry): add OpenTelemetry instrumentation with Aspire Dashboard support

[Hona]

Adds experimental OpenTelemetry support for debugging and observability.

What

• Full OTEL instrumentation: all tools, MCP, sessions, LLM, LSP, plugins
• Aspire Dashboard integration via bun run dev:otel
• Service differentiation: opencode-cli vs opencode-server
• Structured logs with full key=value context + exception stack traces
• AI SDK telemetry with GenAI message content capture

Enabling OpenTelemetry

1. Add to your global config (~/.config/opencode/opencode.json:

{
  "experimental": {
    "openTelemetry": true
  }
}

2. Run with Aspire Dashboard:

cd packages/opencode
bun run dev:otel

3. Open dashboard at http://localhost:18888

The OTEL_EXPORTER_OTLP_ENDPOINT env var controls the endpoint (defaults to http://localhost:4317).

Images

[strangemonad]

My recommendation (and what's somewhat conventional) is the app implementation is responsible for setting up this exporter machinery and then if the app is using a library that has an existing otel instrumentation, you enable that. For example ai-sdk provides otel instrumentation. If you use the openai sdk or claude sdk directly, you'd leverage that instrumentation.

The main issue I could imaging (assuming you don't want to be churning on setting all the attributes to work well across vendors) is that the attribute naming for llm related spans is still a bit of a mess as everyone is trying to figure out how to consistently name all these attributes.

If you're just collecting traces for performance sake and don't care about llm/eval then all these traces will show up just fine with the span operation.names you've defined in any trace viewer. The use case I mostly care about is shipping the signals to a tool like langfuse. Those tools expect specific names to show things like sessionID, llm generation, tool call etc.

The different vendors a re working on making the core attributes more uniform but it's not there yet, so personally, I'd try and punt most of that churn on to something like the ai sdk.

Here's a quick snapshot of the landscape of attribute definitions

• Openllmetry has a reasonable collection here https://github.com/traceloop/openllmetry/blob/main/packages/opentelemetry-semantic-conventions-ai/opentelemetry/semconv_ai/__init__.py
• Here's what ai-sdk collects https://ai-sdk.dev/docs/ai-sdk-core/telemetry#collected-data
• Langfuse span operation types https://langfuse.com/docs/observability/features/observation-types and trace attributes https://langfuse.com/integrations/native/opentelemetry#trace-level-attributes
• The emerging OTEL semantic conventions (still very incomplete)
  • https://opentelemetry.io/docs/specs/semconv/gen-ai/
  • https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/ e.g. operation types still don't have a standard naming here yet.

[Hona]

agreed on the running application chooses the exporter.
ill check more but running opencode cli should configure the exporter.
also tbh this otel work is just to support development/profiling/debugging for now.

i'll check those emerging standards for attributes to see if I can consolidate.
for now any span/attribute is good and we can easily rename later.

I'll check your other comments later but I'm sure you saw I pushed a big refactor to clean up the implementation to be more like a decorator/using pattern to remove heaps of noise.

[strangemonad]

yep, saw the cleanup / refactor. This comment still applies and summarizes whatever still applies after your refactor.

agreed on the running application chooses the exporter.
ill check more but running opencode cli should configure the exporter.

Yep, I think we're saying the same thing here. the current experimental_telemetry just enables the ai sdk instrumentation but doesn't start an exporter. So mainly calling out that the biggest missing piece is something needs to start the exporter.

also tbh this otel work is just to support development/profiling/debugging for now.

That makes sense. Mostly calling out that if you retain the ai-sdk enabling, you don't need to re-instrument llm calls, tool calls etc since those are already done for you and will the most up to date evolving attributes so the same traces become useful for building agentic engineering evals or workflow review (the part I'm actually more excited about).

That obviously doesn't prevent wrapping those ai SDK calls in you own spans to get even finer-grained instrumentation.

That said, if you're mostly interested in instrumentation for performance profiling. I'd definitely consider setting up the node.js otel auto-instrumentation and metrics. Eg you'll probably find at least having metrics around GC stats like runs and pauses useful.

crude example:

const sdk = new NodeSDK({
  traceExporter: new ConsoleSpanExporter(),
  metricReader: new PeriodicExportingMetricReader({
    exporter: new ConsoleMetricExporter(),
  }),
  instrumentations: [
     getNodeAutoInstrumentations()
  ],
});

[Hona]

I've got some more work to make it perfect - but agree on your points.

i'll double check the ai sdk vs my custom spans.
the aspire dashboard looked pretty nice but i'll check if there's exact double ups

yup I'll add the typical instrumentation for node, even seeing if our underlying opentui/zig stuff can have instrumentation.

I'll see what is first cut/vs add to the PR. the team will check this out over the next few weeks

[strangemonad]

FWIW, if you wanted to spot check stuff against another otel collector and trace view, you can run a langfuse stack fully locally

git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up

everything (web app and otel collector endpoint is available on localhost:3000).