/phoenix-tracing

Sessions (Python)

Track multi-turn conversations by grouping traces with session IDs.

Setup

from phoenix.otel import using_session

with using_session(session_id="user_123_conv_456"):
    response = llm.invoke(prompt)

Best Practices

Bad: Only parent span gets session ID

from phoenix.otel import SpanAttributes
from opentelemetry import trace

span = trace.get_current_span()
span.set_attribute(SpanAttributes.SESSION_ID, session_id)
response = client.chat.completions.create(...)

Good: All child spans inherit session ID

with using_session(session_id):
    response = client.chat.completions.create(...)
    result = my_custom_function()

Why: using_session() propagates session ID to all nested spans automatically.

Session ID Patterns

import uuid

session_id = str(uuid.uuid4())
session_id = f"user_{user_id}_conv_{conversation_id}"
session_id = f"debug_{timestamp}"

Good: str(uuid.uuid4()), "user_123_conv_456" Bad: "session_1", "test", empty string

Multi-Turn Chatbot Example

import uuid
from phoenix.otel import using_session

session_id = str(uuid.uuid4())
messages = []

def send_message(user_input: str) -> str:
    messages.append({"role": "user", "content": user_input})

    with using_session(session_id):
        response = client.chat.completions.create(
            model="gpt-4",
            messages=messages
        )

    assistant_message = response.choices[0].message.content
    messages.append({"role": "assistant", "content": assistant_message})
    return assistant_message

Additional Attributes

from phoenix.otel import using_attributes

with using_attributes(
    user_id="user_123",
    session_id="conv_456",
    metadata={"tier": "premium", "region": "us-west"}
):
    response = llm.invoke(prompt)

LangChain Integration

LangChain threads are automatically recognized as sessions:

from langchain.chat_models import ChatOpenAI

response = llm.invoke(
    [HumanMessage(content="Hi!")],
    config={"metadata": {"thread_id": "user_123_thread"}}
)

Phoenix recognizes: thread_id, session_id, conversation_id

See Also

• TypeScript sessions: sessions-typescript.md
• Session docs: https://docs.arize.com/phoenix/tracing/sessions