OpenCode Traces

OpenCode is an open-source coding agent you run in your terminal. The Inference platform OpenCode plugin records those coding sessions so you can review what the agent did: model calls, tool calls, token usage, cost, finish reasons, errors, prompts, responses, and tool payloads.

This page is for observing a coding tool you use. To trace an agent or application you build, start with the Tracing Quickstart and the SDK integrations.

OpenCode installs npm plugins automatically from your opencode.json; you do not need to add this package to your app's dependencies.

Install

Add the plugin to your OpenCode config, either in your project opencode.json or globally at ~/.config/opencode/opencode.json.

opencode.json

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

Configure

Opt in with your inference.net API key. INFERENCE_API_KEY alone never turns recording on (many environments export it for gateway calls), so pair it with TRACE_TO_INFERENCE=true.

export TRACE_TO_INFERENCE=true
export INFERENCE_API_KEY="<your-inference-api-key>"
export INFERENCE_SERVICE_NAME="my-opencode"

Then use OpenCode as usual.

opencode run "add a health check endpoint and a test for it"

What Gets Recorded

Every turn, meaning one prompt and the agent's response to it, becomes a trace in the Inference platform. Spans carry the OpenCode session.id, so all turns from the same coding session can be grouped together.

The AGENT root span records session id, service identity, call counts, stop reason, and error status.
LLM spans record model/provider details, finish reason, prompt/cache/completion/reasoning tokens, and cost.
TOOL spans record shell, file, and MCP tool calls with timing and error status.

By default, spans include prompts, model output, tool arguments, and tool output. Set INFERENCE_REDACT_CONTENT=true to keep spans metadata-only.

Turn (AGENT, session.id=ses_...)
  anthropic/claude-...  (LLM: tokens, cache, finish reason, cost)
  bash: ...             (TOOL: name, timing, status)
  read: file.ts         (TOOL)
  anthropic/claude-...  (LLM: final reply)

Use these traces to audit what a session did, debug failed turns, compare how models behave on similar tasks, or track coding-agent cost. Turn on content redaction when you only need metadata and timing.

Configuration Reference

The plugin uses the same env-var convention as the TypeScript and Python tracing SDKs.

Environment variable	Default	Description
`INFERENCE_API_KEY`	-	inference.net API key used as the ingest bearer token. Requires `TRACE_TO_INFERENCE=true` to enable recording.
`INFERENCE_OTLP_ENDPOINT`	`https://telemetry.inference.net`	OTLP/HTTP trace ingest endpoint.
`INFERENCE_SERVICE_NAME`	`opencode`	Stable OTel `service.name`, also used as the OpenCode agent id.
`TRACE_TO_INFERENCE`	off	Set `true` to enable with `INFERENCE_API_KEY`, or for tokenless custom collectors with an explicit non-hosted endpoint. Set `false` to force-disable.
`INFERENCE_REDACT_CONTENT`	`false`	Set `true` to keep prompts, model outputs, tool arguments, and tool outputs off traces.
`INFERENCE_ADDITIONAL_METADATA`	-	JSON object attached to each turn's metadata.
`INFERENCE_DEBUG`	`false`	Verbose plugin logging through OpenCode's log API.

Local Collector

To export to a local collector without an auth token, set both an explicit endpoint and TRACE_TO_INFERENCE=true.

export INFERENCE_OTLP_ENDPOINT="http://localhost:4318"
export TRACE_TO_INFERENCE=true

Privacy

By default the plugin records prompts, model output, file content read or written by tools, and shell command output. Set INFERENCE_REDACT_CONTENT=true when you want metadata-only traces.

Troubleshooting

If no traces appear, check:

TRACE_TO_INFERENCE=true and INFERENCE_API_KEY are set in the environment that launches OpenCode.
INFERENCE_SERVICE_NAME is the value you are filtering for in the dashboard.
INFERENCE_OTLP_ENDPOINT is https://telemetry.inference.net unless you are intentionally using a custom collector.
OpenCode has restarted after you added the plugin to opencode.json.