What gets recorded
Every event has a kind. There are 25:
How much each run records depends on how it started (see How a team works for the two paths):
- Team chat records board changes, runs, tool calls and errors. It writes no
costevents and no trace spans. - The task runner (agent routines on Clawboo Native, Claude Code, Codex and Hermes, and runs started through the API) records all of that, plus a
costevent for each cost report and a trace for each run. - OpenClaw activity that Clawboo did not start, such as an OpenClaw agent’s own cron job or a message from another channel, is still recorded as tool calls and results while Clawboo is connected to the Gateway.
Where to look
Fleet health sorts each agent by its open run: working (an open run with a recent event), idle (no open run), stalled (no event for 5 minutes) or zombie (no event for 30 minutes, so the process is almost certainly gone).
What traces cover
A trace groups one run’s events into a timeline: the run itself, with each tool call inside it. Runs of tasks in the same delegation tree share one trace, keyed on the tree’s top task. Only runs the task runner starts have traces. Team-chat work and OpenClaw routines are recorded as events without a trace, so they never appear in the Traces list or in OpenTelemetry export. Most everyday work happens in team chat, so an empty Traces list is normal if that is how you use Clawboo.Errors and harness bugs
Clawboo sorts every error a run reports into a class, by keywords in its code and message. The first class that fits wins, in the order of this table:
An
Unknown error is flagged as a harness bug: most likely a defect in Clawboo rather than in your prompt or your provider. If you see one, please open an issue with the error text. A PolicyDenied error is never a harness bug; it means a guardrail did its job.
How much the views read, and how long the log keeps
- Fleet health and the delegation graph read the newest 5,000 events, so older agents and tasks drop out of them. A single trace shows at most 5,000 events. The error list shows the newest 500 errors, and its harness-bug count covers only those.
- Nothing prunes the event log or the tool-call audit, so both grow as you use Clawboo. Stored tool results are the exception: they are deleted after 7 days (
CLAWBOO_TOOL_RESULT_TTL_MS). To back up or reset your data, see Data and state.
OpenTelemetry export
Clawboo can also send its traces to an OpenTelemetry collector, such as Jaeger or any OTLP endpoint. Export is off unless you setOTEL_EXPORTER_OTLP_ENDPOINT (or OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) before you start Clawboo. OTEL_SERVICE_NAME sets the service name, clawboo by default. Only task-runner runs have traces, so only those are exported.
The npm package does not include the OpenTelemetry SDK. On an install from npm (
npx clawboo@latest or a global install), setting the endpoint exports nothing. The exporter cannot load, traces stay in the local log, and System Health shows the OTel exporter check as degraded, saying the SDK is not included. Its observability row reads “local event log (OTLP endpoint set, exporter not running)”. Export works where the two packages it needs, @opentelemetry/sdk-node and @opentelemetry/exporter-trace-otlp-http, can be loaded, as when you run Clawboo from a source checkout of the repository.Under the hood
Under the hood
- The log is the
orchestration_eventstable in Clawboo’s SQLite database. Each row has an auto-incrementseq(the order of events, and the cursor for the live stream), a UUIDid, a timestamp, the kind, team, task, agent and runtime ids, trace and span ids, and a scrubbed JSONdatafield. A row with an unknown kind is stored aserror. - The live stream is
GET /api/obs/stream, a Server-Sent Events feed polled every 750 ms that resumes fromLast-Event-ID,?afterSeq=<seq>or?since=<seq>, and that?kinds=narrows to some event kinds. With no cursor it replays the scoped log from the start, then follows it. - Only the server writes to the log. No route adds events from outside it, so board, cost and approval events cannot be forged over HTTP.
- The MCP stdio servers write to this log only when they open the server’s database. The attach configs Clawboo generates set
CLAWBOO_DB_PATHso they do. - Errors are classified on both paths. A refused tool call is recognized as
PolicyDeniedonly in the task runner; in team chat the same refusal is classified by its message.
Related
- Observability: a tour of the Observability and Fleet panels.
- Budgets and guardrails: spend limits, circuit breakers and caps, and the audit log they write to.
- Events and errors: every event kind and error class in detail.
- Observability API: read events, traces and the live stream over REST.
- Environment variables: the OpenTelemetry and retention settings.
- System Health: the checks Clawboo runs at startup, including the OpenTelemetry exporter.