Skip to main content
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.
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}
)

​
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. 
enrich_span({
    "user_id": "user_12345",
    "feature": "chat"
})

enrich_span(
    user_id="user_12345",
    feature="chat"
)
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}
)
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?

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...
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...
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...
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...
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
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. 
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?

1

Open the Session view

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

Inspect a session

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

Filter and analyze

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

​
What are trace enrichment best practices?

DoDon’t
Use consistent key names across your appInclude sensitive data (passwords, API keys, PII)
Add user/session IDs for debuggingAttach large values (>1KB per field)
Include feature and endpoint identifiersUse 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()