HoneyHive Docs

Introduction

Metadata is a key-value pair that you can add to your traces to provide additional context.

It is provided as a catch-all for arbitrary information or JSON you might want to add to your traces.

The following steps will show you how to set metadata on the entire session.

Prerequisites

You have already set tracing for your code as described in our quickstart guide.

Setting

You can set on both the trace level or the span level. If the applies to the entire trace, then set it on the trace level. If the applies to a specific span, then set it on the span level. For more details, refer to the enrich traces documentation.

In Python, you can use the enrich_session function to set on the trace level.

To pass to HoneyHive, pass it to the 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 object on the trace.

Read more about the enrich_session function in the Python SDK reference.

Here’s an example of how to set on the trace level in Python:

Python

from honeyhive import HoneyHiveTracer, enrich_session

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

# ...

enrich_session(metadata={
  "experiment-id": 12345,
  # any other custom fields and values as you need
})

In Python, you can use the enrich_session function to set on the trace level.

Read more about the enrich_session function in the Python SDK reference.

Here’s an example of how to set on the trace level in Python:

Python

from honeyhive import HoneyHiveTracer, enrich_session

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

# ...

enrich_session(metadata={
  "experiment-id": 12345,
  # any other custom fields and values as you need
})

In Python, you can use the enrich_span function to set on the span level.

To pass to HoneyHive, pass it to the param in the enrich_span function. This function is used to enrich the span with additional information. Remember that enrich_span will update, not overwrite, the existing object linked to the span.

Read more about the enrich_span function in the Python SDK reference.

Here’s an example of how to set on the span level in Python:

Python

from honeyhive import HoneyHiveTracer, trace, enrich_span

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

# ...

@trace
def my_function(input, something):
  # ...

  enrich_span(metadata={
    "experiment-id": 12345,
    "something": something,
    # any other custom fields and values as you need
  })

  # ...

  return response

# ...

Alternatively, you can also enrich the field on the decorator in addition to using the enrich_span function.

You can find the complete documentation for this in the Python SDK reference.

In Python, you can use the enrich_session function to set on the trace level.

Read more about the enrich_session function in the Python SDK reference.

Here’s an example of how to set on the trace level in Python:

Python

from honeyhive import HoneyHiveTracer, enrich_session

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

# ...

enrich_session(metadata={
  "experiment-id": 12345,
  # any other custom fields and values as you need
})

In Python, you can use the enrich_session function to set on the trace level.

Read more about the enrich_session function in the Python SDK reference.

Here’s an example of how to set on the trace level in Python:

Python

from honeyhive import HoneyHiveTracer, enrich_session

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

# ...

enrich_session(metadata={
  "experiment-id": 12345,
  # any other custom fields and values as you need
})

In Python, you can use the enrich_span function to set on the span level.

Read more about the enrich_span function in the Python SDK reference.

Here’s an example of how to set on the span level in Python:

Python

from honeyhive import HoneyHiveTracer, trace, enrich_span

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

# ...

@trace
def my_function(input, something):
  # ...

  enrich_span(metadata={
    "experiment-id": 12345,
    "something": something,
    # any other custom fields and values as you need
  })

  # ...

  return response

# ...

Alternatively, you can also enrich the field on the decorator in addition to using the enrich_span function.

You can find the complete documentation for this in the Python SDK reference.

In TypeScript, you can use the tracer.enrichSession function to set on the trace level.

To pass to HoneyHive, pass it to the 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 object linked to the trace.

Read more about the tracer.enrichSession function in the TypeScript SDK reference.

Here’s an example of how to set on the trace level in TypeScript:

TypeScript

import { HoneyHiveTracer, enrichSession } from "honeyhive";

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

// Wrap the execution logic in tracer.trace()
await tracer.trace(async () => {
    // Add metadata to the entire trace session
    enrichSession({
      metadata: {
        "experiment-id": 12345,
        "user-group": "beta",
        // any other custom fields and values as you need
      }
    });

    // ... rest of your application logic ...
    console.log("Trace session enriched with metadata.");
});

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

In TypeScript, you can use the tracer.enrichSession function to set on the trace level.

Read more about the tracer.enrichSession function in the TypeScript SDK reference.

Here’s an example of how to set on the trace level in TypeScript:

TypeScript

import { HoneyHiveTracer, enrichSession } from "honeyhive";

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

// Wrap the execution logic in tracer.trace()
await tracer.trace(async () => {
    // Add metadata to the entire trace session
    enrichSession({
      metadata: {
        "experiment-id": 12345,
        "user-group": "beta",
        // any other custom fields and values as you need
      }
    });

    // ... rest of your application logic ...
    console.log("Trace session enriched with metadata.");
});

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

In TypeScript, you can use the tracer.enrichSpan function to set on the span level.

To pass to HoneyHive, pass it to the param in the tracer.enrichSpan function. This function is used to enrich the span with additional information. Remember that tracer.enrichSpan will update, not overwrite, the existing object linked to the span.

Read more about the tracer.enrichSpan function in the TypeScript SDK reference.

Here’s an example of how to set on the span level in TypeScript:

TypeScript

import { HoneyHiveTracer, traceTool, enrichSpan } from "honeyhive";

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

// Define the traced function using traceTool
const myTracedFunction = traceTool(
    function my_function ( // Function name is used as span name
        input: string,
        something: any
    ) {
        // Add metadata specific to this span
        enrichSpan({
            metadata: {
                "experiment-id": 12345,
                "something": something,
                // any other custom fields and values as you need
            }
        });

        // Your function code here (mock response)
        const response = `Processed input: ${input}`;
        return response;
    }
);

// --- Main Execution Logic ---
// Wrap the execution in tracer.trace() to establish context
await tracer.trace(async () => {
    const metadataValue = "some-metadata";
    // Execute the traced function within the trace context
    myTracedFunction("This is a mock input", metadataValue);
});

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

Alternatively, you can also enrich the field on the decorator in addition to using the enrichSpan function.

You can find the complete documentation for this in the TypeScript SDK reference.

Previously, tracing and enrichment involved calling methods directly on the tracer instance (e.g., tracer.traceFunction(), tracer.enrichSpan(), 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 functions (traceTool, enrichSpan, enrichSession) along with the tracer.trace() wrapper as shown in the examples above. This new approach simplifies usage within nested functions by not requiring the tracer instance to be passed around.

Example of the deprecated pattern:

// OLD (DEPRECATED) PATTERN:
// const tracer = await HoneyHiveTracer.init({...});
// tracer.enrichSession({ metadata: {...} }); 
// const myFunc = tracer.traceFunction()(function(...) { ... });
// tracer.enrichSpan({ metadata: {...} });

Concepts

What is Metadata?

Metadata is anything that doesn’t describe the quality of inputs / outputs or the system’s behavior. This metadata can be used to filter and group traces in HoneyHive.

Examples include

Online Experiment IDs
Offline Experiment IDs
Token Usage
Cost
System-level information

Reserved Fields

The following metadata fields are reserved and treated specially by HoneyHive:

Token Usage
- total_tokens: Total tokens used in the session/event
- completion_tokens: Completion tokens used in the session/event
- prompt_tokens: Prompt tokens used in the session/event
Cost
- cost: Cost of the session/event
Event Counts
- num_events: Number of events in the session
- num_model_events: Number of model events in the session
- has_feedback: Whether the session has feedback on any of the events
Evaluation Run ID
- run_id: Evaluation run ID used to group sessions for an evaluation run

Learn more

Grouping charts by metadata

Learn how to group charts by metadata in HoneyHive

SDK Reference

Read more about the enrich_session function in the Python SDK reference.

​Introduction

​Prerequisites

​Setting

​Concepts

​What is Metadata?

​Reserved Fields

​Learn more

Grouping charts by metadata

​SDK Reference

Introduction

Prerequisites

Setting

Concepts

What is Metadata?

Reserved Fields

Learn more

SDK Reference