Prerequisites
- An agent in your project.
- Advanced mode turned on. Tracing is on when Advanced mode is on. To turn it on, click the flask icon in the header, or use the settings. The mode is off by default.
Restrictions
- Tracing shows data from the current test session. The interaction panel keeps this data only in your browser tab. It clears the data when you reset the session or start a voice call, live follow, simulation, or Playbook run.
- The trace doesn’t show the results of guardrails. If a guardrail blocks a response, you see it only indirectly, for example, as the stop reason Blocked by the content filter on an LLM call.
- For voice calls, the trace shows the call transcript and the call events. It doesn’t offer audio playback or call recordings.
- Tracing data isn’t available through the Cognigy OData endpoint.
Working with tracing
Inline trace summary
With Advanced mode on, each turn shows a trace summary below its last message. The summary shows the number of spans, the duration of the turn, and the number of errors, for example,5 spans · 2.40s · 1 error. To show or hide the spans of a turn, click Expand trace details or Collapse trace details.
By default, the interaction panel expands the spans of each turn. To change this, turn off Tracing spans per turn in the settings. To show only spans with errors in the full tracing view, turn on Display only error spans in the settings. This filter doesn’t apply to the inline trace summary.
If an agent turn used a custom system prompt, the summary and the turn header show a Custom badge. Hover over the badge to see the explanation. This badge isn’t related to the Custom source of skills and tools.
Full tracing view
To see all turns of the session in the main area of the page, click Full tracing view in a trace summary. The full tracing view shows the following:
To open the details of a span, click it. The span details sidebar opens. To close the full tracing view, click Close execution trace.
Span types
The trace shows spans such as the following for agents:
The trace also shows spans for flows, such as Flow Transition, Intent matched, System Slot Match, Node, Debug message, Debug error, Node error, Track Goal, and System: JSON data payload. LLM calls of flows also appear as LLM call spans.
Spans of skills, tool calls, and tool results show where the tool or skill comes from: System (built-in tools), Custom, or MCP (Model Context Protocol). Tool calls and tool results appear one level below the LLM call that triggered them.
LLM call details
To see how the language model handled a call, click an LLM call span. The span details sidebar shows the following:- Model and performance. The Model that answered the call, the Model latency that the provider measured, the Stop reason, and the number of Retries. For streaming calls, also the Time to first token. If a value isn’t available, the sidebar shows Not reported. The stop reason is one of Completed, Called a tool, Called a function, Hit the token limit, Blocked by the content filter, or Unknown.
- Tokens. The prompt, completion, reasoning, cache read, cache write, and uncached tokens. The cache values are part of the prompt tokens.
- Pace. The Time per output token, the Tokens per second, and the Inter-token latency. These values are available only for streaming calls.
- Fallback model. If a fallback model answers the call, the span shows a warning ring around its status dot. The callout Served by a fallback model explains why the primary model didn’t answer. A fallback is a warning, not an error. Failed attempts lists each model that Cognigy tried and the error that the model returned.
System prompt details
For agent LLM calls, the span details sidebar can show a System prompt section. It shows the following:- Custom prompt configured. Whether the agent has a custom system prompt.
- Prompt sent. The prompt that Cognigy sent to the model: Custom, Default, or Built-in.
- Build time and Evaluation time. How long Cognigy took to build the prompt and to evaluate its expressions.
- Evaluations. Each expression in the prompt with its type, CognigyScript or Data, and its value.
- Prompt text. To read the prompt, click Show prompt. To copy it, click Copy the system prompt.