# Identify users

Attach a user identity to your telemetry to unlock user-level analytics and insights.

User identification lets you track individual users across sessions, unlocking analytics like user journeys, retention, and per-user debugging.

## Why track users?

When you attach a user id to your telemetry, Brizz can:

- **Track user journeys** across multiple AI interactions
- **Identify power users** and understand their behavior patterns
- **Measure retention** and engagement over time
- **Spot issues** affecting specific user segments

## Identify a user

Call `set_user` / `setUser` inside a session. The identity applies to the turn's spans and propagates to the child spans created within the same context. Only `id` is required; every other field is optional.

:::tabs
:::tab[Python]

```python
from brizz import set_user, start_session

with start_session("session-123"):
    set_user(id=user.id, email=user.email, name=user.name, role=user.role, plan=user.plan)

    reply = agent.run(prompt)
```

:::tab[Node.js]

```typescript
import { startSession, setUser } from '@brizz/sdk';

await startSession('session-123', async () => {
  setUser({ id: user.id, email: user.email, name: user.name, role: user.role, plan: user.plan });

  return agent.run(prompt);
});
```

:::

Each field maps to its own dotted attribute — `brizz.user.id`, `brizz.user.email`, `brizz.user.name`, `brizz.user.role`, `brizz.user.plan`. The same setter is available on the session object (`session.set_user(...)` / `session.setUser(...)`).

## Extra attributes with traits

For anything beyond the named fields, pass a `traits` record. Each entry becomes `brizz.user.<key>`; named fields win on key collision.

:::tabs
:::tab[Python]

```python
set_user(id=user.id, traits={"department": "sales", "signup_source": "referral"})
```

:::tab[Node.js]

```typescript
setUser({ id: user.id, traits: { department: 'sales', signup_source: 'referral' } });
```

:::

## Scoped form

To apply identity to a single block and reset it on exit, use the scoped wrapper instead of the imperative setter.

:::tabs
:::tab[Python]

```python
from brizz import with_user

# Runs process_request with brizz.user.* on every span created inside it, then resets.
with_user("user-123", process_request, email="ada@example.com", name="Ada Lovelace")
```

:::tab[Node.js]

```typescript
import { callWithUser } from '@brizz/sdk';

await callWithUser({ id: 'user-123', email: 'ada@example.com', name: 'Ada Lovelace' }, processRequest);
```

:::

## Legacy: user properties on the session

You can also pass user properties when you start the session. This still works, but the typed `set_user` / `setUser` above is the recommended path.

:::tabs
:::tab[Python]

```python
from brizz import start_session

with start_session("session-123", {"user_id": "user-42", "user_name": "Ada Lovelace", "user_email": "ada@example.com"}):
    response = openai.chat.completions.create(...)
```

:::tab[Node.js]

```typescript
import { startSession } from '@brizz/sdk';

await startSession('session-123', async (session) => {
  session.updateProperties({ user_id: 'user-42', user_name: 'Ada Lovelace', user_email: 'ada@example.com' });

  const response = await openai.chat.completions.create({ ... });
});
```

:::

### Accepted property names (legacy)

These names are recognized as user identifiers **in the session-properties path above**:

| Property     | Variants                               |
| ------------ | -------------------------------------- |
| `user_id`    | `userId`, `UserID`, `USER_ID`          |
| `user_name`  | `userName`, `UserName`, `USER_NAME`    |
| `user_email` | `userEmail`, `UserEmail`, `USER_EMAIL` |
| `user`       | `User`                                 |

## Best practices

1. **Use consistent IDs** — always use the same user id format across sessions.
2. **Identify every session** — even anonymous users can carry a temporary id for session linking.

## See also

- [Identify organizations](/docs/instrument/identify-organizations.md) — attach the account or workspace the user belongs to.
- [Message IDs](/docs/instrument/message-ids.md) — tag individual replies so you can reference them later.
- [Sessions](/docs/instrument/sessions.md) — attach user properties to the session you're already creating.
- [User intents](/docs/platform/user-intents.md) and [User journeys](/docs/platform/user-journeys.md) — what becomes available once users are identified.