Environment Variables Reference

Note

Complete reference for HoneyHive SDK environment variables

Configure the SDK behavior through environment variables for different deployment scenarios.

The HoneyHive SDK supports comprehensive configuration through environment variables, allowing for flexible deployment across different environments without code changes.

Note

Runtime Configuration Support (v0.1.0rc2+)

Environment variables are now properly picked up when set at runtime, after SDK import. This enables dynamic configuration changes without restarting the application.

Core Configuration Variables

Authentication

Variable	Default	Description
`HH_API_KEY`	Required	HoneyHive API key for authentication. Format: `hh_...`
`HH_API_SECRET`	Optional	Additional API secret for enhanced security (enterprise only)

Examples:

# Basic authentication
export HH_API_KEY="hh_1234567890abcdef"

# Enterprise authentication with secret
export HH_API_KEY="hh_enterprise_key"
export HH_API_SECRET="secret_key_for_enhanced_security"

Project Configuration

Variable	Default	Description
`HH_PROJECT`	Required	Project name for HoneyHive operations. Must match your HoneyHive project.
`HH_SOURCE`	`"unknown"`	Source environment identifier (e.g., production, staging)
`HH_SESSION_NAME`	Auto-generated	Default session name for trace grouping

Examples:

# Production configuration
export HH_SOURCE="production"
export HH_SESSION_NAME="prod-session-$(date +%Y%m%d)"

# Development configuration
export HH_SOURCE="development"
export HH_SESSION_NAME="dev-local"

Network Configuration

Variable	Default	Description
`HH_BASE_URL`	`"https://api.honeyhive.ai"`	HoneyHive API endpoint URL
`HH_SERVER_URL`	None	Alias for `HH_BASE_URL` (for backward compatibility)
`HH_TIMEOUT`	`30.0`	Request timeout in seconds
`HH_MAX_RETRIES`	`3`	Maximum number of retry attempts for failed requests

Examples:

# Custom deployment
export HH_BASE_URL="https://honeyhive.mycompany.com"
export HH_TIMEOUT="60.0"
export HH_MAX_RETRIES="5"

# Development with local server
export HH_BASE_URL="http://localhost:8080"
export HH_TIMEOUT="10.0"

Testing and Development

Variable	Default	Description
`HH_TEST_MODE`	`false`	Enable test mode (no data sent to HoneyHive)
`HH_DEBUG`	`false`	Enable debug logging and verbose output
`HH_LOG_LEVEL`	`"INFO"`	Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)

Examples:

# Test environment
export HH_TEST_MODE="true"
export HH_DEBUG="true"
export HH_LOG_LEVEL="DEBUG"

# Production environment
export HH_TEST_MODE="false"
export HH_DEBUG="false"
export HH_LOG_LEVEL="WARNING"

Performance Configuration

Batching and Buffering

Variable	Default	Description
`HH_BATCH_SIZE`	`100`	Number of spans to batch before sending
`HH_FLUSH_INTERVAL`	`5.0`	Automatic flush interval in seconds
`HH_MAX_QUEUE_SIZE`	`1000`	Maximum number of spans in memory queue

Examples:

# High-throughput configuration
export HH_BATCH_SIZE="500"
export HH_FLUSH_INTERVAL="10.0"
export HH_MAX_QUEUE_SIZE="5000"

# Low-latency configuration
export HH_BATCH_SIZE="10"
export HH_FLUSH_INTERVAL="1.0"
export HH_MAX_QUEUE_SIZE="100"

Connection Pooling

Variable	Default	Description
`HH_MAX_CONNECTIONS`	`50`	Maximum concurrent HTTP connections
`HH_MAX_KEEPALIVE_CONNECTIONS`	`10`	Maximum persistent connections
`HH_KEEPALIVE_EXPIRY`	`30.0`	Connection keepalive timeout in seconds

Examples:

# High-concurrency configuration
export HH_MAX_CONNECTIONS="200"
export HH_MAX_KEEPALIVE_CONNECTIONS="50"
export HH_KEEPALIVE_EXPIRY="60.0"

Tracing Configuration

Instrumentation Control

Variable	Default	Description
`HH_DISABLE_HTTP_TRACING`	`true`	Disable automatic HTTP request tracing
`HH_CAPTURE_INPUTS`	`true`	Default setting for capturing function inputs
`HH_CAPTURE_OUTPUTS`	`true`	Default setting for capturing function outputs
`HH_CAPTURE_EXCEPTIONS`	`true`	Whether to capture exception details in traces

Backwards Compatibility Configuration

Variable	Default	Description
`HONEYHIVE_TELEMETRY`	`true`	Enable/disable git metadata collection for sessions
`HH_VERBOSE`	`false`	Enable verbose debug logging throughout tracer initialization
`HH_DISABLE_BATCH`	`false`	Use SimpleSpanProcessor instead of BatchSpanProcessor for immediate export

Examples:

# Security-conscious configuration
export HH_CAPTURE_INPUTS="false"
export HH_CAPTURE_OUTPUTS="false"
export HH_CAPTURE_EXCEPTIONS="true"

# Full observability configuration
export HH_CAPTURE_INPUTS="true"
export HH_CAPTURE_OUTPUTS="true"
export HH_CAPTURE_EXCEPTIONS="true"
export HH_DISABLE_HTTP_TRACING="false"

# Backwards compatibility configuration
export HONEYHIVE_TELEMETRY="false"  # Disable git metadata collection
export HH_VERBOSE="true"             # Enable debug logging
export HH_DISABLE_BATCH="true"       # Use immediate export for debugging

Sampling Configuration

Variable	Default	Description
`HH_SAMPLING_RATE`	`1.0`	Global sampling rate (0.0 to 1.0)
`HH_ERROR_SAMPLING_RATE`	`1.0`	Sampling rate for error traces
`HH_SLOW_THRESHOLD`	`1000.0`	Threshold in milliseconds for slow trace sampling

Examples:

# Production sampling (10% of normal traces, all errors)
export HH_SAMPLING_RATE="0.1"
export HH_ERROR_SAMPLING_RATE="1.0"
export HH_SLOW_THRESHOLD="500.0"

# Development (all traces)
export HH_SAMPLING_RATE="1.0"
export HH_ERROR_SAMPLING_RATE="1.0"

Security Configuration

SSL/TLS Settings

Variable	Default	Description
`HH_VERIFY_SSL`	`true`	Verify SSL certificates for HTTPS requests
`HH_SSL_CERT_PATH`	None	Path to custom SSL certificate file
`HH_SSL_KEY_PATH`	None	Path to SSL private key file (client certificates)

Examples:

# Enterprise SSL configuration
export HH_VERIFY_SSL="true"
export HH_SSL_CERT_PATH="/etc/ssl/certs/honeyhive.pem"
export HH_SSL_KEY_PATH="/etc/ssl/private/honeyhive.key"

# Development with self-signed certificates
export HH_VERIFY_SSL="false"

Proxy Configuration

Variable	Default	Description
`HH_PROXY_URL`	None	HTTP/HTTPS proxy URL
`HH_PROXY_USERNAME`	None	Proxy authentication username
`HH_PROXY_PASSWORD`	None	Proxy authentication password

Examples:

# Corporate proxy
export HH_PROXY_URL="http://proxy.company.com:8080"
export HH_PROXY_USERNAME="proxy_user"
export HH_PROXY_PASSWORD="proxy_password"

Data Privacy

Variable	Default	Description
`HH_SANITIZE_INPUTS`	`false`	Automatically sanitize sensitive data in inputs
`HH_SANITIZE_OUTPUTS`	`false`	Automatically sanitize sensitive data in outputs
`HH_PII_PATTERNS`	Default patterns	Custom regex patterns for PII detection

Examples:

# Privacy-focused configuration
export HH_SANITIZE_INPUTS="true"
export HH_SANITIZE_OUTPUTS="true"
export HH_PII_PATTERNS="email,phone,ssn,credit_card"

Evaluation Configuration

Evaluator Settings

Variable	Default	Description
`HH_ENABLE_EVALUATION`	`true`	Enable automatic evaluation
`HH_EVALUATION_TIMEOUT`	`30.0`	Timeout for evaluation requests in seconds
`HH_EVALUATION_RETRIES`	`2`	Number of retries for failed evaluations

Examples:

# Evaluation configuration
export HH_ENABLE_EVALUATION="true"
export HH_EVALUATION_TIMEOUT="60.0"
export HH_EVALUATION_RETRIES="3"

Provider-Specific Variables

OpenAI Configuration

Variable	Default	Description
`OPENAI_API_KEY`	None	OpenAI API key (used by OpenAI instrumentor)
`OPENAI_BASE_URL`	OpenAI default	Custom OpenAI API endpoint
`OPENAI_ORGANIZATION`	None	OpenAI organization ID

Examples:

# OpenAI configuration
export OPENAI_API_KEY="sk-..."
export OPENAI_ORGANIZATION="org-..."

Anthropic Configuration

Variable	Default	Description
`ANTHROPIC_API_KEY`	None	Anthropic API key (used by Anthropic instrumentor)
`ANTHROPIC_BASE_URL`	Anthropic default	Custom Anthropic API endpoint

Examples:

# Anthropic configuration
export ANTHROPIC_API_KEY="sk-ant-..."

Environment-Specific Configurations

Development Environment

# .env.development
HH_API_KEY="hh_dev_key_here"
HH_SOURCE="development"
HH_TEST_MODE="false"
HH_DEBUG="true"
HH_LOG_LEVEL="DEBUG"
HH_SAMPLING_RATE="1.0"
HH_BATCH_SIZE="10"
HH_FLUSH_INTERVAL="1.0"
HH_CAPTURE_INPUTS="true"
HH_CAPTURE_OUTPUTS="true"

Staging Environment

# .env.staging
HH_API_KEY="hh_staging_key_here"
HH_SOURCE="staging"
HH_TEST_MODE="false"
HH_DEBUG="false"
HH_LOG_LEVEL="INFO"
HH_SAMPLING_RATE="0.5"
HH_BATCH_SIZE="50"
HH_FLUSH_INTERVAL="3.0"
HH_TIMEOUT="45.0"

Production Environment

# .env.production
HH_API_KEY="hh_prod_key_here"
HH_SOURCE="production"
HH_TEST_MODE="false"
HH_DEBUG="false"
HH_LOG_LEVEL="WARNING"
HH_SAMPLING_RATE="0.1"
HH_ERROR_SAMPLING_RATE="1.0"
HH_BATCH_SIZE="200"
HH_FLUSH_INTERVAL="10.0"
HH_MAX_CONNECTIONS="100"
HH_TIMEOUT="60.0"
HH_SANITIZE_INPUTS="true"
HH_VERIFY_SSL="true"

Container Deployment

Docker Configuration

# Dockerfile
FROM python:3.11-slim

# Install application
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . /app
WORKDIR /app

# Environment variables with defaults
ENV HH_SOURCE="container"
ENV HH_BATCH_SIZE="100"
ENV HH_FLUSH_INTERVAL="5.0"
ENV HH_LOG_LEVEL="INFO"

CMD ["python", "app.py"]

Docker Compose:

# docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    environment:
      - HH_API_KEY=${HH_API_KEY}
      - HH_SOURCE=docker-compose
      - HH_DEBUG=false
      - HH_BATCH_SIZE=150
      - HH_TIMEOUT=45.0
    env_file:
      - .env.production

Kubernetes Configuration

# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: honeyhive-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: honeyhive-app
  template:
    metadata:
      labels:
        app: honeyhive-app
    spec:
      containers:
      - name: app
        image: myapp:latest
        env:
        - name: HH_API_KEY
          valueFrom:
            secretKeyRef:
              name: honeyhive-secret
              key: api-key
        - name: HH_PROJECT
          value: "k8s-production-app"
        - name: HH_SOURCE
          value: "kubernetes"
        - name: HH_BATCH_SIZE
          value: "200"
        - name: HH_MAX_CONNECTIONS
          value: "100"
        - name: HH_LOG_LEVEL
          value: "INFO"

apiVersion: v1
kind: Secret
metadata:
  name: honeyhive-secret
type: Opaque
data:
  api-key: <base64-encoded-api-key>

Configuration Validation

Environment Variable Validation

import os
from honeyhive.utils import validate_configuration

def validate_honeyhive_config():
    """Validate HoneyHive environment configuration."""

    # Required variables
    required_vars = ['HH_API_KEY']
    missing_vars = [var for var in required_vars if not os.getenv(var)]

    if missing_vars:
        raise ValueError(f"Missing required environment variables: {missing_vars}")

    # Validate API key format
    api_key = os.getenv('HH_API_KEY')
    if not api_key.startswith('hh_'):
        raise ValueError("HH_API_KEY must start with 'hh_'")

    # Validate numeric values
    numeric_vars = {
        'HH_TIMEOUT': (1.0, 300.0),
        'HH_BATCH_SIZE': (1, 10000),
        'HH_SAMPLING_RATE': (0.0, 1.0)
    }

    for var, (min_val, max_val) in numeric_vars.items():
        if value_str := os.getenv(var):
            try:
                value = float(value_str)
                if not min_val <= value <= max_val:
                    raise ValueError(f"{var} must be between {min_val} and {max_val}")
            except ValueError:
                raise ValueError(f"{var} must be a valid number")

    # Validate boolean values
    boolean_vars = ['HH_TEST_MODE', 'HH_DEBUG', 'HH_VERIFY_SSL']
    for var in boolean_vars:
        if value_str := os.getenv(var):
            if value_str.lower() not in ['true', 'false']:
                raise ValueError(f"{var} must be 'true' or 'false'")

    print("✓ HoneyHive configuration is valid")

Configuration Loading Patterns

Hierarchical Configuration

import os
from typing import Dict, Any

class HoneyHiveConfig:
    """Hierarchical configuration with environment override."""

    def __init__(self, config_file: str = None, env_prefix: str = "HH_"):
        self.env_prefix = env_prefix
        self.config = self._load_base_config()

        if config_file:
            self.config.update(self._load_file_config(config_file))

        self.config.update(self._load_env_config())

    def _load_base_config(self) -> Dict[str, Any]:
        """Load default configuration."""
        return {
            'api_key': None,
            'project': 'default',
            'source': 'unknown',
            'test_mode': False,
            'debug': False,
            'timeout': 30.0,
            'batch_size': 100,
            'sampling_rate': 1.0
        }

    def _load_file_config(self, config_file: str) -> Dict[str, Any]:
        """Load configuration from file."""
        import json
        with open(config_file) as f:
            return json.load(f)

    def _load_env_config(self) -> Dict[str, Any]:
        """Load configuration from environment variables."""
        config = {}

        env_mapping = {
            'HH_API_KEY': 'api_key',
            'HH_PROJECT': 'project',
            'HH_SOURCE': 'source',
            'HH_TEST_MODE': 'test_mode',
            'HH_DEBUG': 'debug',
            'HH_TIMEOUT': 'timeout',
            'HH_BATCH_SIZE': 'batch_size',
            'HH_SAMPLING_RATE': 'sampling_rate'
        }

        for env_var, config_key in env_mapping.items():
            if value := os.getenv(env_var):
                # Type conversion
                if config_key in ['test_mode', 'debug']:
                    config[config_key] = value.lower() == 'true'
                elif config_key in ['timeout', 'sampling_rate']:
                    config[config_key] = float(value)
                elif config_key in ['batch_size']:
                    config[config_key] = int(value)
                else:
                    config[config_key] = value

        return config

    def get(self, key: str, default=None):
        """Get configuration value."""
        return self.config.get(key, default)

    def __getitem__(self, key: str):
        """Dictionary-style access."""
        return self.config[key]

Configuration Factory

from honeyhive import HoneyHiveTracer

class ConfigurationFactory:
    """Factory for creating configured HoneyHive instances."""

    @staticmethod
    def create_from_environment() -> HoneyHiveTracer:
        """Create tracer from environment variables."""
        return HoneyHiveTracer.init(
            project=os.getenv('HH_PROJECT', 'default-project')  # Or set HH_PROJECT environment variable
        )

    @staticmethod
    def create_for_testing() -> HoneyHiveTracer:
        """Create tracer configured for testing."""
        return HoneyHiveTracer.init(
            api_key=os.getenv('HH_API_KEY', 'test_key'),  # Or set HH_API_KEY environment variable
            project=os.getenv('HH_PROJECT', 'test-project'),  # Or set HH_PROJECT environment variable
            source='test',                                 # Or set HH_SOURCE environment variable
            test_mode=True                                 # Or set HH_TEST_MODE=true environment variable
        )

    @staticmethod
    def create_for_production() -> HoneyHiveTracer:
        """Create production-optimized tracer."""
        return HoneyHiveTracer.init(
            api_key=os.getenv('HH_API_KEY'),              # Or set HH_API_KEY environment variable
            project=os.getenv('HH_PROJECT', 'production-project'),  # Or set HH_PROJECT environment variable
            source='production'                           # Or set HH_SOURCE environment variable
        )

Troubleshooting Configuration

Common Issues

Issue: API Key Not Found

# Error: HoneyHive API key not found
# Solution: Set the environment variable
export HH_API_KEY="your_api_key_here"

Issue: Connection Timeout

# Error: Request timeout
# Solution: Increase timeout or check network
export HH_TIMEOUT="60.0"
export HH_MAX_RETRIES="5"

Issue: High Memory Usage

# Solution: Reduce batch size and queue size
export HH_BATCH_SIZE="50"
export HH_MAX_QUEUE_SIZE="500"
export HH_FLUSH_INTERVAL="2.0"

Issue: SSL Certificate Errors

# For development only - disable SSL verification
export HH_VERIFY_SSL="false"

# For production - use proper certificates
export HH_SSL_CERT_PATH="/path/to/cert.pem"

Configuration Debugging

import os
from honeyhive.utils import get_configuration_summary

def debug_configuration():
    """Debug current configuration."""
    print("HoneyHive Configuration Debug:")
    print("=" * 40)

    # Core settings
    print(f"API Key: {'✓ Set' if os.getenv('HH_API_KEY') else '✗ Missing'}")
    print(f"Project: {os.getenv('HH_PROJECT', 'default')}")
    print(f"Source: {os.getenv('HH_SOURCE', 'unknown')}")
    print(f"Test Mode: {os.getenv('HH_TEST_MODE', 'false')}")

    # Network settings
    print(f"Base URL: {os.getenv('HH_BASE_URL', 'https://api.honeyhive.ai')}")
    print(f"Timeout: {os.getenv('HH_TIMEOUT', '30.0')}s")

    # Performance settings
    print(f"Batch Size: {os.getenv('HH_BATCH_SIZE', '100')}")
    print(f"Sampling Rate: {os.getenv('HH_SAMPLING_RATE', '1.0')}")

    # Debug environment
    all_hh_vars = {k: v for k, v in os.environ.items() if k.startswith('HH_')}
    if all_hh_vars:
        print("\nAll HH_ Environment Variables:")
        for key, value in sorted(all_hh_vars.items()):
            # Mask sensitive values
            if 'key' in key.lower() or 'secret' in key.lower():
                masked_value = value[:8] + "..." if len(value) > 8 else "***"
                print(f"  {key}={masked_value}")
            else:
                print(f"  {key}={value}")

Environment Variables Reference

Core Configuration Variables

Authentication

Project Configuration

Network Configuration

Testing and Development

Performance Configuration

Batching and Buffering

Connection Pooling

Tracing Configuration

Instrumentation Control

Backwards Compatibility Configuration

Sampling Configuration

Security Configuration

SSL/TLS Settings

Proxy Configuration

Data Privacy

Evaluation Configuration

Evaluator Settings

Provider-Specific Variables

OpenAI Configuration

Anthropic Configuration

Environment-Specific Configurations

Development Environment

Staging Environment

Production Environment

Container Deployment

Docker Configuration

Kubernetes Configuration

Configuration Validation

Environment Variable Validation

Configuration Loading Patterns

Hierarchical Configuration

Configuration Factory

Troubleshooting Configuration

Common Issues

Configuration Debugging

See Also