> ## 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

> Learn how to set user properties in your traces

export const enrichmentType_2 = "User Properties"

export const paramName_1 = "user_properties"

export const enrichmentType_1 = "User Properties"

export const paramName_0 = "user_properties"

export const enrichmentType_0 = "User Properties"

## Introduction

HoneyHive allows you to set user properties in your traces to gain more insights into your application.

### Prerequisites

You have already set tracing for your code as [described in our quickstart guide](/introduction/quickstart).

## Setting {enrichmentType_0}

You can set {enrichmentType_0} on both the trace level or the span level. If the {enrichmentType_0} applies to the entire trace, then set it on the trace level. If the {enrichmentType_0} applies to a specific span, then set it on the span level. For more details, refer to the [enrich traces](/tracing/enrich-traces) documentation.

<Note>User Properties can only be set on the trace level.</Note>

<Tabs>
  <Tab title="Python">
    In Python, you can use the `enrich_session` function to set {enrichmentType_1} on the trace level.

    To pass {enrichmentType_1} to HoneyHive, pass it to the {paramName_0} param in the `enrich_session` function. This function is used to enrich the session with additional information. Remember that `enrich_session` will update, not overwrite, the existing {paramName_0} object on the trace.

    Read more about the `enrich_session` function in the [Python SDK reference](/sdk-reference/python-tracer-ref#enrich-session).

    Here's an example of how to set {enrichmentType_1} on the trace level in Python:

    ```python Python theme={null}
    from honeyhive import HoneyHiveTracer, enrich_session

    HoneyHiveTracer.init(
      api_key="my-api-key",
      project="my-project",
    )

    # ...

    enrich_session(user_properties={
      "user_id": "12345",
      "user_email": "user@example.com",
      "user_properties": {
        "is_premium": True,
        "subscription_plan": "pro",
        "last_login": "2024-01-01T12:00:00Z"
      }
    })
    ```
  </Tab>

  <Tab title="TypeScript">
    In TypeScript, you can use the `tracer.enrichSession` function to set {enrichmentType_2} on the trace level.

    To pass {enrichmentType_2} to HoneyHive, pass it to the {paramName_1} param in the `tracer.enrichSession` function. This function is used to enrich the session with additional information. Remember that `tracer.enrichSession` will update, not overwrite, the existing {paramName_1} object linked to the trace.

    Read more about the `tracer.enrichSession` function in the [TypeScript SDK reference](/sdk-reference/typescript-tracer-ref#enrichsession).

    Here's an example of how to set {enrichmentType_2} on the trace level in TypeScript:

    ```typescript TypeScript theme={null}
    import { HoneyHiveTracer, enrichSession } from "honeyhive";

    // Define types for user properties
    interface CustomUserProperties {
        is_premium: boolean;
        subscription_plan: string;
        last_login: string;
    }

    interface UserProperties {
        user_id: string;
        user_email: string;
        user_properties: CustomUserProperties;
    }

    // Initialize tracer 
    // Ensure HH_API_KEY and HH_PROJECT are set in your environment
    const tracer = await HoneyHiveTracer.init({
        sessionName: "setting-properties-session"
        // apiKey and project will be picked from environment variables
    });

    // Define the user properties object
    const userProps: UserProperties = {
        user_id: "12345",
        user_email: "user@example.com",
        user_properties: {
            is_premium: true,
            subscription_plan: "pro",
            last_login: "2024-01-01T12:00:00Z"
        }
    };

    // Wrap the execution logic in tracer.trace()
    // Note: Even if only enriching, trace() creates the session context
    await tracer.trace(async () => {
        // Enrich the session with user properties using standalone function
        enrichSession({
            userProperties: userProps // Note: property name is userProperties
        });
        
        console.log("Trace session enriched with user properties.");
    });

    // await tracer.flush(); // If the script exits immediately
    ```

    <Note title="Legacy Tracing Method (Deprecated)">
      Previously, enrichment involved calling methods directly on the `tracer` instance (e.g., `tracer.enrichSession()`). While this pattern still works, it is now deprecated and will be removed in a future major version.

      Please update your code to use the imported `enrichSession` function along with the `tracer.trace()` wrapper as shown in the example above. This new approach provides a consistent pattern with span-level tracing and enrichment.

      Example of the **deprecated** pattern:

      ```typescript theme={null}
      // OLD (DEPRECATED) PATTERN:
      // const tracer = await HoneyHiveTracer.init({...});
      // tracer.enrichSession({ userProperties: {...} }); 
      ```
    </Note>
  </Tab>
</Tabs>

## Concepts

### What are User Properties?

User properties are additional attributes that you can set on your traces to gain more insights into your application.

Examples include:

* User ID
* User email
* User properties
* User payment plan details
* User experiment group

User properties can help you link traces to specific users, improving your ability to group and filter traces using user-centric attributes.

## SDK Reference

Read more about the `enrich_session` function in the [Python SDK reference](/sdk-reference/python-tracer-ref#enrich-session).