Reference documentation for the HoneyHiveTracer and @trace decorator
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.
str
or None
): Stores the current session ID of the instance. This is None
until a session is successfully initialized by the constructor.str
or None
, static): Class-level attribute storing the API key used for authentication. Set during the first initialization (HoneyHiveTracer(...)
or HoneyHiveTracer.init(...)
) or via the HH_API_KEY
environment variable. It is shared across all instances and tracer contexts.init
(Static Method)HoneyHiveTracer
and sets up the tracing environment.
Automatic Git Information: During initialization, if the code is run inside a Git repository and the git
command is available, the tracer will attempt to automatically capture information like the current commit hash, branch name, repository URL, and whether there are uncommitted changes. This information is added to the session’s initial metadata. This behavior can be disabled by setting the HONEYHIVE_TELEMETRY
environment variable to false
.
Parameters:
str
, optional): API key for authenticating with the HoneyHive service. If not provided, it checks the HH_API_KEY
environment variable.str
, optional): Name of the project associated with this tracing session. If not provided, it checks the HH_PROJECT
environment variable.str
, optional): Name for this specific session. Defaults to the name of the main Python script if possible, otherwise ‘unknown’.str
, optional): Source identifier, typically describing the environment or component that initiates the session. Defaults to the HH_SOURCE
environment variable or ‘dev’.str
, optional): HoneyHive server URL. Defaults to the HH_API_URL
environment variable or "https://api.honeyhive.ai"
.str
, optional): A specific session ID to use. If provided, the tracer attempts to resume or link to this existing session’s context (e.g., from a parent trace). If not provided, a new session ID is generated, or an existing one is potentially retrieved from the current context if automatically propagated.bool
, optional): When set to True
, spans for requests from common Python HTTP libraries (like requests
, urllib3
) will not be automatically traced (default: False
). This can also be controlled via context propagation.bool
, optional): Whether to disable batching of trace data (default: False
). Sending spans individually can increase network overhead.bool
, optional): Whether to print detailed debug information, including trace initialization details and potential errors, to the console (default: False
).Exception
and print an error message. Specific SDKError
types might be raised for configuration issues. If verbose
is False
, some non-critical errors might only be logged internally without raising an exception immediately, but essential failures like missing credentials will still halt execution.
enrich_session
(Module-Level Function)enrich_session
, which is the recommended way to enrich sessions.
tracer_instance.enrich_session(...)
available on HoneyHiveTracer
objects, but the module-level function is generally preferred as it can automatically determine the relevant session from the current context.str
, optional): The ID of the session to enrich. If not provided, the function attempts to retrieve the session_id
from the active tracing context (established during HoneyHiveTracer
initialization or context propagation).dict
, optional): Dictionary of configuration settings related to the session.dict
, optional): Dictionary of feedback data.dict
, optional): Dictionary of metrics data.dict
, optional): Dictionary of metadata.dict
, optional): Dictionary of session outputs.dict
, optional): Dictionary of user properties.inputs
parameter is currently not supported for enriching sessions via this function.
Raises:
session_id
is not provided and cannot be found in the current context.enrich_span
@trace
or @atrace
. If called outside of an active span managed by these decorators, it will have no effect and log a warning.
Adds context to the span. Can take any or all of the following parameters:
dict
): Dictionary of configuration settings related to the function.dict
): Dictionary of feedback to be sent to HoneyHive.dict
): Dictionary of metrics to be sent to HoneyHive.dict
): Dictionary of metadata to be sent to HoneyHive.dict
): Dictionary of inputs to be sent to HoneyHive.dict
): Dictionary of outputs to be sent to HoneyHive.string
): String describing the error that occurred.flush
@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.
@trace
decorator, first initialize the HoneyHiveTracer:
str
, optional): Type of the event. Must be one of ‘tool’, ‘model’, or ‘chain’.dict
, optional): A dictionary of configuration settings related to the function.dict
, optional): A dictionary of additional metadata to be associated with the span.str
, optional): A custom name for the span created for this trace. If not provided, it defaults to the name of the decorated function.@atrace
async def
), use the @atrace
decorator instead. It functions identically to @trace
but correctly handles async execution contexts.