Trace Visualization

Agent Health provides built-in trace visualization for monitoring and debugging AI agent executions. If your agent emits OpenTelemetry traces, Agent Health can display them alongside evaluation results.

Live trace monitoring

Navigate to Traces in the sidebar for real-time trace monitoring:

Live tailing — auto-refresh traces every 10 seconds with pause/resume controls
Agent filter — filter traces by specific agent
Text search — search span names and attributes

View modes

Toggle between visualization modes using the view selector:

View	Best For	Description
Timeline	Detailed timing analysis	Hierarchical span tree with duration bars
Flow	DAG visualization	Graph-based view of span relationships

Click the Maximize button on any trace visualization to open full-screen mode with a larger visualization area, detailed span attributes panel, and collapsible sections for complex traces.

Trace comparison

The comparison view supports side-by-side trace analysis:

Aligned view — spans from different runs aligned by similarity
Merged view — combined flow visualization showing all traces
Horizontal/Vertical orientation — toggle layout for your preference

Enabling trace collection

To collect traces from your agent:

Set useTraces: true in your agent configuration:

export default {
  agents: [
    {
      key: "my-agent",
      name: "My Agent",
      endpoint: "http://localhost:8000/agent",
      connectorType: "rest",
      models: ["claude-sonnet-4"],
      useTraces: true,  // Enable trace collection
    }
  ],
};

Configure the OpenSearch traces endpoint in your .env file:

OPENSEARCH_LOGS_ENDPOINT=https://your-cluster.opensearch.amazonaws.com
OPENSEARCH_LOGS_TRACES_INDEX=otel-v1-apm-span-*
OPENSEARCH_LOGS_USERNAME=admin
OPENSEARCH_LOGS_PASSWORD=your_password

Run an evaluation, then navigate to Traces and select your agent from the filter.