Trace custom spans (Python)

While the HoneyHive tracer automatically instruments all of the most common LLM application components, you might sometimes want to trace parts of your code beyond the automated coverage.

HoneyHive provides a flexible trace decorator that allows you to easily add custom spans to your application. This decorator captures function inputs, outputs, and additional metadata, providing deeper insights into your application’s behavior.

​

Using the trace decorator

To use the trace decorator, you need to first instantiate the HoneyHiveTracer to begin tracing your session:

from honeyhive.tracer import HoneyHiveTracer
HoneyHiveTracer.init(
    api_key=MY_HONEYHIVE_API_KEY,
    project=MY_HONEYHIVE_PROJECT_NAME,
    source=MY_SOURCE, # e.g. "prod", "dev", etc.
    session_name=MY_SESSION_NAME,
)

Then you can add the trace decorator above any function you want to trace:

from honeyhive.tracer.custom import trace

@trace()
def my_function(param1, param2):
    # Code here

This will automatically create a span for the function, capturing its inputs and outputs.

​

Adding configuration and metadata

You can provide additional configuration and metadata to your traced functions:

@trace(
    config={"important_setting": True},
    metadata={"version": "1.0.0"}
)
def my_configured_function(param1, param2):
    # Your function code here
    return result

The config and metadata parameters allow you to add custom attributes to the span, which can be useful for filtering and analyzing your traces later.

​

How it works

The trace decorator performs the following actions:

1. Creates a new span with the function’s name
2. Captures all function inputs (parameters) as span attributes
3. Adds any provided config and metadata as span attributes
4. Executes the function
5. Captures the function’s return value as a span attribute
6. Ends the span

All captured data is automatically sent to your HoneyHive project, where you can view and analyze it alongside your other traces.

​

Best practices

• Use descriptive function names, as they will be used as span names in your traces
• Be mindful of sensitive data when tracing functions - avoid capturing passwords or other secrets
• Use the config parameter for settings that might affect the function’s behavior
• Use the metadata parameter for additional context that could be useful for analysis

By strategically adding the @trace() decorator to key functions in your application, you can gain valuable insights into your custom code’s performance and behavior, complementing HoneyHive’s automatic instrumentation of LLM components.