Reference documentation for the HoneyHiveTracer class
HoneyHiveTracer
class is a utility designed to initialize and manage a tracing session with the HoneyHive API, utilizing 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 JavaScript code. A full explanation of how this works in JavaScript can be found here.
A general explanation of what OpenTelemetry is can be found here.
string | undefined
): Stores the current session ID. This is undefined
until a session is initialized.string | undefined
): API key used for authentication (read-only, sourced from initialization or HH_API_KEY
env var).string | undefined
): Project name associated with the session (read-only, sourced from initialization or HH_PROJECT
env var).string
): HoneyHive server URL (read-only, sourced from initialization, HH_API_URL
env var, or default).string
): Name for the current session (read-only, sourced from initialization, HH_SESSION_NAME
env var, main module filename, or default).string
): Source identifier for the session (read-only, sourced from initialization, HH_SOURCE
env var, package name, or default).Record<string, any>
): Default metadata associated with the session during initialization (read-only).boolean
): Whether batch exporting of traces is disabled (read-only, sourced from initialization).boolean
): Whether verbose logging is enabled (read-only, sourced from initialization).boolean
): Whether automatic HTTP tracing is disabled (read-only, sourced from initialization).init
Partial<HoneyHiveTracerProperties>
, optional): An object containing initialization options.
string
, required if HH_API_KEY
env var not set): API key for authenticating with the HoneyHive service.string
, required if HH_PROJECT
env var not set): Name of the project associated with this tracing session.string
, optional): Pre-existing session ID (must be a valid UUID) to continue tracing an existing session.string
, optional): Name for this specific session. Defaults will be inferred from the environment.string
, optional): Source identifier, typically describing the environment or component. Defaults will be inferred from the environment.string
, optional): HoneyHive server URL. Defaults to "https://api.honeyhive.ai"
, can also be set via HH_API_URL
env var.Record<string, any>
, optional): Default metadata to associate with the session.boolean
, optional): Enable verbose logging (default: false
).boolean
, optional): Disable batch exporting of traces (default: false
).boolean
, optional): Disable automatic tracing for HTTP requests (default: false
).Promise<HoneyHiveTracer>
: A promise that resolves to an instance of HoneyHiveTracer.
enrichSession
enrichSession
function instead for better context handling. enrichSession
function for parameters.Promise<void>
traceFunction
traceFunction
function instead for better context handling. traceFunction
function for parameters.traceModel
traceModel
function instead for better context handling. traceModel
function for parameters.traceTool
traceTool
function instead for better context handling. traceTool
function for parameters.traceChain
traceChain
function instead for better context handling. traceChain
function for parameters.trace
trace
will also return a Promise.
traceFunction
, traceModel
, traceTool
, or traceChain
decorators/wrappers often provides more structured tracing with automatic event type tagging. trace<A extends unknown[], F extends (...args: A) => ReturnType<F>>(fn: F, ...args: A): ReturnType<F>
Parameters:
F
): The function to execute and trace.A
): The arguments to pass to the function fn
.ReturnType<F>
: The result of executing fn(...args)
, preserving whether it’s a direct value or a Promise.
enrichSpan
enrichSpan
function instead. enrichSpan
function for parameters.void
flush
Promise<void>
enrichSpan
method should be called within a traced function to ensure there’s an active span to enrich.inputs
parameter in enrichSession
is currently not supported and will log a warning if used.HoneyHiveTracer
once using HoneyHiveTracer.init()
, the following exported functions are the preferred way to interact with tracing throughout your application. They automatically handle the necessary context association.
enrichSession
sessionId
from the current context if not provided.
Parameters:
EnrichSessionParams
, optional): An object containing data to enrich the session.
string
, optional): The ID of the session to enrich. If not provided, it attempts to get it from the active context.Record<string, any>
, optional): Additional metadata for the session.Record<string, any>
, optional): Feedback data for the session.Record<string, any>
, optional): Metrics data for the session.Record<string, any>
, optional): Configuration data for the session.Record<string, any>
, optional): Input data for the session (currently not supported).Record<string, any>
, optional): Output data for the session.Record<string, any>
, optional): User properties for the session.Promise<void>
enrichSpan
traceFunction
, traceModel
, etc.).
Parameters:
EnrichSpanParams
, optional): An object containing data to enrich the span.
any
, optional): Configuration data for the span.any
, optional): Additional metadata for the span.any
, optional): Metrics data for the span.any
, optional): Feedback data for the span.any
, optional): Input data for the span.any
, optional): Output data for the span.any
, optional): Error data for the span.string
, optional): A specific name to associate with this enrichment event within the span.void
traceFunction
TraceFunctionOptions
, optional): Configuration options for the trace.
string
, optional): Type of event (‘tool’, ‘model’, or ‘chain’). Sets the honeyhive_event_type
attribute.any
, optional): Configuration data to attach to the span (honeyhive_config
).any
, optional): Additional metadata to attach to the span (honeyhive_metadata
).string
, optional): Custom name for the trace span. Defaults to the function name or a generic event name.func
) as input and returns a new, traced version of func
.
Example Usage:
traceModel
traceFunction
that automatically sets the eventType
to “model”.
Parameters:
Function
): The model-related function to trace.Omit<TraceFunctionOptions, 'eventType'>
, optional): Configuration options (excluding eventType
).
any
, optional): Configuration data for the span.any
, optional): Additional metadata for the span.string
, optional): Custom name for the trace span.func
.
Example Usage:
traceTool
traceFunction
that automatically sets the eventType
to “tool”.
Parameters:
Function
): The tool-related function to trace.Omit<TraceFunctionOptions, 'eventType'>
, optional): Configuration options (excluding eventType
).
any
, optional): Configuration data for the span.any
, optional): Additional metadata for the span.string
, optional): Custom name for the trace span.func
.
Example Usage:
traceChain
traceFunction
that automatically sets the eventType
to “chain”. Typically used to wrap functions that orchestrate multiple model or tool calls.
Parameters:
Function
): The chain-related function to trace.Omit<TraceFunctionOptions, 'eventType'>
, optional): Configuration options (excluding eventType
).
any
, optional): Configuration data for the span.any
, optional): Additional metadata for the span.string
, optional): Custom name for the trace span.func
.
Example Usage:
enrichSession
and enrichSpan
functions should be used within the context of a traced function to ensure the correct session and span are enriched.traceFunction
, traceModel
, traceTool
, and traceChain
functions are designed to be used within the context of a traced function to ensure the correct event type is set.trace
function is a convenience function that can be used to trace any function, but it does not automatically associate the trace with the current session.