Environment Variables

The Python SDK reads the following environment variables. All are optional when the equivalent parameter is passed directly to HoneyHiveTracer.init() or the HoneyHive client.

Authentication & Endpoints

Variable	Description	Default
`HH_API_KEY`	Classic project API key for operations that still require it, including creating and updating datasets, event reads, and experiment runs. Also used for ingestion when `HH_INGESTION_API_KEY` is unset. The deprecated `HONEYHIVE_API_KEY` is also read.	None
`HH_INGESTION_API_KEY`	Ingestion API key (`hh_ingst_`) for OTLP export, session start, and event writes. When unset, those calls use `HH_API_KEY`. Any value that is not an ingestion key raises at initialization.	None
`HH_DATA_PLANE_API_KEY`	Data plane fine-grained API key (`hh_fgdp_`) for supported project-scoped operations. Pass `project_id` to the call. The equivalent `HoneyHive()` parameter is `data_plane_api_key`. A wrong key type or incomplete value raises at initialization.	None
`HH_PROJECT`	Deprecated. Ignored project name. Ingestion and classic project keys identify their project; supported data plane fine-grained calls require `project_id` on the method.	None
`HH_API_URL`	Base URL for the Data Plane API. The deprecated `HONEYHIVE_SERVER_URL` and `HH_SERVER_URL` are also read.	`https://api.dp1.us.honeyhive.ai`

Credential selection is per operation. A tracing-only process can set just HH_INGESTION_API_KEY; a process that only calls supported project-scoped methods can set just HH_DATA_PLANE_API_KEY. The client raises before sending a call if its required key is absent. Data plane keys never fall back to HH_API_KEY and cannot send telemetry. See key selection by project ID.

Tracer Behavior

Variable	Description	Default
`HH_SOURCE`	Environment label for traces (e.g., `"prod"`, `"dev"`, `"staging"`).	`"dev"`
`HH_SESSION_NAME`	Default session name.	`""`
`HH_DISABLE_BATCH`	Disable batched span export. Set to `true` for serverless environments.	`false`
`HH_DISABLE_HTTP_TRACING`	Disable automatic HTTP request tracing. Also accepts `HONEYHIVE_DISABLE_HTTP_TRACING`.	`false`
`HH_TEST_MODE`	Disable OTLP export and use local-only session IDs. Useful for local development and tests.	`false`
`HH_VERBOSE`	Set to `"true"` to enable verbose debug logging.	`"false"`
`HH_OTLP_ENABLED`	Enable or disable OTLP span export.	`true`

Export & Performance

Variable	Description	Default
`HH_OTLP_PROTOCOL`	OTLP transport protocol (`"http/json"`, `"http/protobuf"`, or `"grpc"`). Also accepts `OTEL_EXPORTER_OTLP_PROTOCOL`.	`"http/json"`
`HH_BATCH_SIZE`	Maximum number of spans per export batch.	`100`
`HH_FLUSH_INTERVAL`	Interval in seconds between batch exports.	`5.0`
`HH_EXPORT_TIMEOUT`	Timeout in seconds for OTLP span exports.	`30`
`HH_EXPORT_TIMEOUT_SECONDS`	Timeout in seconds for large data exports via the REST API (e.g., `export()`, `get_by_session_id()`).	`120`
`HH_HIGH_CONCURRENCY`	Set to `"true"` to optimize for high-concurrency workloads.	`false`

Resource Attributes

Variable	Description	Default
`HH_SERVICE_NAME`	Override the OpenTelemetry `service.name` resource attribute.	Auto-detected
`HH_SERVICE_VERSION`	Override the OpenTelemetry `service.version` resource attribute.	Auto-detected

Span Limits

Variable	Description	Default
`HH_MAX_ATTRIBUTES`	Maximum number of attributes per span. Core HoneyHive attributes are preserved even when limits are reached.	`128`
`HH_MAX_EVENTS`	Maximum number of events per span.	`128`
`HH_MAX_LINKS`	Maximum number of links per span.	`128`

When to adjust span limits - The defaults work for most workloads. Consider raising them if your spans carry many attributes (e.g., deep RAG pipelines with dozens of retrieval chunks, or tool-calling agents with large parameter sets). When a limit is reached, new attributes beyond the limit are dropped. Core HoneyHive attributes like session_id and event_type are always preserved regardless of the limit.

Experiments

Variable	Description	Default
`HH_EXPERIMENT_ID`	Override the experiment ID.	-
`HH_EXPERIMENT_NAME`	Override the experiment name.	-
`HH_EXPERIMENT_VARIANT`	Tag the experiment variant.	-
`HH_EXPERIMENT_GROUP`	Tag the experiment group.	-

Proxy

Variable	Description	Default
`HH_HTTP_PROXY`	HTTP proxy URL for SDK requests. Falls back to standard `HTTP_PROXY`.	-
`HH_HTTPS_PROXY`	HTTPS proxy URL for SDK requests. Falls back to standard `HTTPS_PROXY`.	-
`HH_NO_PROXY`	Comma-separated list of hosts to bypass the proxy. Falls back to standard `NO_PROXY`.	-

Telemetry

Variable	Description	Default
`HH_TELEMETRY`	Enable or disable SDK telemetry. Also accepts `HONEYHIVE_TELEMETRY`.	`true`

A few HH_* variables also accept a HONEYHIVE_* name, and every alias a variable accepts is listed in its description above. Everything else is read under the HH_ prefix only. HH_INGESTION_API_KEY has no alias and is the only name the SDK reads for the ingestion key.

Deprecated aliases

These names are still read when the preferred name is unset, but each logs a deprecation warning once per process.

Deprecated	Replacement
`HONEYHIVE_API_KEY`	`HH_API_KEY`
`HONEYHIVE_SERVER_URL`	`HH_API_URL`
`HH_SERVER_URL`	`HH_API_URL`

Python SDK

TypeScript API SDK

TypeScript Control Plane SDK

Semantic Conventions

OpenAPI Client

Authentication & Endpoints

Tracer Behavior

Export & Performance

Resource Attributes

Span Limits

Experiments

Proxy

Telemetry

Deprecated aliases

​Authentication & Endpoints

​Tracer Behavior

​Export & Performance

​Resource Attributes

​Span Limits

​Experiments

​Proxy

​Telemetry

​Deprecated aliases

Authentication & Endpoints

Tracer Behavior

Export & Performance

Resource Attributes

Span Limits

Experiments

Proxy

Telemetry

Deprecated aliases