Configure tracing, spans, and capture for debugging and monitoring agent execution

Observability

The observability block configures tracing and capture for your topology. It generates structured trace data that helps you debug agent behavior, identify bottlenecks, and monitor execution in production.

Basic Syntax

observability {
  tracing: true
  spans: [agent, tool, flow]
  capture: [inputs, outputs, errors]
}

Field Reference

Field	Type	Required	Description
`tracing`	boolean	No	Enable or disable tracing (default: `false`)
`spans`	list	No	What to generate spans for
`capture`	list	No	What data to capture in spans
`output`	string	No	File path for trace output
`format`	identifier	No	Output format (e.g. `json`, `otlp`)

Span Types

Span	Description
`agent`	One span per agent execution
`tool`	One span per tool invocation
`flow`	One span per flow edge traversal
`gate`	One span per gate evaluation
`group`	One span per group discussion round

observability {
  tracing: true
  spans: [agent, tool, flow, gate]
}

Capture Options

Option	Description
`inputs`	Capture input data for each span
`outputs`	Capture output data for each span
`errors`	Capture error details
`timing`	Capture start time, end time, and duration
`tokens`	Capture token usage per span

observability {
  tracing: true
  spans: [agent, tool]
  capture: [inputs, outputs, errors, timing, tokens]
}

Output Configuration

Write trace data to a file:

observability {
  tracing: true
  spans: [agent, tool, flow]
  capture: [inputs, outputs, errors, timing]
  output: "traces/run.json"
  format: json
}

Formats

Format	Description
`json`	JSON array of spans
`otlp`	OpenTelemetry Protocol format for integration with tracing backends

Full Example

topology observable-pipeline : [pipeline] {
  agent researcher {
    model: sonnet
    tools: [WebSearch, Read]
  }

  agent writer {
    model: sonnet
    tools: [Write]
  }

  agent reviewer {
    model: opus
    tools: [Read]
  }

  flow {
    researcher -> writer -> reviewer
    reviewer -> writer  [when reviewer.verdict == "revise", max 2]
  }

  observability {
    tracing: true
    spans: [agent, tool, flow]
    capture: [inputs, outputs, errors, timing, tokens]
    output: "traces/review-pipeline.json"
    format: json
  }
}

Tips

Enable tracing during development and disable it in production to save overhead, or use otlp format to send traces to a backend like Jaeger or Datadog.
Capturing inputs and outputs produces large trace files. Use selectively.
Combine with metering for a complete picture of both performance and cost.
The tool span type is especially useful for debugging MCP server issues.
Trace output paths are relative to the topology file's directory.

Observability

On this page