Traces
Every workflow execution and agent session 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 session 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 execution; everything else nests beneath it.
| 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 | An agent session, with token usage. |
gen_ai.chat | A single model call. |
gen_ai.execute_tool | A tool invocation. |
swirls.sandbox.exec | A process run inside a sandbox. |
swirls.workflow.invoke | A nested workflow, linked to its own execution trace. |
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.
Viewing traces in Swirls
Everything lives in the product. Open a project in Swirls Cloud and go to Traces.
- Activity list. Recent executions and agent sessions, with duration, status, and the trigger that started each one. Filter 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 model-call spans, so you can read the spend of a single run.
This is the same trace data whether or not you ever export. The activity view in Swirls reads directly from it.
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
Prompt and completion bodies are redacted by default. Secrets and sandbox command text are never recorded on a span. A span captures structure: timings, token counts, model and tool names, cost, and status, not the contents of a message.
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. See Trace export.