How to Enrich Traces with Metadata and Metrics

Use enrich_span() and enrich_session() to attach user context, feature tags, evaluator scores, and config snapshots to HoneyHive traces so you can filter, debug, and evaluate production runs. Auto-instrumentation captures what your agent did; enrichments capture why it matters.

What types of enrichments can you add?

HoneyHive organizes custom attributes into typed namespaces. Each has a dedicated guide.

User Properties

Attach user IDs, account tiers, and other user context for per-user filtering and analysis.

User Feedback

Capture thumbs-up/down ratings, comments, and implicit signals directly on traces.

Custom Metrics

Log evaluation scores, guardrail results, and other numeric measurements computed in your app.

Config

Log prompt versions, model parameters, and other configuration context on traces.

Online Experiments

Tag traces with experiment IDs and variant names to analyze A/B tests in HoneyHive.

You can also attach arbitrary key-value pairs as metadata (e.g. feature flags, request IDs, environment tags). Any key that doesn’t belong to a typed namespace lands in metadata by default. For the full list of namespaces and data types, see the Schema Reference.

How do you enrich traces in code?

There are three functions, each scoped to a different level of your trace. Start from custom spans if you need to wrap business logic before enriching it.

enrich_session()
enrich_span()
using_attributes

Set attributes once and apply them to all traces in the session. Ideal for tenant context, app version, or user tier.

import os
from honeyhive import HoneyHiveTracer

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

tracer.enrich_session({
    "tenant_id": "acme_corp",
    "user_tier": "premium",
    "app_version": "2.1.0"
})

You can enrich a specific session by ID, which is useful in distributed systems:

tracer.enrich_session(
    session_id="sess_abc123",
    metadata={"completed": True}
)

Add attributes to the current active span. Use inside any @trace-decorated function for per-call context.

import os
from honeyhive import HoneyHiveTracer, enrich_span, trace

HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))

@trace
def process_query(query: str, user_id: str):
    enrich_span({
        "user_id": user_id,
        "query_length": len(query),
        "feature": "search"
    })
    # Your logic here...

Enrich auto-instrumented LLM spans (like OpenAI ChatCompletion) without wrapping them in @trace. Use the using_attributes context manager from OpenInference.

import os
from honeyhive import HoneyHiveTracer
from openinference.instrumentation import using_attributes
from openinference.instrumentation.openai import OpenAIInstrumentor
import openai

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

client = openai.OpenAI()

with using_attributes(
    user_id="user_12345",
    metadata={"feature": "chat_support"}
):
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello!"}]
    )

using_attributes attaches metadata directly to auto-instrumented spans. For your own functions, use @trace with enrich_span().

Should you use global or instance enrichment methods?

from honeyhive import HoneyHiveTracer, enrich_span

# Global function — works within any @trace context
enrich_span({"user_id": "user_123"})

# Instance method — recommended for production
tracer = HoneyHiveTracer.init(...)
tracer.enrich_span({"user_id": "user_123"})
tracer.enrich_session({"tenant_id": "acme"})

Use instance methods in production for an explicit tracer reference.

What invocation patterns does enrich_span support?

Both enrich_span() and enrich_session() accept data in several forms.

Simple dictionary

enrich_span({
    "user_id": "user_12345",
    "feature": "chat"
})

Keyword arguments

enrich_span(
    user_id="user_12345",
    feature="chat"
)

Explicit namespaces

Organize data by type using named parameters:

enrich_span(
    metadata={"user_id": "user_12345", "feature": "chat"},
    metrics={"latency_ms": 150, "score": 0.95},
    user_properties={"plan": "premium"},
    feedback={"rating": 5}
)

Mixed (namespaces + keywords)

Extra keyword arguments are added to metadata automatically:

enrich_span(
    metadata={"user_id": "user_12345"},
    metrics={"score": 0.95},
    feature="chat",      # → metadata.feature
    priority="high"      # → metadata.priority
)

What are common enrichment use cases?

User context

Attach user identity and message metadata to every traced call.

@trace
def generate_response(user_id: str, message: str):
    enrich_span(
        user_properties={"user_id": user_id},
        metadata={"message_length": len(message)}
    )
    # LLM call...

Feature tracking

Tag traces by feature to compare performance across different parts of your app.

@trace
def summarize_document(document: str, feature: str):
    enrich_span({
        "feature": feature,
        "document_length": len(document)
    })
    # LLM call...

Request metadata (Flask)

Capture HTTP request context for correlating traces with API traffic.

from flask import request

@app.route("/api/chat", methods=["POST"])
@trace
def chat_endpoint():
    enrich_span({
        "request_id": request.headers.get("X-Request-ID"),
        "endpoint": "/api/chat"
    })
    # Process request...

Business metrics

Log scores and experiment variants alongside your traces.

@trace
def generate_recommendation(product_id: str, user_id: str):
    enrich_span(
        user_properties={"user_id": user_id},
        metadata={"product_id": product_id, "ab_variant": "B"},
        metrics={"recommendation_score": 0.92}
    )
    # LLM call...

Performance monitoring

Record custom timing and throughput alongside auto-captured latency.

import time

@trace
def expensive_operation(data_size: int):
    start_time = time.perf_counter()

    result = process_data(data_size)

    duration_ms = (time.perf_counter() - start_time) * 1000
    enrich_span(metrics={
        "duration_ms": duration_ms,
        "data_size": data_size,
        "throughput": data_size / (duration_ms / 1000)
    })
    return result

Error context

Enrich spans with success/failure status and error details for debugging.

@trace
def risky_operation(operation_id: str, data: dict):
    enrich_span(metadata={"operation_id": operation_id})

    try:
        result = process(data)
        enrich_span(metadata={"success": True})
        return result
    except Exception as e:
        enrich_span(
            metadata={"success": False},
            error=str(e)
        )
        raise

How do session and span enrichment work together?

This example combines session-level and span-level enrichment in a single application.

Full example: session + span enrichment

import os
from honeyhive import HoneyHiveTracer, enrich_span, trace
from openinference.instrumentation.openai import OpenAIInstrumentor
import openai

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

# Session-level context (set once)
tracer.enrich_session({
    "tenant_id": "acme_corp",
    "user_tier": "premium",
    "app_version": "2.1.0"
})

client = openai.OpenAI()

# Span-level context (per call)
@trace
def chat(message: str, user_id: str):
    enrich_span({
        "user_id": user_id,
        "message_length": len(message),
        "feature": "chat_support"
    })

    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": message}]
    )
    return response.choices[0].message.content

# Each call inherits session context + gets its own span context
chat("Hello!", user_id="user_123")
chat("What's the weather?", user_id="user_456")

How do you view enriched data in the dashboard?

Open the Session view

Go to your project in the HoneyHive dashboard and select Traces.

Inspect a session

Click any session to expand it. Your enriched data appears in the Metadata and Attributes panels.

Filter and analyze

Use enriched fields to filter events, build custom charts, or set up alerts.

What are trace enrichment best practices?

Do	Don’t
Use consistent key names across your app	Include sensitive data (passwords, API keys, PII)
Add user/session IDs for debugging	Attach large values (>1KB per field)
Include feature and endpoint identifiers	Use random or generated key names
Use descriptive names (`user_id` not `uid`)	Duplicate data already captured by auto-instrumentation

Where is the SDK reference?

Python SDK

enrich_span() and enrich_session()

Getting Started

Observability

Evaluation

Prompt Management

Administration

Learn More

How to Enrich Traces with Metadata and Metrics

What types of enrichments can you add?

User Properties

User Feedback

Custom Metrics

Config

Online Experiments

How do you enrich traces in code?

Should you use global or instance enrichment methods?

What invocation patterns does enrich_span support?

What are common enrichment use cases?

How do session and span enrichment work together?

How do you view enriched data in the dashboard?

What are trace enrichment best practices?

Where is the SDK reference?

Python SDK

​What types of enrichments can you add?

User Properties

User Feedback

Custom Metrics

Config

Online Experiments

​How do you enrich traces in code?

​Should you use global or instance enrichment methods?

​What invocation patterns does enrich_span support?

​What are common enrichment use cases?

​How do session and span enrichment work together?

​How do you view enriched data in the dashboard?

​What are trace enrichment best practices?

​Where is the SDK reference?

Python SDK

What types of enrichments can you add?

How do you enrich traces in code?

Should you use global or instance enrichment methods?

What invocation patterns does enrich_span support?

What are common enrichment use cases?

How do session and span enrichment work together?

How do you view enriched data in the dashboard?

What are trace enrichment best practices?

Where is the SDK reference?