Skip to content

Multiwoven/opencode-plugin-otel

BranchesTags

Repository files navigation

opencode-plugin-otel

npm version npm downloads GitHub stars Build status Discord notifications License

An opencode plugin that exports telemetry via OpenTelemetry (OTLP over gRPC or HTTP/protobuf), mirroring the same signals as Claude Code's monitoring.

What it instruments

Metrics

Metric Type Description
opencode.session.count Counter Incremented on each session.created event
opencode.token.usage Counter Per token type: input, output, reasoning, cacheRead, cacheCreation
opencode.cost.usage Counter USD cost per completed assistant message
opencode.lines_of_code.count Counter Gross positive churn, not a net total. Emits the positive delta of additions/deletions since the previous session.diff for the same session; negative deltas (when opencode's cumulative additions or deletions shrinks vs. the last event) are dropped. Summing the counter therefore reports gross lines added/removed across forward transitions — it does not reconcile back to the session's current state after any revert (full or partial). Intra-message rewrites that opencode collapses in its per-message cumulative are not visible here at all. Use opencode.lines_of_code.total for the authoritative live cumulative.
opencode.lines_of_code.total Gauge Authoritative live cumulative lines added/removed for the session. Refreshed on every session.diff with opencode's current cumulative value. Drops back to 0 if opencode reports a revert to baseline, and tracks partial reverts faithfully. Query this (not the counter) to answer "what does this session currently amount to".
opencode.commit.count Counter Git commits detected via bash tool
opencode.tool.duration Histogram Tool execution time in milliseconds
opencode.cache.count Counter Cache activity per message: type=cacheRead or type=cacheCreation
opencode.session.duration Histogram Session duration from created to idle in milliseconds
opencode.message.count Counter Completed assistant messages per session
opencode.session.token.total Histogram Total tokens consumed per session, recorded on idle
opencode.session.cost.total Histogram Total cost per session in USD, recorded on idle
opencode.model.usage Counter Messages per model and provider
opencode.retry.count Counter API retries observed via session.status events

Log events

Event Description
session.created Session started
session.idle Session went idle (includes total tokens, cost, messages)
session.error Session error
user_prompt User sent a message (includes prompt_length, model, agent)
api_request Completed assistant message (tokens, cost, duration)
api_error Failed assistant message (error summary, duration)
tool_result Tool completed or errored (duration, success, output size)
tool_decision Permission prompt answered (accept/reject)
commit Git commit detected

Installation

Add the plugin to your opencode config at ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@devtheops/opencode-plugin-otel"]
}

Or point directly at a local checkout for development:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["/path/to/opencode-plugin-otel/src/index.ts"]
}

Configuration

All configuration is via environment variables. Set them in your shell profile (~/.zshrc, ~/.bashrc, etc.).

Variable Default Description
OPENCODE_ENABLE_TELEMETRY (unset) Set to any non-empty value to enable the plugin
OPENCODE_OTLP_ENDPOINT http://localhost:4317 OTLP collector endpoint. Always include a URL scheme. For grpc, use the collector URL (for example http://localhost:4317 or grpc://collector:4317). For http/protobuf and http/json, use the base URL and the plugin will append /v1/traces, /v1/metrics, and /v1/logs.
OPENCODE_OTLP_PROTOCOL grpc OTLP transport protocol: grpc, http/protobuf, or http/json
OPENCODE_OTLP_METRICS_INTERVAL 60000 Metrics export interval in milliseconds
OPENCODE_OTLP_LOGS_INTERVAL 5000 Logs export interval in milliseconds
OPENCODE_METRIC_PREFIX opencode. Prefix for all metric names (e.g. set to claude_code. for Claude Code dashboard compatibility)
OPENCODE_DISABLE_METRICS (unset) Comma-separated list of metric name suffixes to disable (e.g. cache.count,session.duration)
OPENCODE_DISABLE_LOGS (unset) Set to any non-empty value to suppress all OTLP log events while leaving metrics and traces unchanged
OPENCODE_DISABLE_TRACES (unset) Comma-separated list of trace types to disable (session, llm, tool). Use all, *, true, or 1 to disable every trace type
OPENCODE_OTLP_HEADERS (unset) Comma-separated key=value headers added to all OTLP exports. Keep out of version control — may contain sensitive auth tokens.
OPENCODE_OTLP_HEADERS_HELPER (unset) Executable script/binary that returns dynamic OTLP headers as JSON after an auth failure. Helper headers override OPENCODE_OTLP_HEADERS.
OPENCODE_RESOURCE_ATTRIBUTES (unset) Comma-separated key=value pairs merged into the OTel resource (describes the producer). Example: service.version=1.2.3,deployment.environment=production
OPENCODE_SPAN_ATTRIBUTES (unset) Comma-separated key=value pairs added to spans only (not logs, metrics, or the resource). Example: team=platform,deployment.environment=production
OPENCODE_METRIC_ATTRIBUTES (unset) Comma-separated key=value pairs added to metric data points only (not spans, logs, or the resource). Example: deployment.environment=production
OPENCODE_EXCLUDE_METRICS_ATTRIBUTES (unset) Comma-separated attribute keys stripped from metric data points only (not spans or logs). Applied last, so it always wins over OPENCODE_METRIC_ATTRIBUTES. Example: session.id to avoid high-cardinality session labels on counters and histograms
OPENCODE_OTLP_METRICS_TEMPORALITY (unset) Metrics aggregation temporality: delta, cumulative, or lowmemory. Required for Datadog (delta). Copied to OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE.
OPENCODE_COST_USAGE_SCALE 1 Multiplier applied to USD cost values before they are recorded as the cost.usage counter. Set to 1000000 for backends that round metric values to one decimal place (e.g. AppSignal) so per-message cents land as whole numbers. Only affects cost.usage — session.cost.total, spans, and log events keep raw USD. Divide by this value in dashboards to display dollars.
OPENCODE_TRACEPARENT (unset) W3C traceparent string. When set, all spans are parented under this remote context so opencode traces nest inside a caller's trace (e.g. a CI job). Invalid values are logged and ignored. Note: with the default ParentBased sampler, a value with the sampled flag off (...-00) suppresses all trace export.
OPENCODE_TRACESTATE (unset) W3C tracestate string, parsed alongside OPENCODE_TRACEPARENT and attached to the remote parent context. Ignored unless a valid OPENCODE_TRACEPARENT is also set.

Quick start

export OPENCODE_ENABLE_TELEMETRY=1
export OPENCODE_OTLP_ENDPOINT=http://localhost:4317
export OPENCODE_OTLP_PROTOCOL=grpc
opencode

Always set OPENCODE_OTLP_ENDPOINT to a full URL with a scheme. Scheme-less values like localhost:4317 are rejected.

For OPENCODE_OTLP_PROTOCOL=http/protobuf or OPENCODE_OTLP_PROTOCOL=http/json, set OPENCODE_OTLP_ENDPOINT to the collector base URL rather than a per-signal path. The plugin expands it to /v1/traces, /v1/metrics, and /v1/logs automatically.

Headers and resource attributes

# Auth token for a managed collector (e.g. Honeycomb, Grafana Cloud)
export OPENCODE_OTLP_HEADERS="x-honeycomb-team=your-api-key,x-honeycomb-dataset=opencode"

# Tag the OTel resource (producer metadata) with deployment context
export OPENCODE_RESOURCE_ATTRIBUTES="service.version=1.2.3,deployment.environment=production"

# Tag spans only (e.g. high-cardinality dimensions for trace drill-down)
export OPENCODE_SPAN_ATTRIBUTES="team=platform"

# Tag metric data points only (e.g. low-cardinality dashboard dimensions)
export OPENCODE_METRIC_ATTRIBUTES="deployment.environment=production"

Each attribute channel targets a different signal: OPENCODE_RESOURCE_ATTRIBUTES → the OTel Resource (producer metadata); OPENCODE_SPAN_ATTRIBUTES → spans only; OPENCODE_METRIC_ATTRIBUTES → metric data points only. They are independent — a key set in one does not appear in the others.

Security note: OPENCODE_OTLP_HEADERS typically contains auth tokens. Set it in your shell profile (~/.zshrc, ~/.bashrc) or a secrets manager — never commit it to version control or print it in CI logs.

Dynamic headers

Use OPENCODE_OTLP_HEADERS_HELPER when your collector requires short-lived authentication tokens. When this is set, the plugin prewarms the helper once during startup so the first export can use fresh credentials. If a later OTLP export fails with an authentication error (401/403 for HTTP or UNAUTHENTICATED/PERMISSION_DENIED for gRPC), the plugin refreshes headers again, rebuilds the exporter, and retries the failed export once.

export OPENCODE_OTLP_HEADERS_HELPER=/path/to/opencode-otel-headers.sh

Use an absolute helper path. If you need the path to follow the current project, OPENCODE_OTLP_HEADERS_HELPER also supports ${PROJECT_ROOT}, ${WORKTREE}, and ${DIRECTORY} placeholders.

export OPENCODE_OTLP_HEADERS_HELPER='${PROJECT_ROOT}/scripts/opencode-otel-headers.sh'

The helper must be executable and print a JSON object to stdout:

#!/bin/sh
printf '{"Authorization":"Bearer %s"}' "$(get-token.sh)"

For a Cloud Run collector using IAM authentication, get-token.sh might be gcloud auth print-identity-token.

If OPENCODE_OTLP_HEADERS is also set, helper-provided headers override static headers with the same name. Header values are never logged.

Disabling specific metrics

Use OPENCODE_DISABLE_METRICS to suppress individual metrics. The value is a comma-separated list of metric name suffixes (without the prefix).

Disabling a metric only stops the counter/histogram from being incremented — the corresponding log events are still emitted.

# Disable a single metric
export OPENCODE_DISABLE_METRICS="retry.count"

# Disable multiple metrics
export OPENCODE_DISABLE_METRICS="cache.count,session.duration,session.token.total,session.cost.total,model.usage,retry.count,message.count"

# Disable the new per-session cumulative gauge while keeping the delta counter
export OPENCODE_DISABLE_METRICS="lines_of_code.total"

opencode-only metrics

The following metrics are specific to opencode and have no equivalent in Claude Code's built-in monitoring. If you are using a Claude Code dashboard and want to avoid cluttering it with opencode-only metrics, you can disable them:

export OPENCODE_DISABLE_METRICS="cache.count,session.duration,session.token.total,session.cost.total,model.usage,retry.count,message.count"
Metric suffix Why it's opencode-only
cache.count Tracks cache read/write activity as occurrence counts — not a Claude Code signal
session.duration Session wall-clock duration — not emitted by Claude Code
session.token.total Per-session token histogram — not emitted by Claude Code
session.cost.total Per-session cost histogram — not emitted by Claude Code
model.usage Per-model message counter — not emitted by Claude Code
retry.count API retry counter — not emitted by Claude Code
message.count Completed message counter — not emitted by Claude Code

Disabling OTLP logs

Use OPENCODE_DISABLE_LOGS to suppress every OTLP log event emitted by the plugin.

export OPENCODE_DISABLE_LOGS=1

This only disables OTLP logs. Metrics and traces continue to be exported unless they are disabled separately.

Disabling traces

Use OPENCODE_DISABLE_TRACES to suppress one or more trace types.

# Disable one trace type
export OPENCODE_DISABLE_TRACES="tool"

# Disable multiple trace types
export OPENCODE_DISABLE_TRACES="llm,tool"

# Disable every trace type explicitly
export OPENCODE_DISABLE_TRACES="all"

Accepted explicit "disable all traces" values are all, *, true, and 1.

SigNoz example

export OPENCODE_ENABLE_TELEMETRY=1
export OPENCODE_OTLP_ENDPOINT="https://ingest.us.signoz.cloud:443"
export OPENCODE_OTLP_HEADERS="signoz-ingestion-key=<SIGNOZ_INGESTION_KEY>"

Use https://ingest.in.signoz.cloud:443 for India, https://ingest.eu2.signoz.cloud:443 for EU2, etc. See SigNoz setup docs for all regions.

Datadog example

export OPENCODE_ENABLE_TELEMETRY=1
export OPENCODE_OTLP_ENDPOINT=https://otlp.datadoghq.com
export OPENCODE_OTLP_PROTOCOL=http/protobuf
export OPENCODE_OTLP_HEADERS="dd-api-key=YOUR_DATADOG_API_KEY"

# Required — Datadog's OTLP intake only accepts delta temporality
export OPENCODE_OTLP_METRICS_TEMPORALITY=delta

Note: The endpoint is otlp.datadoghq.com (not api.datadoghq.com). Use otlp.datadoghq.eu for EU, otlp.us3.datadoghq.com for US3, etc. See Datadog OTLP docs for all regions.

Honeycomb example

export OPENCODE_ENABLE_TELEMETRY=1
export OPENCODE_OTLP_ENDPOINT=https://api.honeycomb.io
export OPENCODE_OTLP_PROTOCOL=http/protobuf

Grafana Cloud example

export OPENCODE_ENABLE_TELEMETRY=1
export OPENCODE_OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
export OPENCODE_OTLP_PROTOCOL=http/protobuf
export OPENCODE_OTLP_HEADERS="Authorization=Basic <base64-instance-id:api-key>"

Claude Code dashboard compatibility

export OPENCODE_METRIC_PREFIX=claude_code.

Scaling cost.usage for backends that round metric values

Some observability backends round metric values to one decimal place server-side (AppSignal is one example). Per-message cost values like $0.023 then collapse to 0.0 and dashboards look empty.

Use OPENCODE_COST_USAGE_SCALE to multiply the value sent to cost.usage so the integer part is meaningful. Only cost.usage is affected — session.cost.total, spans, and log events still carry the raw USD value.

# Scale to millionths of a dollar — $0.023 → 23000
export OPENCODE_COST_USAGE_SCALE=1000000

When querying the metric, divide by the same factor to get dollars back. With OPENCODE_COST_USAGE_SCALE=1000000, a cost.usage value of 23000 is $0.023.

The cost.usage unit is updated to USD/1000000 (or whatever scale you set) and the description is annotated so the unit is visible in the backend's metric catalog.

Local development

See CONTRIBUTING.md.

GitHub Discord notifications

This repo includes a reusable workflow at .github/workflows/discord-notify.yml that posts a Discord embed for supported GitHub events. The included .github/workflows/discord-events.yml file wires it up for:

  • issues.opened
  • pull_request.opened
  • release.published

Set an org or repo secret named DISCORD_WEBHOOK and the workflow will post to that webhook automatically.

To reuse it from another repository in the DEVtheOPS org:

name: Discord Events

on:
  issues:
    types: [opened]
  pull_request:
    types: [opened]
  release:
    types: [published]

jobs:
  notify-discord:
    uses: DEVtheOPS/opencode-plugin-otel/.github/workflows/discord-notify.yml@main
    with:
      username: DEVtheOPS Bot
      title_prefix: "[DEVtheOPS]"
      include_body: true
    secrets:
      discord_webhook: ${{ secrets.DISCORD_WEBHOOK }}

Available workflow inputs:

  • username: webhook display name
  • avatar_url: webhook avatar image URL
  • title_prefix: optional title prefix for the embed
  • include_body: include the issue, PR, or release body in the card
  • color: fallback embed color for unsupported events

About

No description, website, or topics provided.

Resources

Readme

License

MPL-2.0 license

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages