Skip to main content
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: 
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: 
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:
NamespaceUse forDashboard display
user_propertiesUser context (who)Separate “User Properties” section
metadataRequest 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

TypeExample
String"user_id": "user_12345"
Number"age": 25
Boolean"is_premium": true
Object"preferences": {"theme": "dark"}

​
Learn More

Enriching Traces

Full guide to trace enrichment

Schema Reference

All namespaces and data types

​
SDK Reference