Group Traces by Session
Group traces into sessions so you can view and analyze multi-turn conversations, chatbot flows, and per-session metrics in Observe.
About
Sessions group related traces together under a single identifier. A chatbot conversation, a multi-step user journey, or any sequence of LLM calls that belong to the same flow can be tracked as one session. The Observe dashboard shows sessions with their duration, cost, and token usage so you can review the full flow, drill into individual traces, and spot where things went wrong.
When to use
- Chatbot and multi-turn flows: Group all traces for a single conversation so you can review the full exchange and debug a specific turn.
- User journey analysis: Treat one user’s sequence of requests as a session to understand behavior and find drop-off points.
- Session-level metrics: See total duration, cost, and tokens for an entire session instead of checking each trace individually.
- Filtering and drill-down: Filter sessions by time range, open a session to see its traces, then open a trace to see spans and eval results.
How to
Associate traces with a session
For a trace to appear in a session, the span must carry a session identifier via the session.id attribute. All traces with the same session name in the same project form one session. The backend creates the session automatically when the first trace with that identifier arrives.
Set session.id on a span (manual)
When creating a span manually, set the attribute so the trace is attached to the session:
from fi_instrumentation import register, FITracer
trace_provider = register(
project_type=ProjectType.OBSERVE,
project_name="PROJECT_NAME",
)
tracer = FITracer(trace_provider.get_tracer(__name__))
with tracer.start_as_current_span(
f"SPAN_NAME",
) as span:
span.set_status(Status(StatusCode.OK))
span.set_attribute("session.id", "session123")
span.set_attribute("input.value", "input")
span.set_attribute("output.value", "output")const { register, ProjectType } = require("@traceai/fi-core");
const traceProvider = register({
projectType: ProjectType.OBSERVE,
projectName: "FUTURE_AGI"
});
const tracer = traceProvider.getTracer("manual-instrumentation-example");
tracer.startActiveSpan("HandleFunctionCall", {}, (span) => {
span.setAttribute("session.id", "my-session-id");
span.end();
});Set session for many spans (context)
To tag all spans in a block with the same session, use context so every span gets session.id automatically:
from fi_instrumentation import using_session
with using_session(session_id="my-session-id"):
# All spans created within this block get session.id = "my-session-id"
...import { context, propagation } from "@opentelemetry/api";
const sessionId = "my-js-session-id";
const activeContext = context.active();
const baggageWithSession = propagation.createBaggage({
"session.id": { value: sessionId }
});
const newContext = propagation.setBaggage(activeContext, baggageWithSession);
context.with(newContext, () => {
// All spans created within this block get session.id = "my-js-session-id"
});View sessions in Observe
In the Observe UI, open the project and go to the Sessions view. You can filter by time range, see a list of sessions with duration and metrics, open a session to see its traces, and click View Trace for span-level detail and eval results.
Note
For more on setting session.id with Trace AI helpers and context, see the manual tracing guide.