Track Users in Traces

Overview

You can track user interactions with your LLM app by setting the user ID in a trace. This allows you to track things such as how much tokens each user is costing you, who interacted with your LLM app the most, etc.

Set Users at Runtime

from langchain_openai import ChatOpenAI
from confident_trace import init, trace_context

init()
model = ChatOpenAI(model="gpt-4o")

def llm_app(query: str, user_id: str):
    with trace_context(user_id=user_id):
        return model.invoke(query)

import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { init, traceContext } from "confident-trace";

init();

const llmApp = (query: string, userId: string) =>
    traceContext({ userId }, () =>
        generateText({ model: openai("gpt-4o"), prompt: query }),
    );

A trace context supplies defaults to traces started inside it. If the trace already has a user ID, the existing value wins. See Update Trace Properties for the full behavior.

Set User Fields

You can attach a display name to a user to make traces easier to identify in the observatory. Pass a user object to set the ID and name together:

with trace_context(user={"id": "user-42", "name": "Marta"}):
    return model.invoke(query)

return traceContext(
  { user: { id: "user-42", name: "Marta" } },
  () => model.invoke(query),
);

You can identify the user in either of two ways — use one form or the other:

• Pass user_id / userId when you only need the ID.
• Pass a user object when you also want to set a display name. The object contains id and can include name.

The same two options are available with turn(), a trace context, and the trace update helper. Python also accepts them when creating a span(); inside a TypeScript span() or withSpan() callback, call updateTrace().

View Users

Once your traces carry a user ID, open Users under Observe in the sidebar. The page shows every user that sent a trace in the selected window, so you can see who uses your app the most, what they cost, and who is having a bad experience.

Use the date picker, environment dropdown, and filters at the top to scope the whole page. The window defaults to the last three months.

User Overview

The top of the page summarizes your users for the selected window:

• Users — active and new users over time. Drag across the chart to zoom the page into that range.
• Most active users — users ranked by trace count, alongside their total cost. Click a row to open that user.
• Cost per user — the average cost of a user over the window.
• Sentiment — the share of negative sentiment over the window.
• Issues — the number of classified issues over the window.
• Retention — a cohort table. Each row is the users first seen in a period, and each column shows how many of them came back that many periods later. Switch between daily, weekly, and monthly cohorts.

Users Table

Below the overview, a table lists each user with their name, sentiment split, top issue, number of traces and threads, cost, first seen, and last activity. It is sorted by most recent activity by default.

Search by name or user ID, sort by any column except the name, and use the column editor to choose which columns appear.

User Details

Click a user to open their detail page. The cards at the top cover the same window as the page:

• Cost — total cost for this user, with cost over time.
• Last seen — the most recent trace, when the user was first seen, and a strip showing when in the window they were active.
• Sentiment — the breakdown of sentiment labels across this user's interactions.
• Issues and Use Cases — the labels this user hits most often.

Below the cards, the Traces and Threads tabs list everything this user did. If the user belongs to a customer, a pill next to the date picker links to that customer's page. Click the page title to rename the user without changing your code.

Next Steps

Last updated on September 30, 2026