OpenTelemetry telemetry for OpenCode V2. Exports session, LLM-step and tool spans, plus token/cost/cache metrics and structured logs, to any OTLP endpoint (gRPC or HTTP).
This plugin began as a port of @devtheops/opencode-plugin-otel.
Both projects now support OpenCode V2. This fork was verified against OpenCode 2.0.15.
| Area | What this plugin exports or controls |
|---|---|
| Traces | One root span per turn, LLM spans per step, and named tool spans with input, output, duration, and error status. Subagent sessions can nest under their dispatch tool. Spans carry OpenInference and GenAI attributes. |
| Usage and timing | Counters for sessions, messages, model usage, tokens, cost, cache reads and writes, and retries. Histograms for tool duration, session duration, and session token and cost totals. Tool timing and model metrics also work when their spans are disabled. |
| Structured logs | Session creation, success, interruption, failure, and observed idle events. The first LLM step emits a user_prompt log linked to the active turn span when available. Prompt text in logs is opt-in. |
| Content and redaction | Choose full bodies, metadata only, or no bodies for prompts, tool payloads, and errors. Full capture redacts recognized credential patterns, secret environment values, and configured literals by default. Concurrent locations use the strictest active capture mode. |
| Project and run attributes | Filter telemetry by project name, directory, and stable directory-derived ID. Set resource or span attributes in config, or load per-location tags such as run.id and build.id from .opencode/attributes.json. |
| Trace propagation | Attach turn roots to an incoming W3C traceparent and optional tracestate. For selected providers, propagate an active LLM step’s context through the model.request hook. |
| OTLP export | Send traces, metrics, and logs over gRPC, HTTP/protobuf, or HTTP/JSON. Supply static headers or a helper that refreshes credentials and retries an export after an authentication failure. |
| Signal controls | Set the metric prefix, metric and log export intervals, and delta, cumulative, or low-memory aggregation. Disable logs, individual metrics, or session, LLM, and tool traces independently. |
| Multiple locations and diagnostics | Compatible locations share exporters and deduplicate events by ID. Final teardown flushes pending telemetry and releases the providers. A startup probe checks collector reachability. Set OPENCODE_OTEL_DIAG_LOG to choose the diagnostic log path. |
Both packages support OpenCode V2 and register the plugin ID devtheops.otel. Configure one package per installation. This table compares this fork on main at 91463c9 with DEVtheOPS v2.0.1.
| Behavior | This fork · opencode-plugin-otel-v2 |
Upstream · @devtheops/opencode-plugin-otel |
|---|---|---|
| Prompt and tool content | captureContent selects full, metadata, or off. The default is full with best-effort secret redaction. |
Enabled spans can carry prompt and tool bodies. capturePromptInLogs controls prompt text in logs only. |
| Model inputs and outputs | The turn span captures the admitted prompt according to the content policy. LLM spans record model, usage, cost, and finish reason. | LLM spans can include completed assistant text. Optional captureModelContext adds a bounded preview of the system and conversation text visible to the model. |
| Project attribution | Directory-derived project.id, human-readable project name and directory, and per-location JSON attributes. |
Uses OpenCode’s project ID and configured common attributes. |
| Metrics export | Defaults to delta. Idle intervals produce no new metric exports. | Defaults to cumulative. Set metricsTemporality to delta for delta export. |
| Token dashboards | opencode.token.usage adds input, output, and reasoning into one value per step. Cache token quantities appear on LLM spans. |
opencode.token.usage has separate type series for input, output, reasoning, cache reads, and cache writes. |
| Retries and activity | Counts retry status notifications. Emits turn outcome and prompt logs. | Counts durable session.retry.scheduled events. Also emits permission decisions, API request/error logs, tool-result logs, and commit activity inferred from shell commands. |
| Outbound trace headers | Injects headers through model.request for matching active steps. |
Also supports the experimental WebSocket handshake hook for selected providers. |
| Changing exporters | After the last location closes, the next setup can use a new endpoint or credentials. | Keeps the shared providers after the last location closes. Changing their configuration requires a process restart. |
When switching packages, check dashboards that group tokens by type or filter on project.id. Both the available token series and the source of the project ID change.
- OpenCode 2.0.x
- An OTLP endpoint (e.g. Logfire, Grafana, Honeycomb, a local collector)
opencode plugin add opencode-plugin-otel-v2opencode plugin add github:alexhawat/opencode-plugin-otel-v2Clone the repo and point the config at the directory (V2 requires a directory, not a file).
Don't clone it into ~/.config/opencode/plugins/ or .opencode/plugins/: OpenCode V2
auto-loads those folders, so together with the config entry the plugin loads twice
(duplicate spans and metrics). Use a path such as ~/.local/share/opencode-plugins/:
Then add the plugin entry (see examples/opencode.jsonc) to
~/.config/opencode/opencode.jsonc:
{
"plugins": [
{
"package": "opencode-plugin-otel-v2",
"options": {
"enabled": true,
"endpoint": "https://logfire-eu.pydantic.dev",
"protocol": "http/protobuf",
"otlpHeaders": "Authorization={env:LOGFIRE_TOKEN}",
"resourceAttributes": "service.name=my-service,deployment.environment=dev"
}
}
]
}Set the token in the environment (never in the file):
export LOGFIRE_TOKEN=...Verify:
opencode plugin list # expect: devtheops.otelSet options in the plugin configuration. Where an environment variable is listed, an explicit option takes precedence over that variable and the built-in default.
| Option | Default | Description |
|---|---|---|
enabled |
OPENCODE_ENABLE_TELEMETRY |
Master switch. |
endpoint |
OPENCODE_OTLP_ENDPOINT / http://localhost:4317 |
OTLP endpoint. |
protocol |
OPENCODE_OTLP_PROTOCOL / grpc |
grpc, http/protobuf, or http/json. |
otlpHeaders |
OPENCODE_OTLP_HEADERS |
e.g. Authorization={env:LOGFIRE_TOKEN}. |
otlpHeadersHelper |
OPENCODE_OTLP_HEADERS_HELPER |
Command that prints refreshed headers. |
resourceAttributes |
OPENCODE_RESOURCE_ATTRIBUTES |
key=value,... resource attributes. |
spanAttributes |
OPENCODE_SPAN_ATTRIBUTES |
key=value,... added to every span/log. |
metricsInterval / logsInterval |
60000 / 5000 |
Export intervals (ms). |
metricsTemporality |
OPENCODE_OTLP_METRICS_TEMPORALITY / delta |
delta, cumulative, or lowmemory. Keep delta for long-lived hosts: it reports only changes, so an idle process exports nothing. |
metricPrefix |
OPENCODE_METRIC_PREFIX / opencode. |
Metric name prefix. |
logsEnabled |
!OPENCODE_DISABLE_LOGS |
Emit OTLP log records. |
capturePromptInLogs |
OPENCODE_CAPTURE_PROMPT_IN_LOGS |
Put the prompt text on the user_prompt log. Only honoured when captureContent is full. |
captureContent |
OPENCODE_CAPTURE_CONTENT / full |
Prompt, tool and error bodies on spans and logs: full (redacted bodies), metadata (character counts only — input.length, output.length — and the error type without its message), or off. When several plugin instances share a process (one per location), all apply the strictest mode any of them sets. An unrecognised value falls back to metadata. |
redactSecrets |
true (!OPENCODE_NO_REDACT) |
Mask credential-shaped strings and known secrets. |
redactValues |
— | Exact values to mask verbatim. |
locationAttributes |
OPENCODE_LOCATION_ATTRIBUTES / .opencode/attributes.json |
Location-relative JSON file of per-session attributes. |
spanLabels |
true (!OPENCODE_NO_SPAN_LABELS) |
Add a readable label to each span in logfire.msg, e.g. subagent wave-plan-executor: Execute W5. See Readable labels. |
pendingSpans |
OPENCODE_PENDING_SPANS / auto |
Export a placeholder for each span when it starts, so a running turn shows as a tree: auto (on for a Pydantic Logfire endpoint only), true/on, false/off. See Running turns. |
disabledMetrics / disabledTraces |
OPENCODE_DISABLE_METRICS / OPENCODE_DISABLE_TRACES |
Silence by name (session, llm, tool for traces); all or * silences every metric or trace. |
traceparent / tracestate |
OPENCODE_TRACEPARENT / OPENCODE_TRACESTATE |
W3C parent for the root. |
tracePropagationProviders |
OPENCODE_TRACE_PROPAGATION_PROVIDERS |
Providers to inject W3C headers into (* = all). |
Metrics default to delta. Cumulative snapshots are re-exported every interval for the lifetime of the process — even when every session is idle — and the payload grows with each new session and attribute set, which can exhaust a backend's ingest quota while OpenCode is not being used. Delta reports only the change since the last collection: active periods export, idle periods export nothing at all (the SDK skips empty collections). Logfire's metric ingest expects delta.
Override with metricsTemporality, OPENCODE_OTLP_METRICS_TEMPORALITY, or the standard
OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE (in that order of precedence). Only choose
cumulative for short-lived processes. The e2e verification harness asserts that no metric
exports happen while idle.
| Signal | Source |
|---|---|
opencode.session run span (AGENT, turn root) |
session.execution.started → session.execution.succeeded/failed/interrupted |
Session count + session.created log |
session.created, or lazily on first sight |
session.duration, session.token.total, session.cost.total |
session.usage.updated, turn end |
opencode.llm step span (LLM) + token/cost/cache/model metrics |
session.step.started/ended/failed |
The assistant's reply text on the step span (output.value, llm.output_messages) |
session.text.ended, written when the step ends |
opencode.tool.<name> span (TOOL) + tool.duration |
session.tool.input.started, called, success/failed |
retry.count |
session.status (retry) |
user_prompt log (linked to the run span) |
first step of each turn |
session.execution.interrupted log + interrupted span outcome |
session.execution.interrupted |
session.error log + error span status |
session.execution.failed |
| W3C trace-context header injection | model.request hook |
Every span, log and metric also carries a human-readable project.name and project.directory,
derived from the session location at startup (no per-repo file). When the event supplies a working directory,
its basename becomes project.name and its path becomes project.directory.
cache.count counts steps with cache activity separately for type=cacheRead and
type=cacheCreation. Prior versions added cached token quantities to this request counter.
OpenTelemetry exports a span when it ends. A turn's root span (opencode.session) stays open
for as long as the agent works, which can be hours, so every LLM step and tool call that finishes
earlier reaches the backend with a parent it has never seen. Until the turn ends they show as
loose rows instead of a tree.
With pendingSpans on, the plugin also exports a zero-length placeholder for each span the
moment it starts. It uses Pydantic Logfire's pending-span convention: the placeholder has its own
span id, the real span as its parent, logfire.span_type=pending_span, and the real span's own
parent in logfire.pending_parent_id. Logfire shows the span as ongoing with its children nested
under it, and replaces the placeholder when the real span arrives. Subagent sessions, which hang
off the parent's dispatch tool span, appear in place while they run for the same reason.
The default, auto, turns this on only when endpoint is a Logfire host
(logfire-*.pydantic.dev). A backend that does not know the convention would store each
placeholder as an extra zero-length span, so set pendingSpans: true elsewhere only if that is
acceptable. It doubles the number of exported span records; it does not change the real spans.
The turn's outcome log (session.execution.succeeded, .interrupted, or session.error) is
emitted inside the turn's trace, under the run span.
Span names are fixed and low-cardinality (opencode.session, opencode.llm,
opencode.tool.read), which is right for grouping and wrong for reading a trace: a subagent's
session and each of its turns are all called opencode.session. With spanLabels on (the
default), every span also carries a label in the logfire.msg attribute. Pydantic Logfire shows
it as the row's message; other backends keep it as an ordinary attribute. Span names do not
change, so existing queries on span_name keep working.
| Span | Label |
|---|---|
Turn (opencode.session) |
<agent> turn: <start of the prompt> |
Subagent session (opencode.session) |
subagent <agent>: <session title> |
Subagent dispatch (opencode.tool.subagent) |
dispatch <agent>: <description> |
Tool (opencode.tool.<name>) |
<name>: <path, command, pattern or URL> |
LLM step (opencode.llm) |
llm <model>: <start of the reply> |
The part after the colon is content. It is redacted like any other content, collapsed to one
line and truncated, and it is only included when captureContent is full; in metadata and
off the label is the structural part alone (build turn, read, subagent explore).
Set locationAttributes to a location-relative JSON file (default .opencode/attributes.json) and
the plugin merges its contents — a flat string map — into each session's spans, logs, and metrics at
session.created. Use it to tag sessions per working copy (e.g. a run id) without changing global
config:
{ "locationAttributes": ".opencode/attributes.json" }{ "run.id": "f51a0acf-…", "build.id": "b42" }Filter with attributes->>'run.id' = '…'. A missing or malformed file is ignored, and sessions in
other locations are unaffected.
redactSecrets (default on) masks credential-shaped substrings before anything is exported:
Authorization/Bearer, known token prefixes (sk-, pylf_v…, ghp_/github_pat_, AKIA…,
xox…, JWTs), and secret-looking KEY=value pairs. It also masks exact values of
secret-looking environment variables (*_TOKEN, *_SECRET, *_API_KEY, …) and anything in
redactValues, matched anywhere. Applied to prompt text, run-span input, and tool
input/output.
Redaction is best-effort, not a guarantee. It cannot catch a secret it has never seen (not in env, no known shape, not in
redactValues), nor obfuscated/encoded secrets. If you need hard assurance, only send text you are willing to store.
This fork uses per-step LLM spans in place of V1 message/part spans. Its current V2 handlers omit permission decisions, shell-command and commit events, and lines-of-code metrics.
- V2 evaluates a global plugin once per location and delivers every event to every
instance. This plugin therefore keeps its OTel providers and tracing state on
globalThisand dedupes events byevent.id. Active locations must agree on exporter settings. The last location to close flushes and shuts down the private providers. A later setup can use a new collector or new credentials. - V2 does not emit
session.idle, andsession.createdis absent for pre-existing sessions, so the turn root span is anchored onsession.execution.*. session.tool.called/success/faileddo not carry the tool name; it is read fromsession.tool.input.started.data.nameand correlated by call id.
npm install
npm run build # tsc -> dist/
npm run typecheck
npm run verify # drives real V2 payloads into a local OTLP receiver (needs bun)MPL-2.0, inherited from the upstream project. This is a modified fork; see CHANGELOG.md.
{ "plugins": [{ "package": "/absolute/path/to/opencode-plugin-otel-v2" }] }