opencode-otel

OpenCode plugin that forwards runtime stderr logs to any OTLP-compatible collector via gRPC or HTTP.

For BAT deployments, the plugin follows the same OpenTelemetry environment-variable contract injected by Captain:

• logs route to triplog-otel-collector
• optional session-correlation traces route to bat-otel-collector
• metrics remain outside this plugin and are ignored safely

Business-level observability (session traces, message spans, tool calls) is still handled by opencode-plugin-langfuse. This plugin focuses on runtime log shipping and log-to-session correlation only.

How It Works

The plugin monkey-patches process.stderr.write at initialization. Each complete stderr line is:

1. parsed for severity (ERROR, WARN, INFO, DEBUG)
2. emitted as an OTEL LogRecord
3. batched to the configured OTLP log exporter

Original stderr output is preserved exactly as-is.

Quick Start

1. Enable the plugin in OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-otel"]
}

2. Set OTLP routing

Generic OTLP example:

export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://your-collector:8080
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc

3. Start OpenCode

opencode

BAT / Captain Example

The plugin accepts the BAT endpoint format verbatim: http://host:8080 with protocol declared separately as grpc.

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://bat-otel-collector.fws.qa.nt.ctripcorp.com:8080
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://triplog-otel-collector.fws.qa.nt.ctripcorp.com:8080
export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc
export OTEL_EXPORTER_OTLP_TIMEOUT=2000
export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=otlp
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=http://otel.hickwall.sys.qa.nt.ctripcorp.com:8080
export OTEL_EXPORTER_OTLP_METRICS_PROTOCOL=grpc
export OTEL_RESOURCE_ATTRIBUTES=service.name=100059443,group.id=71236405,idc=NTGXH,bu.code=BBZ,cloud.availability_zone=NTGXH-AZ1,cloud.region=NT,host.ip=10.1.2.3,host.name=pod-001
export OTEL_SERVICE_NAME=pay-dev-agent

Notes:

• OTEL_RESOURCE_ATTRIBUTES.service.name wins over OTEL_SERVICE_NAME
• missing BAT identity keys are backfilled from runtime metadata when available
• metrics exporter env vars are tolerated but ignored by this plugin

Signal Routing

Signal	Source	Route	Required
Logs	OTEL_EXPORTER_OTLP_LOGS_*	TripLog / generic OTLP collector	Yes
Traces	OTEL_EXPORTER_OTLP_TRACES_*	BAT trace collector / generic OTLP trace collector	No
Metrics	shared Captain OTEL template	ignored by this plugin	No

If no logs endpoint is configured, the plugin remains inactive and does not install the stderr interceptor.

Service Identity Precedence

service.name is resolved in this order:

1. service.name inside OTEL_RESOURCE_ATTRIBUTES
2. OTEL_SERVICE_NAME
3. serviceName in the optional otel.json
4. PAAS_APP_APPID
5. built-in default opencode-agent

Other BAT identity fields are resolved as:

Resource attribute	Primary source	Runtime fallback
group.id	OTEL_RESOURCE_ATTRIBUTES	PAAS_APP_GROUPID
idc	OTEL_RESOURCE_ATTRIBUTES	CDOS_IDC
bu.code	OTEL_RESOURCE_ATTRIBUTES	CDOS_BUCODE
cloud.availability_zone	OTEL_RESOURCE_ATTRIBUTES	CDOS_AZ
cloud.region	OTEL_RESOURCE_ATTRIBUTES	CDOS_REGION
host.ip	OTEL_RESOURCE_ATTRIBUTES	CDOS_POD_IP
host.name	OTEL_RESOURCE_ATTRIBUTES	HOSTNAME or OS hostname

When inputs disagree, the higher-priority source wins and the plugin emits a startup warning through the OpenCode app logger.

Configuration

Env Variable	Required	Default	Description
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	Yes	—	OTLP logs endpoint
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL	No	grpc	Logs protocol: grpc or http/json
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	No	—	Optional session-correlation trace endpoint
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL	No	grpc	Trace protocol; only grpc is supported
OTEL_EXPORTER_OTLP_TIMEOUT	No	SDK default	Shared OTLP timeout in milliseconds
OTEL_SERVICE_NAME	No	opencode-agent	Secondary service-name input
OTEL_RESOURCE_ATTRIBUTES	No	—	Explicit resource attributes and BAT identity source
OTEL_EXPORTER_OTLP_HEADERS	No	—	Comma-separated key=value auth headers
OTEL_METRICS_EXPORTER	No	ignored	Accepted for shared templates; not used
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	No	ignored	Accepted for shared templates; not used
OTEL_EXPORTER_OTLP_METRICS_PROTOCOL	No	ignored	Accepted for shared templates; not used

Optional Config File

Create ~/.config/opencode/plugins/otel.json:

{
  "logsEndpoint": "http://triplog-otel-collector.fws.qa.nt.ctripcorp.com:8080",
  "logsProtocol": "grpc",
  "tracesEndpoint": "http://bat-otel-collector.fws.qa.nt.ctripcorp.com:8080",
  "serviceName": "opencode-agent",
  "timeoutMs": 2000,
  "maxLineLength": 4096
}

Environment variables take precedence over the config file.

Set OTEL_PLUGIN_CONFIG_PATH to an absolute path to override the default config file location (useful for multi-tenant deployments or tests).

Log Severity Mapping

Stderr Prefix	OTEL Severity
ERROR	ERROR (17)
WARN	WARN (13)
INFO	INFO (9)
DEBUG	DEBUG (5)
Other	UNSPECIFIED (0)

Development

bun install
bun test
bun run build

License

MIT