OpenCode Sentry Effect
Effect-native monitoring for OpenCode V2. The server plugin observes agent runs, model requests and tools. Separate terminal and desktop adapters report client-side errors to the same Sentry project.
This is a local implementation targeting OpenCode 2.2.7 and its supplied Effect 4.1.0 runtime. It is not an official OpenCode or Sentry plugin. Nothing is published to npm.
Coverage
| Signal |
Collection |
| Agent runs |
One transaction per observed execution, with success, failure or interruption status |
| Model calls |
Request spans, response-body timing, reported token usage and cost |
| Tools |
Child spans with timing and the host's actual completion or failure status |
| Retries |
Latest retry attempt and error classification on the agent transaction |
| Compaction |
Separate request transactions with reported usage and costs |
| Content |
Assembled primary request context, completed response text and tool input/output, when enabled |
| Server failures |
Terminal session failures correlated with their agent transaction |
| Terminal errors |
uncaughtExceptionMonitor, without suppressing normal process termination |
| Desktop errors |
Main-process exception monitoring, window errors, unhandled rejections and abnormal renderer exits |
The server owns session telemetry. Clients do not re-report session events. Execution events without a location are resolved through the session API so that unrelated open project locations do not duplicate them.
The plugin never initializes a global Sentry SDK or replaces OpenCode's built-in client. Pure Sentry SDK utilities handle envelope serialization, IDs and stack parsing. Effect owns configuration, subscriptions, the bounded outbox and exporter lifetime.
Install locally
bun install
bun run check
bun run install:global
bun run install:global -- --apply
The installer reads ~/.config/opencode/sentry-monitor.jsonc, validates the DSN, backs up the global opencode.jsonc and adds this repository as a plugin. It enables input/output recording for this personal setup. It preserves unrelated configuration and never restarts a process. The DSN is never printed.
Alternatively, add the local package to global opencode.jsonc yourself:
{
"plugins": [
{
"package": "/absolute/path/to/opencode-sentry",
"options": {
"dsn": "https://PUBLIC_KEY@SENTRY_HOST/PROJECT_ID",
"recordInputs": true,
"recordOutputs": true
}
}
]
}
OpenCode's configuration watcher reloads the plugin. Desktop loads the prebuilt ./gui-experimental bundle; rebuild it after source changes. A terminal connected to a different server needs its own TUI-plugin configuration if that server does not advertise this package.
The window adapter requires options.dsn because it cannot read local config files. Server, terminal and desktop-main adapters also accept the global sidecar or OPENCODE_SENTRY_DSN. The generic SENTRY_DSN is deliberately ignored so another application's environment cannot silently change the destination.
Configuration
| Option |
Default |
dsn |
Required; HTTPS, or HTTP loopback for a local relay |
recordInputs / recordOutputs |
false unless explicitly enabled |
environment |
personal |
maxContentLength |
12,000 characters |
queueCapacity |
256 accepted queued records and active agent runs |
flushTimeoutMs |
2,000 ms |
Credentials in sensitive fields, common token formats, bearer strings and known secret-valued process environment variables are scrubbed. This is not a guarantee that arbitrary secrets embedded in prose can be identified. Do not record sensitive content unless you accept that residual risk.
Telemetry is best-effort, not durable. Producers do not wait on network delivery. Overflow is dropped, requests have a deadline, and shutdown flush is bounded. A failed tool does not automatically mean the agent run failed. Cancellation is not reported as a provider failure.
Verification
bun run check
bun run integration
bun run integration -- --sentry
bun run integration -- --failure
The integration command launches a separate OpenCode server with isolated HOME, configuration and database paths. A local fixture model makes two calls and invokes the real read tool. A local collector verifies the exported transaction. It never discovers, stops or replaces your shared service.
--sentry additionally forwards that synthetic envelope to your configured project in the verification environment. No paid model is called. The command prints the trace ID for a subsequent Sentry query. An HTTP success alone is not proof that Sentry retained the record.
--failure makes the fixture provider reject its second request. This verifies the failed agent transaction and correlated error report without breaking a real session.
Set OPENCODE_TEST_BINARY to choose a different OpenCode executable. The default is the local macOS desktop 2.2.7 CLI. Test diagnostics stay in a dedicated temporary directory.
Limits
- No capture before plugin loading, after a forced kill, or after an out-of-memory termination.
- A fatal process exception may terminate before asynchronous export finishes. The plugin does not change crash behavior to force delivery.
- Caught UI errors that never reach global browser error events are not automatically visible.
- The GUI API is experimental. The bundle is built and listener behavior is tested; a successful build alone does not prove compatibility with every desktop/web host.
- Title and transient-generation usage is not collected: the host's per-request usage event is internal and unavailable to public plugin subscriptions.
- Raw HTTP headers, provider credentials and raw WebSocket frames are not collected.
- No standalone metrics exporter, replay, profiling or native minidump upload. Usage and costs are span attributes. Existing native OTLP export is a separate integration.
- Up to 512 completed spans and 128 in-flight model/tool spans are retained per run. Very long runs may lose detail. Reported costs are the host's estimates, not billing reconciliation.
Related work
Scott Tolinski's original monitor and thelooter's V2 port already cover much of the server-side use case. Their event mapping informed this implementation. This project adds an Effect-managed pipeline and separate client adapters rather than claiming that monitoring did not already exist.