Skip to content

README.md

Latest commit

 

History

History
122 lines (89 loc) · 3.95 KB

README.md

File metadata and controls

122 lines (89 loc) · 3.95 KB

@braintrust/trace-opencode

Braintrust tracing plugin for OpenCode. Automatically traces your OpenCode sessions to Braintrust with hierarchical spans.

  • Session spans: Root span for each OpenCode session with metadata (workspace, hostname, etc.)
  • Turn spans: Captures each user-assistant interaction
  • Tool spans: Records individual tool executions with inputs and outputs

Quick Start

Add to your OpenCode configuration (opencode.json or ~/.config/opencode/opencode.json):

{
  "plugin": ["@braintrust/[email protected]"], <--- replace with latest version
}

Then,

# Set your API key
export BRAINTRUST_API_KEY="your-api-key"
export TRACE_TO_BRAINTRUST="true"

# Run OpenCode
opencode

# View traces at:
# https://www.braintrust.dev/app/projects/opencode/logs

Configuration

You can configure the plugin using a config file or environment variables.

Config File

Create a braintrust.json file in one of these locations:

  • .opencode/braintrust.json - Project-level config
  • ~/.config/opencode/braintrust.json - Global config
{
  "trace_to_braintrust": true,
  "project": "my-project",
  "api_key": "your-api-key",
  "debug": true
}

Config Options

Config Key Env Var Type Default Description
trace_to_braintrust TRACE_TO_BRAINTRUST boolean false Enable/disable tracing
project BRAINTRUST_PROJECT string "opencode" Project name for traces
debug BRAINTRUST_DEBUG boolean false Enable debug logging
api_key BRAINTRUST_API_KEY string API key for authentication
api_url BRAINTRUST_API_URL string "https://api.braintrust.dev" API URL
app_url BRAINTRUST_APP_URL string "https://www.braintrust.dev" App URL
org_name BRAINTRUST_ORG_NAME string Organization name
additional_metadata BRAINTRUST_ADDITIONAL_METADATA string JSON object of additional metadata to attach to the root span. Standard metadata keys take precedence on conflict.

Precedence

Configuration is loaded with the following precedence (later overrides earlier):

  1. Default values
  2. ~/.config/opencode/braintrust.json (global config)
  3. .opencode/braintrust.json (project config)
  4. Environment variables (highest priority)

Adding Dynamic Metadata

Use BRAINTRUST_ADDITIONAL_METADATA to attach custom key-value pairs to the root span. This is useful for tagging traces in CI or linking them back to a specific run.

BRAINTRUST_ADDITIONAL_METADATA='{"ci": true, "run_id": "abc-123"}' opencode run "do the thing"

You can also set it via the config file:

{
  "additional_metadata": {
    "team": "platform"
  }
}

The value must be a JSON object. Any keys that conflict with standard root span metadata (session_id, workspace, directory, hostname, username, os) will be overridden by the standard values.

Trace Structure

Sessions are traced with the following hierarchy:

Session (task span)
├── metadata: session_id, workspace, hostname, username, os
├── Turn 1 (task span)
│   ├── input: "user message"
│   ├── metadata: turn_number, agent, model
│   ├── Tool 1 (tool span)
│   │   ├── input: tool arguments
│   │   └── output: tool result
│   └── Tool 2 (tool span)
├── Turn 2 (task span)
│   └── ...
└── metrics: total_turns, total_tool_calls

Releasing

This package is published from GitHub Actions via .github/workflows/publish-package.yaml using npm trusted publishing with OIDC and npm provenance (npm publish --provenance).

To cut a release:

  1. Bump package.json to the version you want to ship.
  2. Run the Publish package workflow from the branch you want to release.
  3. The workflow validates the package, publishes to npm, pushes the matching v<version> git tag, and creates a GitHub release.
⚡