Find and read a run

A trace is useful only when you can answer a concrete question with it. This guide shows how to go from a customer report or suspicious metric to a defensible account of what the agent actually did.

Use one question to guide the read. For example:

Why did the refund assistant quote policy v2 when the request date was after that policy expired?

That question tells you which outcome to confirm and which retrieval, tool, and model evidence matters. Reading every field without a question creates activity, not understanding.

Before you search

Collect any identifiers that narrow the candidate set:

• approximate timestamp and timezone;
• project and workflow;
• session ID or user ID;
• trace ID, tag, or metadata value your application records (for example an environment or release);
• error text, tool name, or distinctive output;
• source platform if traces were imported.

Start with the narrowest trustworthy fact. A trace ID is definitive; a user ID plus a ten-minute window is usually better than a broad behavioral search.

Find the run

Use View by to switch the list between Traces, Sessions, and Users when the report names a conversation or a customer rather than one run. Use Display preferences to show or hide columns such as Workflow, Latency, Cost, Tags, Session, User ID, and Trace ID, to group rows (for example by date), or to change the ordering. The Detections, Evals, and Comments columns show which runs already carry a label or discussion; select a detection chip to open the trace focused on that match.

Use the trace list to narrow the population, then open one run to reconstruct its execution.

Read the run from outcome to cause

Opening a trace shows the whole run as a transcript, already at its final state. First identify the final outcome. Then work backward through the steps that could have produced it.

1. Read the root input and final output.
2. Find the span that produced or assembled the output.
3. Inspect the model input, tool results, and retrieved context available at that point.
4. Continue backward until you find the earliest evidence that explains the divergence.
5. Check sibling branches for contradictory or ignored evidence.

The root is a parentless span of kind WORKFLOW, CHAIN, AGENT, MCP_TOOL, or LLM. The structure shows an eligible semantic root at the top, with agent, model, tool, retrieval, and other operations beneath it. If a run you expected to see as one trace appears as several, the application may not give those calls a shared root; see span kinds.

This avoids a common mistake: labeling the final LLM call as the root cause when an earlier retrieval, tool, or state-management step supplied the wrong information.

Choose the right view

All views live on the trace page. The trace index and the graph and timeline toggles sit at the top left of the transcript.

The timeline answers when work happened; it does not replace reading the content of the relevant spans.

Hover a step to reveal its actions, then select Attributes to open the span inspector. On the Attributes tab, hover a metadata value to filter traces by it in a new tab, which is a quick way to find other runs that share that value. Search this trace in the header finds a span name or a phrase in span content within the current run. For a multi-turn session, the trace page opens the session conversation, and Replay offers Replay this turn or Replay full session.

Read each kind of evidence

Model calls

Compare the effective instructions and context with the output. Check model identity, settings, token truncation, structured-output errors, and whether the model received the facts needed to succeed. The input shown is the payload the SDK recorded for the provider call, so it reflects your code's prompt formatting.

Tool calls

Check the selected tool, arguments, return value, status, retries, and whether the agent used the result. A successful HTTP response can still contain a business-level failure.

Retrieval

Inspect the query, returned chunks, ranking, document version, and whether relevant context survived into the model prompt. Separate “the right document was not retrieved” from “it was retrieved but ignored.”

Agent and workflow steps

Look for routing decisions, repeated loops, missing handoffs, state overwritten between steps, and branches that completed after the final answer was already chosen.

Add the surrounding evidence

Detections tell you which known conditions matched. Eval results tell you how a reviewer judged the run. Comments preserve context and decisions. None of them replaces the underlying span: open the evidence that supports the label or verdict.

On the trace page, detection matches appear on the steps they flagged, and findings that apply to the whole run appear above the transcript. When you open a trace from a detection, use the match bar to move between flagged steps. Eval chips on a step open that step's evaluation responses. Use Comments in the header to open the discussion, or hover a step and select Comment to anchor a note to it.

Ask a question about the run

Select Ask neat AI in the trace header to open the neat AI panel for the trace you are viewing. It opens with a Trace summary and Quick actions such as What happened in this trace? and Show me any errors, and it answers follow-up questions by reading the run's spans. You can also highlight text anywhere in the trace and select Ask neat AI to attach that passage to your question before you send it. Use History in the panel to return to an earlier conversation.

Use it for bounded questions such as:

Which span first introduced the policy version quoted in the final answer?

Show the slowest tool calls and whether any were retried.

Open the spans it points to before you rely on an answer.

The panel starts from the run you are viewing. For behavioral questions across many runs, use Search across production. If the question needs a root cause, ask it to investigate the trace; see Investigate a failure.

Know when you are done

You can stop reading when you can state:

• the observed outcome;
• the execution path that produced it;
• the earliest supported divergence from expected behavior;
• the evidence for that claim;
• what is still uncertain.

If you can describe what happened but not why, start an investigation. If you cannot identify the run, search across production.

Avoid common reading mistakes

Record the account of what happened

Before moving to an investigation, write a compact evidence summary:

Outcome: The answer quoted policy v2.
Execution: retrieve_policy returned v2, and generate_answer used it.
Earliest divergence: retrieval received no request date.
Evidence: linked retrieval and model spans.
Unknown: whether the date was unavailable or dropped before the call.

This preserves the distinction between the observed execution and the causal question that still needs investigation. To share the raw run with someone outside Neatlogs, open Trace actions in the trace header and choose Copy Markdown, Download Markdown, or Download CSV.

Frequently asked questions

Why is a span missing?

The source may not instrument that operation, context may have been lost across a boundary, or a short-lived process may have exited before export. Compare the application path with the captured tree and review missing traces.

Why does a trace show Processing?

Neatlogs has received the trace but has not finished finalizing it, so some derived data may not appear yet. Processing failed means finalization did not complete. If that persists, contact support with the trace ID.

Why do imported and native traces look different?

Neatlogs normalizes both, but it cannot reconstruct fields or relationships the source did not provide.

Should I judge the whole trace or one span?

Judge the trace when quality depends on the end-to-end result. Judge a span when the standard applies to one operation and its local evidence.

Next step

Investigate the failure →