Skip to main content
This page documents the enrichment schema - available namespaces, supported data types, and how they map to backend attributes. For how to use enrichment functions, see Enriching Traces.

​
Available Namespaces

Enrichments are key-value pairs that add context to your traces. Both enrich_span() and enrich_session() support these namespaces:
NamespaceTypeDescriptionenrich_sessionenrich_span
configObjectConfiguration details (model params, prompt templates)✓✓
feedbackObjectUser feedback or annotations✓✓
metricsObjectScores, evaluations, numeric measurements✓✓
metadataObjectCatch-all for arbitrary metadata or JSON✓✓
inputsObjectInput data for the function or event✓✓
outputsObjectOutput data from the function or event✓✓
user_propertiesObjectUser-specific attributes✓✓
errorStringError information if applicable✗✓
event_idStringCustom event ID (must be valid UUIDv4)✗✓
Setting event type: To set the event type (chain, model, tool), use the @trace decorator’s event_type parameter, not enrichment functions. Example: @trace(event_type="model").

​
Backend Attributes

Each namespace maps to a specific backend attribute prefix:
NamespacePurposeBackend Attribute
metadataCustom business contexthoneyhive_metadata.*
metricsNumeric measurementshoneyhive_metrics.*
user_propertiesUser-specific propertieshoneyhive_user_properties.*
feedbackUser or system feedbackhoneyhive_feedback.*
inputsInput datahoneyhive_inputs.*
outputsOutput datahoneyhive_outputs.*
configConfiguration parametershoneyhive_config.*
errorError messages (string)honeyhive_error
event_idUnique identifier (string)honeyhive_event_id
Additive behavior: For Object-type enrichments (config, metadata, etc.), enrichments are additive for unique keys. Enriching the same field twice with different keys includes both. Enriching the same key twice overwrites the previous value.

​
Parameter Precedence

When using enrich_span() with mixed invocation patterns (dict, kwargs, namespaces), parameters are merged in this order:
  1. Reserved namespaces (metadata, metrics, etc.) - Applied first
  2. attributes dict (simple dict passed as first argument) - Applied second
  3. **kwargs (keyword arguments) - Applied last, wins conflicts
# Example: mixing patterns
enrich_span(
    {"key": "from_dict"},        # attributes dict
    metadata={"key": "from_ns"}, # reserved namespace
    key="from_kwargs"            # kwargs
)
# Result: key="from_kwargs" (kwargs win)
Kwargs override dict values when the same key appears in both. Use explicit namespaces (metadata=, metrics=) for clarity.

​
Supported Data Types

You can enrich with these data types: 
from honeyhive import enrich_span

enrich_span({
    # Strings
    "user_id": "user_12345",
    "feature": "chat",
    
    # Numbers (integers and floats)
    "priority_score": 8.5,
    "retry_count": 3,
    
    # Booleans
    "is_premium_user": True,
    "cache_hit": False,
    
    # Lists (serialized to JSON)
    "tags": ["support", "billing", "urgent"],
    "model_fallback_order": ["gpt-4", "gpt-4o-mini"],
    
    # Nested dicts (serialized to JSON)
    "user_metadata": {
        "tier": "pro",
        "region": "us-east"
    }
})
Complex objects (lists, nested dicts) are automatically serialized to JSON strings for storage.

​
Nesting Limits

For complex data types:
  • Objects: Maximum 5 levels of nesting
  • Arrays: Maximum 2 levels of nesting
When querying nested data in the dashboard, use dot notation: 
{
  "step_evals": [
    { "invalid_grammar": true, "user_intervened": true },
    { "invalid_grammar": false }
  ],
  "trajectory_eval": {
    "overall": 5,
    "clarified_user_intent": "yes"
  }
}
You can chart:
  • metrics.step_evals.0.user_intervened (boolean)
  • metrics.trajectory_eval.overall (number)

​
Best Practices

DO:
  • Use consistent key names across your application
  • Add user/session IDs for debugging
  • Include feature/endpoint identifiers
  • Use descriptive key names (user_id not uid)
  • Keep values under 1KB per field
DON’T:
  • Include sensitive data (passwords, API keys, PII)
  • Use random or generated key names
  • Duplicate data already captured by auto-instrumentors
  • Exceed nesting limits (5 objects, 2 arrays)

​
Task-Specific Guides

Each namespace has a dedicated guide with detailed examples:

Metrics & Evaluations

The metrics namespace for scores and evaluations

User Feedback

The feedback namespace for ratings and comments

Prompts

Manage prompt templates and model configs

User Properties

The user_properties namespace for user context

Custom Metadata

The metadata namespace for arbitrary data

​
SDK Reference