Schema Reference

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:

Namespace	Type	Description	`enrich_session`	`enrich_span`
`config`	Object	Configuration details (model params, prompt templates)	✓	✓
`feedback`	Object	User feedback or annotations	✓	✓
`metrics`	Object	Scores, evaluations, numeric measurements	✓	✓
`metadata`	Object	Catch-all for arbitrary metadata or JSON	✓	✓
`inputs`	Object	Input data for the function or event	✓	✓
`outputs`	Object	Output data from the function or event	✓	✓
`user_properties`	Object	User-specific attributes	✓	✓
`error`	String	Error information if applicable	✗	✓
`event_id`	String	Custom 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:

Namespace	Purpose	Backend Attribute
`metadata`	Custom business context	`honeyhive_metadata.*`
`metrics`	Numeric measurements	`honeyhive_metrics.*`
`user_properties`	User-specific properties	`honeyhive_user_properties.*`
`feedback`	User or system feedback	`honeyhive_feedback.*`
`inputs`	Input data	`honeyhive_inputs.*`
`outputs`	Output data	`honeyhive_outputs.*`
`config`	Configuration parameters	`honeyhive_config.*`
`error`	Error messages (string)	`honeyhive_error`
`event_id`	Unique 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:

Reserved namespaces (metadata, metrics, etc.) - Applied first
attributes dict (simple dict passed as first argument) - Applied second
**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

Python SDK Reference - enrich_session(), enrich_span()

Getting Started

Observability

Evaluation

Prompt Management

Administration

Learn More

Available Namespaces

Backend Attributes

Parameter Precedence

Supported Data Types

Nesting Limits

Best Practices

Task-Specific Guides

Metrics & Evaluations

User Feedback

Prompts

User Properties

Custom Metadata

SDK Reference

​Available Namespaces

​Backend Attributes

​Parameter Precedence

​Supported Data Types

​Nesting Limits

​Best Practices

​Task-Specific Guides

Metrics & Evaluations

User Feedback

Prompts

User Properties

Custom Metadata

​SDK Reference

Available Namespaces

Backend Attributes

Parameter Precedence

Supported Data Types

Nesting Limits

Best Practices

Task-Specific Guides

SDK Reference