Traces
Every workflow execution and agent turn is an OpenTelemetry trace. Inspect any run span by span in Swirls Cloud.
What it is. Full observability for every run, built into Swirls Cloud. Every workflow execution and every agent turn is one OpenTelemetry trace. Nodes, agent turns, model calls, tool invocations, and sandbox processes are spans inside that trace. You view it all directly in the UI. There is nothing to set up and nothing to export first.
Use it when you want to see what a run actually did: which nodes ran and in what order, how long each step took, which model and tools an agent used, token usage and cost, and exactly where a run failed.
Works with workflows and agents. Every hosted run produces a trace automatically. There is nothing to instrument.
Traces are built in. If you also want your runs in your own observability tool, you can export them over OTLP. That is optional and additive. It does not change what you see in Swirls.
The trace model
A run is a tree of spans. The root is the run; everything else nests beneath it. A workflow execution roots at swirls.graph.execution. An agent reached over the API or a chat channel roots at gen_ai.invoke_agent; in a multi-turn chat each turn is its own trace, grouped by a shared session id.
| Span | What it represents |
|---|---|
swirls.graph.execution | The workflow run. The root span. |
swirls.node.execution | One node in the workflow. |
gen_ai.invoke_agent | One agent turn, with token usage. |
gen_ai.chat | A single model call. |
ai.toolCall | A tool the model called. |
gen_ai.execute_tool | An agent invoking a workflow as a tool. |
swirls.sandbox.exec | A process run inside a sandbox. |
swirls.workflow.invoke | A nested workflow, linked to its own execution trace. |
swirls.trace.complete | A zero-duration sentinel marking the trace finished. |
Spans follow the OpenTelemetry GenAI semantic conventions, so model names, token counts, tool names, durations, and status read the same way they do in any OpenTelemetry tool.
For the full definition of each span and how the tree nests, see the Span spec. For every attribute key on a span, with its type and content policy, see the Attribute schema.
Viewing traces in Swirls
Everything lives in the product. Open a project in Swirls Cloud and go to Traces.
- Run list. Recent executions and agent sessions, with duration, status, token totals, and the trigger that started each one. Filter by status, workflow, or trigger to find the run you care about.
- Waterfall. Select a run to open its span tree. Each span shows its duration, status, and attributes, so you can see where time went and which step failed.
- Agent drill-down. Open an agent session to follow its turns, the model calls inside each turn, and the tools it ran, with token usage on each call.
- Cost and tokens. Token counts and cost roll up from the run's spans at a single layer, so you can read the spend of a single run without double-counting.
- Parent run. A nested workflow links back to the run that invoked it, so you can walk a chain of executions.
This is the same trace data whether or not you ever export. The Traces view reads directly from it.
Live status
Spans reach the trace store when they end, so a trace fills in as the run proceeds:
- The currently running span, and any open ancestor, is not visible yet.
- The root span ends last, so a run's final status and total duration land at completion. Until then the run shows as running, with a duration that grows as spans arrive.
- The
swirls.trace.completesentinel is the definitive signal that no more spans are coming.
For per-step detail on an in-flight run, open the run itself rather than its trace.
Retention
Traces are kept for 90 days. Your durable run state lives separately, so an execution's record and outputs are unaffected by trace retention.
Privacy
What a span captures splits into structure and content. Structure is always recorded: timings, token counts, model and tool names, cost, and status. Content is run I/O: node inputs and outputs, prompts, completions, and sandbox command text. Content capture is governed by a per-project policy (full, redacted, or off) in project settings. The policy gates at capture time: under redacted or off the content never reaches a span, so it cannot leak through a query or a later export. Secrets are never recorded on any span. See Content policy.
Correlation
Traces use W3C trace context. When the caller that triggers a run propagates traceparent into Swirls, the run's trace links to your upstream trace, so a Swirls execution shows up in line with the rest of your system.
Sending traces to your own backend
Viewing in Swirls needs no export. If you do want the same runs alongside the rest of your system, you can stream a live copy to your own observability tool over OTLP, with presets for Datadog, Honeycomb, New Relic, Grafana Tempo, and Neatlogs. See Trace export.