User Tracking

User Tracking connects your LLM activity to the people using your application. By associating traces with user identifiers, you gain visibility into individual consumption patterns, can debug issues for specific users, and understand how different segments interact with your system. This feature is optional but highly recommended.

Why User Tracking Matters

System-wide averages tell you how your application performs overall, but not how individual users experience it. User tracking lets you:

• Identify your heaviest consumers and understand usage distribution

• Spot users experiencing disproportionate errors or latency

• Compare behavior patterns across different user segments

• Track individual user journeys through your LLM application

• Monitor token usage, costs, and other metrics on a per-user basis

• Filter and segment traces to debug user-reported issues

---

User Views

All Users View

This view lets you segment by overall token usage, number of traces, and total cost making it easy to identify power users and usage patterns.

Individual User View

Selecting a user opens their detail page with:

• Aggregated statistics (observations, traces, tokens, cost, active period)

• Complete trace history for that user

• Session history showing multi-turn conversations

• Score history for quality tracking

This view is useful for debugging user-reported issues, understanding power-user behavior, and auditing activity for compliance or support purposes.

---

Properties of a User

Property	Description
User ID	Unique identifier for the user
First Event	Timestamp of the user's first recorded trace
Last Event	Timestamp of the user's most recent trace
Total Events	Number of traces attributed to this user
Total Tokens	Cumulative token consumption across all activity
Model Cost	Accumulated cost of all operations for this user

---

Tracking Users

To track users, include a user_id when creating traces. This can be any unique string that identifies a user in your system: a username, email address, internal ID, or any other distinct identifier. The field is optional, but populating it unlocks the full set of user-centric analytics.

Basic User Tracking

with interactiveai.start_as_current_observation(
    as_type="span",
    name="your_trace_name"
) as span:
    span.update_trace(user_id="your_user_id")

Combining User ID with Session ID

Track both the platform user and their conversation session:

with interactiveai.start_as_current_observation(as_type="span", name="your_trace_name") as span:
    span.update_trace(
        user_id="your_user_id",
        session_id="your_session_id",
        input={"message": "What's the weather like?"}
    )

Adding User Metadata

Include additional user context using tags or metadata:

with interactiveai.start_as_current_observation(as_type="span", name="your_trace_name") as span:
    span.update_trace(
        user_id="your_user_id",
        tags=["premium_tier", "mobile_app"],
        metadata={
            "user_plan": "enterprise",
            "app_version": "2.1.0"
        }
    )

Tracking Users Across Multiple Traces

The same user_id links all of a user's activity together:

user_id = "your_user_id"

# First interaction
with interactiveai.start_as_current_observation(as_type="span", name="your_trace_name") as span:
    span.update_trace(user_id=user_id, input={"query": "python tutorials"})

# Second interaction (same user, different trace)
with interactiveai.start_as_current_observation(as_type="span", name="your_trace_name") as span:
    span.update_trace(user_id=user_id, input={"topic": "python basics"})

Both traces will appear in the user's detail page, giving you a complete view of their activity.