​
HoneyHiveTracer class

The HoneyHiveTracer class is a utility designed to initialize and manage a tracing session with the HoneyHive API, and utilize OpenTelemetry. This class encapsulates initialization of the tracing environment, capturing telemetry, and sending updates related to feedback, metrics, and metadata.

Our tracer uses OpenTelemetry as a base to auto-trace Python code. A full explanation of how this works in Python can be found here.

A general explanation of what OpenTelemetry is can be found here.

​
Attributes

The code for the tracer is open source and can be found here.

  • session_id (str or None): Stores the current session ID. This is None until a session is initialized.
  • api_key (str or None): Stores the API key used for authenticating with HoneyHive’s services.

​
Example Usage

from honeyhive import HoneyHiveTracer, enrich_session

# Initialize a session
HoneyHiveTracer.init(
    api_key="your-api-key",
    project="Project Name",
    session_name="Session Name",
    source="source_identifier"
)

# Set feedback, metrics, and metadata during the session
HoneyHiveTracer.enrich_session(feedback={'some_domain_expert': "Session feedback"})
HoneyHiveTracer.enrich_session(metrics={"metric_name": "metric_value"})
HoneyHiveTracer.enrich_session(metadata={"key": "value"})

# Set two or more of the following at once
HoneyHiveTracer.enrich_session(
    feedback={'some_domain_expert': "Session feedback"},
    metrics={"metric_name": "metric_value"},
    metadata={"key": "value"}
)

# (optional) Flush trace data before ending the session
# HoneyHiveTracer.flush()

​
Methods

​
init

Initializes a HoneyHive tracing session and sets up the tracing environment.

Parameters:

  • api_key (str): API key for authenticating with the HoneyHive service.
  • project (str): Name of the project associated with this tracing session.
  • session_name (str): Name for this specific session. Defaults to the name of the main module.
  • source (str): Source identifier, typically describing the environment or component that initiates the session. Defaults to dev.
  • server_url (str, optional): HoneyHive server URL (default: "https://api.honeyhive.ai").
  • disable_batch (bool, optional): Whether to disable batching of trace data (default: False).
  • verbose (bool, optional): Whether to print debug information to the console (default: False).

Usage Example:

HoneyHiveTracer.init(
    api_key="<YOUR_API_KEY>",
    project="Project Name",
    session_name="Session Name",
    source="source_identifier",
    disable_batch=True,
    verbose=True
)

Raises:
Exceptions are silently caught, meaning no errors will be raised if the initialization fails. It’s important to check if the session has been initialized. If verbose is set to True, then errors will be shown (but still silently caught).

​
init_from_session_id

Initializes a tracing session using an existing session ID.

Parameters:

  • api_key (str): API key for authenticating with HoneyHive services.
  • session_id (str): Pre-existing session ID to continue tracing.
  • server_url (str, optional): HoneyHive server URL (default: "https://api.honeyhive.ai").

Usage Example:

HoneyHiveTracer.init_from_session_id(
    api_key="<YOUR_API_KEY>",
    session_id="<YOUR_SESSION_ID>",
    disable_batch=True,
    verbose=True
)

Parameters:

  • api_key (str): API key for authenticating with HoneyHive services.
  • session_id (str): Pre-existing session ID to continue tracing.
  • server_url (str, optional): HoneyHive server URL (default: "https://api.honeyhive.ai").
  • disable_batch (bool, optional): Whether to disable batching of trace data (default: False).
  • verbose (bool, optional): Whether to print debug information to the console (default: False).

Raises:
Exceptions are silently caught.

​
enrich_session

Adds context to the session.

HoneyHiveTracer.enrich_session(feedback={"feedback_field1": "value1"})

Parameters: Can take any or all of the following parameters:

  • config (dict): Dictionary of configuration settings related to the function.
  • feedback (dict): Dictionary of feedback to be sent to HoneyHive.
  • metrics (dict): Dictionary of metrics to be sent to HoneyHive.
  • metadata (dict): Dictionary of metadata to be sent to HoneyHive.
  • outputs (dict): Dictionary of outputs to be sent to HoneyHive.
  • user_properties (dict): Dictionary of user properties to be sent to HoneyHive.

Raises:

  • Exception: If the HoneyHiveTracer is not initialized (i.e., session_id is None).

​
enrich_span

Adds context to the span. Can take any or all of the following parameters:

  • config (dict): Dictionary of configuration settings related to the function.
  • feedback (dict): Dictionary of feedback to be sent to HoneyHive.
  • metrics (dict): Dictionary of metrics to be sent to HoneyHive.
  • metadata (dict): Dictionary of metadata to be sent to HoneyHive.
  • inputs (dict): Dictionary of inputs to be sent to HoneyHive.
  • outputs (dict): Dictionary of outputs to be sent to HoneyHive.
  • error (string): String describing the error that occurred.

​
flush

Flushes all pending trace data.

Usage Example:

HoneyHiveTracer.flush()

​
@trace decorator

The @trace decorator is a utility provided by HoneyHive to easily add custom spans to your application. It captures function inputs, outputs, and additional metadata, providing deeper insights into your application’s behavior.

​
Usage

To use the @trace decorator, first initialize the HoneyHiveTracer:

from honeyhive import HoneyHiveTracer

HoneyHiveTracer.init(
    api_key="your-api-key",
    project="Project Name",
    source="source_identifier",
    session_name="Session Name"
)

Then, import and apply the trace decorator to any function you want to trace:

from honeyhive import trace

@trace(
    event_type="model",
    config={"important_setting": True},
    metadata={"version": "1.0.0"}
)
def my_function(param1, param2):
    # Function code here
    return result

​
Parameters

The trace decorator accepts the following parameters:

  • event_type (str, optional): Type of the event. Must be one of ‘tool’, ‘model’, or ‘chain’.
  • config (dict, optional): A dictionary of configuration settings related to the function.
  • metadata (dict, optional): A dictionary of additional metadata to be associated with the span.
  • event_type (str, optional): A string describing the type of event being traced. Must be one of: chain, tool, or llm.

​
Behavior

When applied to a function, the trace decorator:

  • Creates a new span with the function’s name.
  • Captures all function inputs (parameters) as span attributes.
  • Adds any provided config and metadata as span attributes.
  • Executes the function.
  • Captures the function’s return value as a span attribute.
  • Ends the span.
Manual InstrumentationTypeScript