Understanding Spans, Traces, and Sessions in Deepchecks

Agentic systems naturally form a hierarchy:

• Span → the atomic interaction (LLM call, tool call, plan step, retrieval step, etc.)
• Trace → a full execution composed of one or more spans
• Session → one or more traces grouped by a shared user or conversation

In Deepchecks:

• A span is represented as an Interaction and can be filtered, inspected, and compared in the Interactions screen.
• A trace is represented by the Root Interaction Type, which aggregates all descendant span data and de-facto exposes trace-level metrics.
• A session is visible on the Sessions screen, showing patterns across multi-turn experiences.

This structure ensures you can analyze your agentic system from the smallest LLM call all the way up to the full end-to-end workflow.

Uploading Agent Data to Deepchecks

Deepchecks supports ingesting agentic data in two ways:

Auto-Instrumentation with Popular Agent Frameworks

If you’re using frameworks like CrewAI, LangGraph, or Google ADK, you can enable full tracing and logging with only a few lines of code. Deepchecks automatically captures:

• Span hierarchy
• Span attributes
• Tool calls and their inputs/outputs
• LLM completions
• Agent-level steps
• More

Tracing is done via our instrumentation layer, and the structure is mapped directly into Deepchecks’ Interaction Types - no manual formatting needed.

Manual Logging (Full Control)

If you prefer to push logs manually, Deepchecks allows you to send spans and define the parent-child relationships yourself. This is useful mainly when you have a custom orchestrator or if you’re modifying or transforming the metadata before sending it. The key requirement is maintaining the span hierarchy so Deepchecks can reconstruct the trace and apply the correct built-in configurations.

Built-In Interaction Types for Agentic Workflows

To provide strong value out–of–the–box, Deepchecks automatically assigns every span to an Interaction Type:

• Root (always present)
• Agent
• Chain
• LLM
• Tool
• Retrieval

These interaction types determine which properties will be calculated for each span, what auto-annotation flow will be applied, and how the trace will be displayed. Because each type has its own logic, Deepchecks can provide accurate, research-backed evaluation even before any customization.