> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# User Properties

> Add user context to your traces for user-centric filtering and analysis

This guide shows you how to add user properties (user ID, email, plan, etc.) to your traces.

## Quick Start

Use `enrich_session()` to add user context to the entire trace, or `enrich_span()` to add it to a specific operation.

### On the Session

Add user properties that apply to the entire user interaction:

```python theme={null}
from honeyhive import HoneyHiveTracer
import os

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)

# ... your application logic ...

# Add user context to the entire trace
tracer.enrich_session(user_properties={
    "user_id": "user_12345",
    "email": "user@example.com",
    "plan": "premium",
    "is_beta": True,
})
```

### On a Span

Add user properties to a specific function or operation:

```python theme={null}
from honeyhive import HoneyHiveTracer, trace
import os

tracer = HoneyHiveTracer.init(
    api_key=os.getenv("HH_API_KEY"),
    project=os.getenv("HH_PROJECT"),
)

@trace
def process_request(query: str, user_id: str):
    # ... your function logic ...
    
    # Add user context to this specific span
    tracer.enrich_span(user_properties={
        "user_id": user_id,
        "last_action": "search",
    })
    
    return response
```

***

## Concepts

### What are User Properties?

User properties are attributes that identify or describe the user making a request. They're stored in a dedicated `user_properties` namespace, displayed separately from other metadata in the dashboard.

Common user properties:

* **Identifiers**: user ID, email, account ID
* **Attributes**: subscription plan, role, region
* **Flags**: is\_beta, is\_internal, is\_premium

### User Properties vs Metadata

Both `user_properties` and `metadata` store key-value data. The difference is organizational:

| Namespace         | Use for                | Dashboard display                  |
| ----------------- | ---------------------- | ---------------------------------- |
| `user_properties` | User context (who)     | Separate "User Properties" section |
| `metadata`        | Request context (what) | "Metadata" section                 |

Use `user_properties` when the data describes the user. Use `metadata` for everything else (feature flags, request IDs, environment info).

### Data Types

| Type    | Example                            |
| ------- | ---------------------------------- |
| String  | `"user_id": "user_12345"`          |
| Number  | `"age": 25`                        |
| Boolean | `"is_premium": true`               |
| Object  | `"preferences": {"theme": "dark"}` |

***

## Learn More

<CardGroup cols={2}>
  <Card title="Enriching Traces" icon="sparkles" href="/v2/tracing/enrich-traces">
    Full guide to trace enrichment
  </Card>

  <Card title="Schema Reference" icon="book" href="/v2/tracing/enrichment-schema">
    All namespaces and data types
  </Card>
</CardGroup>

## SDK Reference

* [Python SDK Reference](https://honeyhiveai.github.io/python-sdk/) - `enrich_session()`, `enrich_span()`