Enriching Traces
Overview
How to enrich your traces and spans with additional context
Prerequisites
Please complete the Quickstart and make sure you set up custom tracing using the@trace Python decorator or traceFunction JavaScript method. Here’s the guide for custom spans to set those up.
Session & Span Level Enrichments
Custom Spans allow you to trace any function in your code and see its inputs, outputs, errors, duration, etc. However, for certain use cases, you might want to add additional context into your trace such as feedback or metrics. We call this context injection enrichments. To log additional context to your rootsession, you can use
To log additional context to a specific child event span, you can use
These are useful if you want to add context within a traced function during runtime.
Enrichment Schema
Enrichments are key-value pairs that you can add to your traces to provide additional context. You can add the following enrichment attributes to your traces:| Attribute Key | Type | Description | enrich_session | enrich_span |
|---|---|---|---|---|
config | Object | Configuration details | ✓ | ✓ |
feedback | Object | User feedback or annotations | ✓ | ✓ |
metrics | Object | Metrics, scores, or evaluations | ✓ | ✓ |
metadata | Object | Catch-all for arbitrary metadata or JSON | ✓ | ✓ |
outputs | Object | Output data from the function or event | ✓ | ✓ |
user_properties | Object | User-specific attributes | ✓ | ✗ |
event_type | String | Type of event (chain, model, tool) | ✗ | ✓ |
inputs | Object | Input data for the function or event | ✗ | ✓ |
error | String | Error information if applicable | ✗ | ✓ |
Note: For the Object type enrichments (config, metadata, etc.), enrichments are always additive for unique keys. This means that enriching the same field twice with different keys will result in both keys being included in the trace. However, if you enrich the same field with the same key twice, the value will be overwritten.
Examples
Here are some ways in which you can enrich your traces:Metrics & Evaluations
Add metrics, scores, or evaluations to your traces
User Feedback
Enrich traces with feedback or additional annotations
Configuration Details
Include config details, model hyperparameters, or prompt templates
User Properties
Add user properties or tracking IDs to your traces
Custom Metadata
Enrich traces with arbitrary metadata or JSON