Sessions

Sessions let you group related traces together. They’re most commonly used for multi-turn chat conversations, where each user message produces a separate trace — but all messages belong to the same conversation.

Once grouped into a session, XeroML provides a Session Replay view that stitches all traces into a single chronological timeline, making it easy to debug conversation flow and understand how context evolved across turns.

Session ID

Sessions are identified by a sessionId — any US-ASCII string under 200 characters. Typically this is a UUID generated when the conversation starts and stored client-side (e.g., in a cookie or local storage).

Implementation

Use propagate_attributes to attach a session ID to all observations in a request:

from xeroml import observe, propagate_attributes

@observe()
def handle_message(user_message: str, session_id: str) -> str:
    with propagate_attributes(session_id=session_id):
        response = generate_response(user_message)
        return response

The session_id propagates to all nested observations automatically.

import { startActiveObservation, propagateAttributes } from "@xeroml/tracing";

async function handleMessage(userMessage: string, sessionId: string) {
  return await startActiveObservation({ name: "handle-message" }, async () => {
    return await propagateAttributes({ sessionId }, async () => {
      return await generateResponse(userMessage);
    });
  });
}

from xeroml.openai import openai
from xeroml import propagate_attributes

def chat(message: str, session_id: str):
    with propagate_attributes(session_id=session_id):
        response = openai.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": message}]
        )
    return response.choices[0].message.content

from xeroml import CallbackHandler, propagate_attributes
from langchain_openai import ChatOpenAI

def chat(message: str, session_id: str):
    handler = CallbackHandler()
    llm = ChatOpenAI(model="gpt-4o", callbacks=[handler])

    with propagate_attributes(session_id=session_id):
        response = llm.invoke(message)

    return response.content

Session Features

Session Replay View all traces in a session as a single timeline. Each turn is shown with its inputs, outputs, and evaluation scores.

Public Links Share sessions via a public link for collaborative debugging or async review. Useful for flagging issues with non-technical stakeholders.

Bookmarking Bookmark sessions of interest for later review or dataset creation.

Session-level Scores Annotate sessions with scores via the UI or programmatically via the API:

from xeroml import get_client

xeroml = get_client()
xeroml.score_session(
    session_id="your-session-id",
    name="overall-quality",
    value=0.85,
)