Reference documentation for the HoneyHive Logger SDK functions: start
, log
, and update
.
honeyhive_logger
provides a lightweight, dependency-free way to send session and event data to HoneyHive. It directly wraps HoneyHive’s /session/start
and /events
API endpoints.
This SDK has no external dependencies beyond built-in Python packages, making it ideal for:
start()
str
, optional): Your HoneyHive API key. If not provided, the logger checks the HH_API_KEY
environment variable. Required either as an argument or environment variable.str
, optional): The name of your project in HoneyHive. If not provided, the logger checks the HH_PROJECT
environment variable. Required either as an argument or environment variable.str
, optional): An optional name or tag for the session (e.g., “v1.2”, “user_chat_abc”, commit hash). Helps in filtering sessions later. Defaults to the project
name if not provided.str
, optional): Identifier for the environment or component where the session originates (e.g., “production”, “staging”, “sdk_test”). Defaults to the HH_SOURCE
environment variable or “dev”.dict
, optional): Dictionary containing configuration details relevant to the entire session (e.g., system prompts, global settings). Defaults to {}
.dict
, optional): Dictionary containing initial input parameters for the session. Defaults to {}
.dict
, optional): Dictionary for additional arbitrary metadata associated with the session. Defaults to {}
.dict
, optional): Dictionary for user-defined properties associated with the session. Defaults to {}
.str
, optional): A specific UUIDv4 string to use as the session ID. Useful for correlating with external logs or resuming sessions. If not provided, a new UUIDv4 is generated automatically.str
, optional): The URL of the HoneyHive API server. Defaults to the HH_API_URL
environment variable or "https://api.honeyhive.ai"
.bool
, optional): If True
, prints detailed debug information, including request data and error messages, to the console. Defaults to False
.str
, optional): Path to a custom Certificate Authority (CA) bundle file for SSL verification. If None
, uses the system’s default CA store. See SSL Certificate Handling. Defaults to None
.str
: The unique session ID (UUIDv4 format) for the created session. This ID is needed to log events within this session or to update the session later.Exception
: If api_key
or project
is missing (and not set via environment variables).Exception
: If the API call fails after retries (e.g., network error, invalid API key, server error). More details are printed if verbose=True
.log()
str
, optional): Your HoneyHive API key. Defaults to HH_API_KEY
env var. Required.str
, optional): Your project name. Defaults to HH_PROJECT
env var. Required.str
, optional): Environment identifier. Defaults to HH_SOURCE
env var or “dev”.str
): A descriptive name for the event being logged (e.g., “generate_summary”, “vector_db_lookup”). Required.str
, optional): The type of the event. Must be one of "model"
, "tool"
, or "chain"
(case-insensitive). Defaults to "tool"
.dict
, optional): Configuration details specific to this event (e.g., model parameters like temperature, tool parameters). Defaults to {}
.dict
, optional): Input parameters for this specific event (e.g., prompt for a model, query for a tool). Defaults to {}
.dict
, optional): Output data generated by this event (e.g., model response, tool result). Defaults to {}
.dict
, optional): Additional arbitrary metadata for this event. Defaults to {}
.str
): The ID of the session this event belongs to (obtained from start()
). Required.int
, optional): The duration of the event execution in milliseconds. If not provided, defaults to 10
.str
, optional): HoneyHive API server URL. Defaults to HH_API_URL
env var or "https://api.honeyhive.ai"
.bool
, optional): Enable detailed debug logging. Defaults to False
.str
, optional): Path to a custom CA bundle file. Defaults to None
.str
: The unique event ID (UUIDv4 format) for the logged event. This ID can be used with update()
to add feedback or metrics later.Exception
: If api_key
, project
, event_name
, or session_id
is missing.Exception
: If event_type
is not one of the valid types (“model”, “tool”, “chain”).Exception
: If the API call fails after retries. More details if verbose=True
.update()
str
, optional): Your HoneyHive API key. Defaults to HH_API_KEY
env var. Required.str
): The ID of the item to update. This must be either:
session_id
returned from start()
to update the session.event_id
returned from log()
to update a specific event.
Required.dict
, optional): Dictionary of metadata to add or update. Existing keys will be overwritten.dict
, optional): Dictionary containing user feedback (e.g., ratings, corrections, comments).dict
, optional): Dictionary containing computed metrics (e.g., latency, token counts, evaluation scores).dict
, optional): Dictionary of configuration settings to add or update.dict
, optional): Dictionary of output data to add or update.dict
, optional): Dictionary of user properties to add or update (typically used when updating a session).int
, optional): Update the duration of the event in milliseconds.str
, optional): HoneyHive API server URL. Defaults to HH_API_URL
env var or "https://api.honeyhive.ai"
.bool
, optional): Enable detailed debug logging. Defaults to False
.str
, optional): Path to a custom CA bundle file. Defaults to None
.None
Exception
: If api_key
or event_id
is missing.Exception
: If event_id
is not a valid UUID.Exception
: If the API call fails after retries. More details if verbose=True
.verbose
set to True, all errors are swallowed.
If true, the logger will raise exceptions for:
ca_bundle_path
parameter available in start()
, log()
, and update()
:
urllib
library to use your specified file for verifying the server’s certificate.
brew install ca-certificates
sudo apt-get install ca-certificates
sudo yum install ca-certificates
REQUESTS_CA_BUNDLE
or CURL_CA_BUNDLE
environment variable: