> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Environment Variables
> Configure the HoneyHive Python SDK with environment variables for API keys, endpoints, tracer behavior, and sampling without hardcoding secrets in code.
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` | API key for authenticating with HoneyHive. Also accepts `HONEYHIVE_API_KEY`. | None (required) |
| `HH_PROJECT` | **Deprecated.** Project name. The backend now infers the project from the API key. Still accepted for backwards compatibility. Also accepts `HONEYHIVE_PROJECT`. | None |
| `HH_API_URL` | Base URL for the Data Plane API. Also accepts `HONEYHIVE_SERVER_URL` or `HH_SERVER_URL`. | `https://api.dp1.us.honeyhive.ai` |
| `HH_CP_API_URL` | Base URL for the Control Plane API. Falls back to `HH_API_URL` if not set. The client accepts this URL, but not every SDK surface routes through it yet. Only relevant for [self-hosted federated deployments](/v2/setup/self-hosted#sdk-configuration). | Same as `HH_API_URL` |
## 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](/v2/tracing/tracer-initialization#serverless). | `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` |
All `HH_*` variables also accept a `HONEYHIVE_*` prefix (e.g., `HONEYHIVE_API_KEY` instead of `HH_API_KEY`). The SDK resolves both prefixes automatically. Where an additional alias exists (e.g., `HONEYHIVE_SERVER_URL`), it is noted in the table above.