​
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

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

# 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.
  • source (str): Source identifier, typically describing the environment or component that initiates the session.
  • 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 log tracer errors to console (default: False). Usage Example:
HoneyHiveTracer.init(
    api_key="<YOUR_API_KEY>",
    project="Project Name",
    session_name="Session Name",
    source="source_identifier"
)

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>"
)

​
flush

Flushes all pending trace data.

Usage Example:

HoneyHiveTracer.flush()

​
enrich_session function

The enrich_session function is used to update the current session with additional information.

Parameters:

  • metadata (dict, optional): Additional metadata for the session.
  • feedback (dict, optional): Feedback data for the session.
  • metrics (dict, optional): Metrics data for the session.
  • config (dict, optional): Configuration data for the session.
  • inputs (dict, optional): Input data for the session (currently not supported).
  • outputs (dict, optional): Output data for the session.
  • user_properties (dict, optional): User properties for the session.

Usage Example:

enrich_session(
    metadata={"key": "value"},
    feedback={"rating": 5},
    metrics={"accuracy": 0.95},
    outputs={"result": "Success"}
)

Raises:

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

​
@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.tracer 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.tracer.custom 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.

​
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.

​
enrich_span function

The enrich_span function is used to add additional information to the current span within a traced function.

Parameters:

  • config (dict, optional): Configuration data for the span.
  • metadata (dict, optional): Additional metadata for the span.
  • metrics (dict, optional): Metrics data for the span.
  • feedback (dict, optional): Feedback data for the span.
  • inputs (dict, optional): Input data for the span.
  • outputs (dict, optional): Output data for the span.
  • error (str, optional): Error information for the span.

Usage Example:

@trace()
def my_function():
    # Function code here
    enrich_span(
        metadata={"key": "value"},
        metrics={"accuracy": 0.95},
        outputs={"result": "Success"}
    )
    # More function code

Note: The enrich_span function should only be used within a function decorated with @trace.

Manual InstrumentationTypeScript Tracer Reference