OpenCode Traces - Inference.net Documentation

OpenCode is an open-source coding agent you run in your terminal. The Catalyst 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

Set your Catalyst OTLP token. Recording turns on automatically when the token is present.

export CATALYST_OTLP_TOKEN="<your-token>"
export CATALYST_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 Catalyst. 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 CATALYST_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 Catalyst tracing env-var convention as the TypeScript and Python tracing SDKs.

Environment variable	Default	Description
`CATALYST_OTLP_TOKEN`	-	Catalyst ingest token. Recording starts when this is set.
`CATALYST_OTLP_ENDPOINT`	`https://telemetry.inference.net`	OTLP/HTTP trace ingest endpoint.
`CATALYST_SERVICE_NAME`	`opencode`	Stable OTel `service.name`, also used as the OpenCode agent id.
`TRACE_TO_CATALYST`	on when a token is set	Set `false` to disable. Set `true` only for tokenless custom collectors with an explicit non-hosted endpoint.
`CATALYST_REDACT_CONTENT`	`false`	Set `true` to keep prompts, model outputs, tool arguments, and tool outputs off traces.
`CATALYST_ADDITIONAL_METADATA`	-	JSON object attached to each turn’s metadata.
`CATALYST_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_CATALYST=true.

export CATALYST_OTLP_ENDPOINT="http://localhost:4318"
export TRACE_TO_CATALYST=true

Privacy

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

Troubleshooting

If no traces appear, check:

CATALYST_OTLP_TOKEN is set in the environment that launches OpenCode.
CATALYST_SERVICE_NAME is the value you are filtering for in Catalyst.
CATALYST_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.

​Install

​Configure

​What Gets Recorded

​Configuration Reference

​Local Collector

​Privacy

​Troubleshooting

Install

Configure

What Gets Recorded

Configuration Reference

Local Collector

Privacy

Troubleshooting