Traces, spans, and sessions
Learn how Neatlogs represents one run, the operations inside it, and related runs over time.
A trace is the evidence for one execution. Spans explain the work inside that execution. A session connects separate executions that belong to the same larger interaction.
Session: refund conversation for customer 42
├── Trace: customer asks whether order 781 is refundable
│ ├── Span: classify intent
│ ├── Span: retrieve refund policy
│ ├── Span: look up order 781
│ └── Span: generate answer
└── Trace: customer asks when the refund will arrive
├── Span: load conversation context
├── Span: look up refund status
└── Span: generate answerThese boundaries determine what you can search, evaluate, detect, investigate, and compare later.
Trace: one complete execution
A trace represents one request, job, or agent run from its entry point to its outcome. It normally carries a trace ID, root input and output, status, timing, and aggregate fields such as tokens or cost when the instrumentation provides them.
The right trace boundary matches the unit people will ask about:
| Application behavior | Useful trace boundary |
|---|---|
| Chat assistant | One user turn and its response |
| Research agent | One complete research task |
| Document pipeline | One document processed from input to result |
| Background support workflow | One ticket-handling attempt |
| Browser agent | One assigned goal or meaningful task |
Do not split one logical execution into separate traces merely because it crosses a service or process. Propagate trace context so the downstream work remains connected. Start another trace when a new independent execution begins.
Span: one operation inside the trace
A span records one timed operation and its relationship to the rest of the run. Common span kinds include workflow, agent, chain, LLM, tool, MCP tool, retrieval, reranking, embedding, vector store, memory, log, and guardrail work.
A useful span answers:
- what operation ran;
- when it started and ended;
- what input it received;
- what output or error it produced;
- which parent operation called it;
- which model, tool, or attributes describe it.
For the refund trace, the retrieval span can show the query and returned documents. The tool span can show the order ID and API response. The LLM span can show the prompt context and generated text. Together they explain how the final answer was produced.
Parent and child relationships
Spans form a tree through parent IDs.
refund_workflow
├── classify_intent
├── gather_context
│ ├── retrieve_policy
│ └── lookup_order
└── generate_responseThe tree answers which operation caused or contained another. It is different from timing: sibling spans may run sequentially or at the same time.
The root span
Every trace is anchored by a root span: a parentless span of kind WORKFLOW, CHAIN, AGENT, MCP_TOOL, or LLM. In the current Python and TypeScript SDKs, a lone wrapped model call uses its LLM span as the root; the Go SDK opens a WORKFLOW root around it instead. A standalone non-root operation such as TOOL, GUARDRAIL, or RETRIEVER gets one automatic WORKFLOW parent, so it also renders without extra code.
Each wrapped call with no surrounding context becomes its own trace. When one run makes several calls, or mixes provider calls with your own functions, give the run its own root, such as a WORKFLOW, AGENT, or CHAIN span around the entry point. The calls then nest under that root, and automatic rooting steps aside. In the refund example above, refund_workflow is the root. See span kinds for which layer emits which kind.
Names and kinds serve different jobs
The kind describes the broad operation category, such as LLM or TOOL. The name describes its role in your application, such as retrieve_refund_policy or lookup_order.
Stable, specific names become useful filters and landmarks. Names such as run, invoke, or call make unrelated operations difficult to distinguish.
Session: related traces over time
A session groups separate traces that belong to one larger interaction, such as a chat conversation or a multi-turn agent task. Each turn is its own trace. Your application supplies a stable session ID on the root of every turn, and traces that share it form one session. Neatlogs does not infer session membership from similar text or the same user.
If a trace arrives without a session ID, Neatlogs uses its trace ID as the session ID. The trace becomes a single-turn session of its own: nothing breaks, but it will not group with other turns. See Sessions for where each SDK takes the ID.
A session ID answers which interaction? An end-user ID answers which person or account? One user can have many sessions, and one session can contain many traces. Set the end-user ID in the same place as the session ID, on the root of each turn; see End-user identity.
When one session starts another, for example a parent agent delegating to a child agent, the TypeScript and Go SDKs can record the parent session ID on the child session's root (session lineage). The Python SDK does not expose it yet. Neatlogs keeps it as session metadata on that root span. It does not merge the two sessions or nest one inside the other.
On traces, use View by to switch the list from Traces to Sessions or Users. Opening a trace that belongs to a multi-turn session shows the whole session conversation.
Use sessions when a later trace depends on context from earlier traces. For example, a follow-up question such as “When will it arrive?” is difficult to understand without the earlier refund request.
Do not use one permanent session for every event from a customer. That creates an unbounded history that no longer represents one coherent interaction.
Identity and relationships
| Identifier | Connects | Typical use |
|---|---|---|
| Project ID | Telemetry with one access and configuration boundary | Separate applications or controlled data domains |
| Trace ID | All spans in one execution | Open, link, and investigate a run |
| Span ID | One operation | Cite exact evidence |
| Parent span ID | A child operation to its caller | Reconstruct the execution tree |
| Session ID | Related traces | Follow a conversation or multi-run task |
| End-user ID | Activity from one person or account | Search customer impact across sessions |
| Workflow name | Runs of the same application behavior | Compare quality, cost, and latency |
| Environment | Production, staging, or another deployment context | Avoid comparing unlike traffic |
These identifiers are useful only when they remain stable and are propagated consistently.
Time in a trace
Each span has its own start and end time. The trace duration covers the execution, while summing span durations can overcount work because spans may overlap.
Use the timeline to distinguish:
- one slow operation;
- several operations running in parallel;
- repeated retries;
- idle gaps between spans;
- a long parent whose child work was brief.
Timing explains where time was spent. It does not by itself explain why the operation was slow.
Native and imported traces
Native traces arrive through Neatlogs instrumentation. Imported traces arrive from another observability platform. Both can be searched, reviewed, evaluated, detected, and investigated when they contain the required evidence.
Neatlogs normalizes common concepts so imported and native runs can be read consistently. It cannot manufacture information the source did not export.
| Missing source data | Result in Neatlogs |
|---|---|
| Parent IDs | A flatter or disconnected tree |
| Tool input or output | An investigation cannot inspect the call fully |
| Stable session ID | Related traces cannot be grouped reliably |
| Model and token attributes | Model, cost, or token analysis may be incomplete |
| Root input or output | The final request or outcome may be difficult to identify |
Source markers help distinguish imported and native evidence. Keep workflow and environment names aligned if you intend to compare both sources.
Read the same trace in different views
No single view answers every question. All of these live on the trace page, which opens the run as a transcript already at its final state.
| View | Best question |
|---|---|
| Transcript (default) | What did each step receive and return, in order? |
| Trace index | Which operation called which, and where did execution branch? |
| Show graph | Which agent delegated to which tool or sub-agent? |
| Show timeline | What was slow, concurrent, retried, or idle? |
| Span inspector (I/O and Attributes tabs) | What exactly did this operation receive, return, and record? |
| Search this trace | Where does a span name or phrase appear in this run? |
| Session conversation | What happened across related runs in the same interaction? |
| Watch replay | In what order did the steps start and finish? |
For a multi-turn session, the trace page shows the session conversation, and Replay offers Replay this turn or Replay full session. See Find and read a run for where each control sits.
The timeline reveals duration and overlap. Open the span inspector to see the evidence behind a bar.
Session Replay (experimental)
Session Replay is a separate page, labeled experimental, for agentic session replay. It is not in the sidebar: open /sessions in the dashboard. It replays an agent run from its recorded spans as a step-by-step story, with Story and Tree views and optional graph and timeline panels.
- Demos replays bundled sample runs, such as ReAct loop and Hierarchical delegation.
- Live lists traces from the current project and replays the one you pick, one trace at a time.
Session Replay does not capture or replay browser sessions, screens, or user clicks. Everything it shows comes from traces your instrumentation already sent. Because it is experimental, its views and behavior may change. For everyday reading, use the trace page and Watch replay.
Trace-level and span-level judgment
Detections and Evals can operate at different levels. Choose the smallest subject that still contains all required evidence.
| Question | Better level |
|---|---|
| Did the assistant resolve the customer's request? | Trace |
| Did retrieval return a currently valid policy? | Retrieval span |
| Did the agent avoid unnecessary tool loops? | Trace |
| Did this tool call use the required account ID? | Tool span |
If the question depends on several steps, absence, order, or the final outcome, use the trace. If one local operation contains the complete answer, use the span.
Evidence quality sets the ceiling
A complete-looking trace can still omit the information needed for judgment. Before trusting a conclusion, check:
- whether the root input and final output are present;
- whether important tool and retrieval results were captured;
- whether parent relationships are intact;
- whether timestamps and statuses are reliable;
- whether redaction removed evidence required by the question;
- whether the trace ended cleanly or stopped before finalization.
An investigation should state when missing evidence limits confidence.
Common modeling problems
| Symptom | Likely cause |
|---|---|
| One request appears as unrelated traces | Context was not propagated across a boundary, or the calls do not share a root span |
| The tree is flat | Parent span IDs are missing |
| Every operation looks the same | Names describe generic functions instead of business operations |
| The final answer is hard to find | The root or final workflow span does not record it |
| A session is empty or fragmented | Session IDs are missing or inconsistent |
| One session contains months of unrelated work | A user ID was used as the session ID |
| Imported traces lack detail | The source export omitted fields or relationships |
Frequently asked questions
Can a trace contain another trace?
No. Work inside one trace is represented by child spans. Related but separate executions belong in a session.
Can a span exist without a parent?
The root span has no parent and is normally a WORKFLOW, CHAIN, AGENT, MCP_TOOL, or LLM span. Current Python and TypeScript SDKs give a standalone tool, guardrail, or retriever span an automatic WORKFLOW parent. Additional parentless spans may appear when context propagation or imported relationships are incomplete.
Is a workflow the same as a project?
No. A project is a telemetry, access, and configuration boundary. A workflow identifies an application behavior within that project.
Can imported traces use detections and Evals?
Yes, when the imported fields contain the evidence required by the rule or question.
Does Session Replay record browser sessions?
No. Session Replay is an experimental agentic replay built from the spans in your project's traces, not a browser or screen recording, so it needs no extra capture. Its Live mode replays one trace at a time. To follow every turn of a multi-turn session, open one of its traces and select Replay, then Replay full session.