Observability model
When a workflow or agent runs, Culvii captures a structured record of what happened. This page explains what's recorded, where to view it, and what's coming.
The trace events
Every run emits a stream of trace events. The shape:
| Event | When it fires |
|---|---|
run.start | A run begins (manual, scheduled, triggered) |
run.complete | A run finishes successfully |
run.failed | A run finishes with an unrecoverable error |
run.paused | A run pauses, e.g., at a gate() |
run.resumed | A paused run resumes |
step.start | A workflow step begins |
step.ok | A step completes successfully |
step.failed | A step fails |
tool.call | An agent invokes a tool |
tool.ok | A tool call returns successfully |
tool.failed | A tool call fails |
llm.call | An agent calls a language model |
gate.waiting | A gate() step is awaiting approval |
gate.approved | A gate was approved |
gate.rejected | A gate was rejected |
Each event includes:
- The run ID, step ID, and (for agent actions) the agent's DID.
- Timestamp (UTC, microsecond precision).
- Inputs and outputs as structured data.
- Latency, token counts, and cost where applicable.
- Correlation ID linking related events.
Where to view traces
Two surfaces in v1:
The Console. Open a run in console.culvii.com. You see a visual DAG of the workflow, color-coded by step status, with each event expandable to its full payload. This is the primary surface for operators and for debugging in dev.
The CLI (culvii logs). Tail traces in your terminal:
culvii logs --run r_a7f3 --follow
This emits the same events as a stream of structured log lines. Tools like Cursor and Claude Code can read the stdout form directly when you're iterating with culvii dev.
What's not captured
A few things we deliberately don't capture:
- The full content of model context windows. We capture the prompt and response, but not arbitrary intermediate state the agent might have stashed in scratchpads. If you need that level of detail, log it explicitly from your tool code.
- External system internals. When a tool calls your HTTPS API, we capture the request and response at the tool boundary; we don't capture what your API did internally.
Cost and token attribution
Every llm.call event records token counts (input, output) and approximate cost based on the model provider's published pricing. The Console aggregates this per run, per workflow, and per workspace.
Cost data is informational in v1. Cost-based policies (e.g., "block this agent if it spends more than $10/day") are part of cost governance, which is on the roadmap.
What's on the roadmap
- Pluggable trace exporters — emit Culvii traces to your existing OpenTelemetry collector, Datadog, Honeycomb, etc.
- Custom event schemas — define your own event types from inside tool code.
- Cost governance — policy enforcement based on token usage and spend.
- Long-term trace retention tiers — currently traces are retained for a fixed period; configurable retention is coming.
What's stable in v1
The event shape and field names listed above are committed. We will not break them without a major version bump in Kit and CLI.
The Console UI for traces is not version-stable — we change it frequently. If you build automation against the underlying data, do it via the Platform API (when public) or culvii logs, not by scraping the Console.