Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tracia.io/llms.txt

Use this file to discover all available pages before exploring further.

Sessions provide automatic span linking for multi-turn conversations. Each call in a session is automatically connected to previous calls, making it easy to visualize conversation flows in the Tracia dashboard.

​
Creating a Session

from tracia import Tracia

client = Tracia(api_key="tr_your_api_key")

# Start a new session
session = client.create_session()

# Or continue an existing trace (e.g., across HTTP requests)
session = client.create_session(
    trace_id="tr_existing_trace_id",
    parent_span_id="sp_last_span_id",  # optional: chain from a specific span
)
OptionTypeDescription
trace_idstrContinue an existing trace instead of creating a new one
parent_span_idstrChain from a specific span in the existing trace

​
Basic Usage

session = client.create_session()

# First call - creates the session (trace)
result1 = session.run_local(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What is the weather?"}],
)
# result1.span_id = "sp_abc123"
# session.trace_id = "tr_xyz789" (session ID)

# Second call - automatically linked to first
result2 = session.run_local(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "What is the weather?"},
        result1.message,
        {"role": "user", "content": "What about tomorrow?"},
    ],
)
# Automatically sends: trace_id="tr_xyz789", parent_span_id="sp_abc123"

# Third call - chain continues
result3 = session.run_local(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "What is the weather?"},
        result1.message,
        {"role": "user", "content": "What about tomorrow?"},
        result2.message,
        {"role": "user", "content": "Thanks!"},
    ],
)
# Automatically sends: trace_id="tr_xyz789", parent_span_id=result2.span_id

​
How It Works

When you use a session:
  1. First call - A trace ID is generated to group all spans in this session
  2. Subsequent calls - Automatically include:
    • trace_id: The session’s trace ID (groups all spans together)
    • parent_span_id: The previous span’s ID (creates a chain)
This creates a tree structure in the Tracia dashboard where you can see the full conversation flow.

​
TraciaSession Methods

​
run_local() / arun_local()

Same as client.run_local() but with automatic span linking: 
# Sync
result = session.run_local(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

# Async
result = await session.arun_local(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

​
trace_id

Property that returns the session’s trace ID (groups all spans): 
trace_id = session.trace_id
# Returns: "tr_abc123" or None if no calls made yet

​
last_span_id

Property that returns the most recent span ID: 
last_id = session.last_span_id
# Returns: "sp_xyz789" or None if no calls made yet

​
reset()

Clears session state to start a new trace: 
session.reset()
# Next call will start a new trace session

​
Continuing Existing Traces

Use create_session with a trace_id to continue a trace across requests or services: 
# Django view - continue a trace from a previous request
def chat(request):
    data = json.loads(request.body)
    message = data["message"]
    trace_id = data.get("trace_id")
    last_span_id = data.get("last_span_id")

    session = client.create_session(
        trace_id=trace_id,              # Continue the same trace
        parent_span_id=last_span_id,    # Chain from the last span
    )

    result = session.run_local(
        model="gpt-4o",
        messages=[{"role": "user", "content": message}],
    )

    return JsonResponse({
        "text": result.text,
        "trace_id": session.trace_id,
        "last_span_id": result.span_id,
    })

​
Manual Span Linking

If you prefer manual control, you can use trace_id and parent_span_id directly: 
# First call
result1 = client.run_local(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

# Second call - manually link
result2 = client.run_local(
    model="gpt-4o",
    messages=[...],
    trace_id=result1.span_id,       # Use first span as session ID
    parent_span_id=result1.span_id,  # Parent is the first span
)

# Third call - continue chain
result3 = client.run_local(
    model="gpt-4o",
    messages=[...],
    trace_id=result1.span_id,       # Same session
    parent_span_id=result2.span_id,  # Parent is the second span
)

​
Streaming with Sessions

Sessions work with streaming: 
session = client.create_session()

stream = session.run_local(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Write a poem."}],
    stream=True,
)

for chunk in stream:
    print(chunk, end="")

result = stream.result.result()  # Future[StreamResult] → StreamResult
# session.trace_id is now set

​
Use Cases

  • Chat applications: Track full conversation threads
  • Multi-step agents: Link planning, execution, and verification steps
  • RAG pipelines: Connect retrieval and generation spans
  • Debugging: Easily find all spans related to a user session