Sessions
Group traces into sessions so you can view and analyze multi-turn conversations, chatbot flows, and per-session metrics in Observe.
What it is
Sessions in Observe are groups of traces that belong together—for example one conversation or one user journey. Each session has an identifier (session name) and is scoped to a project. The Observe UI lists sessions for a project so you can filter by time, see session-level metrics (duration, cost, token usage), open a session to see its traces in order, and jump to a single trace for full span detail. Evals and other metrics can be viewed at the session or trace level. The feature exists so multi-turn and chatbot-style flows are easy to analyze without hunting for related traces by hand.
Use cases
- Chatbot and multi-turn — Group all traces for a single conversation so you can review the full flow and debug a specific turn.
- User journey — Treat one user’s sequence of requests as a session to analyze behavior and drop-off.
- Session-level metrics — See duration, total cost, and total tokens per session instead of per trace only.
- Filtering and drill-down — Filter sessions by time, then open a session to see its traces and open a trace to see spans and evals.
- Bookmarking — Mark sessions as bookmarked in the UI for quick return.
How to
Associate traces with a session
For a trace to appear in a session, the span (or trace) must carry a session identifier. In the OTLP path this comes from the span attribute session.id (or session_name after ingestion). When a span is ingested with this attribute, the backend resolves the session by name and project: it creates a TraceSession if needed and links the trace to that session. All traces with the same session name in the same project form one session.
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({
project_type: ProjectType.OBSERVE,
project_name: "FUTURE_AGI"
});
const tracer = traceProvider.getTracer("manual-instrumentation-example");
tracer.startActiveSpan("HandleFunctionCall", {}, (span) => {
// Set the session.id attribute
span.setAttribute("session.id", "my-session-id");
// End the span
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:
from fi_instrumentation import using_session
with using_session(session_id="my-session-id"):
# Calls within this block will generate spans with the attributes:
# "session.id" = "my-session-id"
...import { context, propagation } from "@opentelemetry/api";
const sessionId = "my-js-session-id"; // Example session ID
const activeContext = context.active();
const baggageWithSession = propagation.createBaggage({
"session.id": { value: sessionId }
});
const newContext = propagation.setBaggage(activeContext, baggageWithSession);
context.with(newContext, () => {
// Calls within this block by auto-instrumented libraries (like traceAI)
// should generate spans with the attribute: "session.id" = "my-js-session-id"
// e.g., myInstrumentedFunction();
});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 use View Trace to see span-level detail and evaluation results.
Note
For more on setting session.id with Trace AI helpers and context, see the manual tracing guide.