HoneyHive Python SDK
A comprehensive Python SDK for HoneyHive, providing LLM observability, evaluation, and tracing capabilities with OpenTelemetry integration.
🚀 Features
- OpenTelemetry Integration - Full OTEL compliance with custom span processor and exporter
- Automatic Session Management - Seamless session creation and management
- Decorator Support - Easy-to-use
@trace(unified sync/async),@atrace, and@trace_classdecorators - Context Managers -
start_spanandenrich_spanfor manual span management - HTTP Instrumentation - Automatic HTTP request tracing
- Baggage Support - Context propagation across service boundaries
- Experiment Harness Integration - Automatic experiment tracking with MLflow, Weights & Biases, and Comet support
- Real-time API Integration - Direct integration with HoneyHive backend services
- Comprehensive Testing - Full test suite with 203 passing tests
📦 Installation
Choose Your Instrumentor Type:
HoneyHive supports both OpenInference (lightweight) and OpenLLMetry (enhanced metrics) instrumentors.
Option A: OpenInference (Recommended for Beginners)
# Install with OpenAI integration (most common)
pip install honeyhive[openinference-openai]
# Install with Anthropic integration
pip install honeyhive[openinference-anthropic]
# Install with Google AI integration
pip install honeyhive[openinference-google-ai]
# Install with multiple providers
pip install honeyhive[openinference-openai,openinference-anthropic,openinference-google-ai]
# Install all OpenInference integrations
pip install honeyhive[all-openinference]
Option B: OpenLLMetry (Enhanced Metrics)
# Install with OpenAI integration (enhanced metrics)
pip install honeyhive[traceloop-openai]
# Install with Anthropic integration
pip install honeyhive[traceloop-anthropic]
# Install with Google AI integration
pip install honeyhive[traceloop-google-ai]
# Install with multiple providers
pip install honeyhive[traceloop-openai,traceloop-anthropic,traceloop-google-ai]
# Install all OpenLLMetry integrations
pip install honeyhive[all-traceloop]
Option C: Mix Both Types
# Strategic mixing based on your needs
pip install honeyhive[traceloop-openai,openinference-anthropic]
Basic Installation (manual instrumentor setup required):
pip install honeyhive
📋 Including in Your Project
For detailed guidance on including HoneyHive in your pyproject.toml, see our pyproject.toml Integration Guide.
🔧 Quick Start
Basic Usage
from honeyhive import HoneyHiveTracer, trace
# Initialize tracer
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
source="production"
)
# Use unified decorator for automatic tracing (works with both sync and async)
@trace(event_type="demo", event_name="my_function")
def my_function():
return "Hello, World!"
@trace(event_type="demo", event_name="my_async_function")
async def my_async_function():
await asyncio.sleep(0.1)
return "Hello, Async World!"
# Manual span management
with tracer.start_span("custom-operation"):
# Your code here
pass
# With HTTP tracing enabled (new simplified API)
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
source="production",
disable_http_tracing=False # project derived from API key
)
Initialization
The HoneyHiveTracer.init() method is the recommended way to initialize the tracer:
from honeyhive import HoneyHiveTracer
# Standard initialization
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
source="production" # project derived from API key
)
# With custom server URL for self-hosted deployments
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
source="production",
server_url="https://custom-server.com" # project derived from API key
)
Enhanced Features Available
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor
# All features are available in the init method
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
source="production",
test_mode=True, # Test mode support
instrumentors=[OpenAIInstrumentor()], # Auto-integration
disable_http_tracing=True # Performance control
)
✅ The init method now supports ALL constructor features!
OpenInference Integration
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor
# Initialize tracer with OpenInference instrumentor (recommended pattern)
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
source="production",
instrumentors=[OpenAIInstrumentor()] # Auto-integration
)
# OpenInference automatically traces OpenAI calls
import openai
response = openai.ChatCompletion.create(
model="gpt-3.5-turbo",
messages=[{"role": "user", "content": "Hello!"}]
)
Enriching Spans and Sessions
v1.0+ Recommended Pattern: Instance Methods
from honeyhive import HoneyHiveTracer
# Initialize tracer
tracer = HoneyHiveTracer.init(
api_key="your-api-key",
)
# Use instance methods for enrichment (PRIMARY - Recommended)
@tracer.trace(event_type="tool")
def my_function(input_data):
result = process_data(input_data)
# ✅ Instance method (PRIMARY pattern in v1.0+)
tracer.enrich_span(
metadata={"input": input_data, "result": result},
metrics={"processing_time_ms": 150}
)
return result
# Enrich session with user properties
tracer.enrich_session(
user_properties={"user_id": "user-123", "plan": "premium"}
)
Legacy Pattern: Free Functions (Backward Compatibility)
For backward compatibility, the free function pattern from v0.2.x still works:
from honeyhive import trace, enrich_span, enrich_session
# Free functions with automatic tracer discovery (LEGACY)
@trace(event_type="tool")
def my_function(input_data):
result = process_data(input_data)
# Free function with auto-discovery (backward compatible)
enrich_span(
metadata={"input": input_data, "result": result},
metrics={"processing_time_ms": 150}
)
return result
# Enrich session via free function
enrich_session(user_properties={"user_id": "user-123"})
⚠️ Deprecation Notice: Free functions will be deprecated in v2.0. We recommend migrating to instance methods for new code.
Why Instance Methods?
- ✅ Explicit tracer reference (no auto-discovery overhead)
- ✅ Better multi-instance support (multiple tracers in same process)
- ✅ Clearer code (explicit is better than implicit)
- ✅ Future-proof (primary pattern going forward)
🏗️ Architecture
Core Components
src/honeyhive/
├── api/ # API client implementations
│ ├── client.py # Main API client
│ ├── configurations.py # Configuration management
│ ├── datapoints.py # Data point operations
│ ├── datasets.py # Dataset operations
│ ├── events.py # Event management
│ ├── evaluations.py # Evaluation operations
│ ├── metrics.py # Metrics operations
│ ├── projects.py # Project management
│ ├── session.py # Session operations
│ └── tools.py # Tool operations
├── tracer/ # OpenTelemetry integration
│ ├── otel_tracer.py # Main tracer implementation
│ ├── span_processor.py # Custom span processor
│ ├── span_exporter.py # Custom span exporter
│ ├── decorators.py # Tracing decorators
│ └── http_instrumentation.py # HTTP request tracing
├── evaluation/ # Evaluation framework
│ └── evaluators.py # Evaluation decorators
├── models/ # Pydantic models
│ └── generated.py # Auto-generated from OpenAPI
└── utils/ # Utility functions
├── config.py # Configuration management
├── connection_pool.py # HTTP connection pooling
├── retry.py # Retry mechanisms
└── logger.py # Logging utilities
Key Design Principles
- Singleton Pattern - Single tracer instance per application
- Environment Configuration - Flexible configuration via environment variables
- Graceful Degradation - Fallback mechanisms for missing dependencies
- Test Isolation - Comprehensive test suite with proper isolation
- OpenTelemetry Compliance - Full OTEL standard compliance
⚙️ Configuration
API keys
The HoneyHive API client selects a credential per operation:
| Key | Environment variable | HoneyHive() parameter |
Used for |
|---|---|---|---|
Data plane fine-grained (hh_fgdp_) |
HH_DATA_PLANE_API_KEY |
data_plane_api_key |
Supported project-scoped operations, currently charts |
Ingestion (hh_ingst_) |
HH_INGESTION_API_KEY |
ingestion_api_key |
Creating sessions and writing events |
Classic project (hh_, or hh_ro_ for reads) |
HH_API_KEY |
api_key |
Other operations, and ingestion when no ingestion key is set |
See API Keys to create the credentials your workload needs. A tracing-only process can use an ingestion key alone. Data plane fine-grained keys cannot send telemetry.
Data plane API key
Set HH_DATA_PLANE_API_KEY to a complete hh_fgdp_ key, or pass data_plane_api_key to HoneyHive(). For supported methods, pass project_id even when the key is rooted at that project:
import os
from honeyhive import HoneyHive
client = HoneyHive()
charts = client.charts.list(project_id=os.environ["PROJECT_ID"])
print(charts.data)
This example requires project.chart.list. Set PROJECT_ID to the project ID from Settings > Project > API Keys > Data Plane. Set HH_API_URL or pass base_url to HoneyHive() if the project's data plane URL differs from the default.
For a method with both legacy and scoped routes, omitting project_id selects the legacy route and classic project key, even if a data plane key is configured. Legacy chart calls are deprecated. Passing project_id selects the scoped route and requires a data plane key; there is no fallback to api_key or HH_API_KEY. See the credential matrix.
A wrong key type or incomplete value in data_plane_api_key or ingestion_api_key (or their environment variables) raises ValueError at initialization. A call whose required credential is absent raises MissingApiKeyError before sending a request.
Environment Variables
| Variable | Description | Default |
|---|---|---|
HH_API_KEY |
Classic project API key for operations that still require it, including datasets, event reads, and experiment runs; also used for ingestion when HH_INGESTION_API_KEY is unset |
Required for classic project-key operations |
HH_INGESTION_API_KEY |
Ingestion API key (hh_ingst_...) used to send traces and events; HH_API_KEY is used when unset |
Optional |
HH_DATA_PLANE_API_KEY |
Fine-grained data plane API key (hh_fgdp_...) for supported project-scoped calls, currently charts; pass project_id to the method |
Required for scoped chart operations |
HH_API_URL |
API base URL | https://api.dp1.us.honeyhive.ai |
HH_SOURCE |
Source environment | production |
HH_DISABLE_TRACING |
Disable tracing completely | false |
HH_DISABLE_HTTP_TRACING |
Disable HTTP request tracing | false |
HH_TEST_MODE |
Enable test mode | false |
HH_DEBUG_MODE |
Enable debug mode | false |
HH_VERBOSE |
Enable verbose API logging | false |
HH_OTLP_ENABLED |
Enable OTLP export | true |
Experiment Harness Variables
| Variable | Description | Default |
|---|---|---|
HH_EXPERIMENT_ID |
Unique experiment identifier | None |
HH_EXPERIMENT_NAME |
Human-readable experiment name | None |
HH_EXPERIMENT_VARIANT |
Experiment variant/treatment | None |
HH_EXPERIMENT_GROUP |
Experiment group/cohort | None |
HH_EXPERIMENT_METADATA |
JSON experiment metadata | None |
HTTP Client Configuration
| Variable | Description | Default |
|---|---|---|
HH_MAX_CONNECTIONS |
Maximum HTTP connections | 100 |
HH_MAX_KEEPALIVE_CONNECTIONS |
Keepalive connections | 20 |
HH_KEEPALIVE_EXPIRY |
Keepalive expiry (seconds) | 30.0 |
HH_POOL_TIMEOUT |
Connection pool timeout | 30.0 |
HH_RATE_LIMIT_CALLS |
Rate limit calls per window | 1000 |
HH_RATE_LIMIT_WINDOW |
Rate limit window (seconds) | 60.0 |
HH_HTTP_PROXY |
HTTP proxy URL | None |
HH_HTTPS_PROXY |
HTTPS proxy URL | None |
HH_NO_PROXY |
Proxy bypass list | None |
HH_VERIFY_SSL |
SSL verification | true |
🤝 Contributing
Want to contribute to HoneyHive? See CONTRIBUTING.md for development setup and guidelines.
5 maintainers
Metadata
5 maintainers
Release files for honeyhive 1.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| honeyhive-1.7.0.tar.gz | 1.1 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| honeyhive-1.7.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.5 MB
Release files / honeyhive-1.7.0.tar.gz
| Download URL | honeyhive-1.7.0.tar.gz |
|---|---|
| Size | 1.1 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cf48022fd157a0bcfc6b4964efdfa9e7630e5c86517e868ba94494631451ad2c
|
|
BLAKE2b-256 checksum How to use checksums |
39ea51f407ffbd840463f5951341b9a58c3f6b270d7f5eeac12311d2a7fa4952
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
Release files / honeyhive-1.7.0-py3-none-any.whl
| Download URL | honeyhive-1.7.0-py3-none-any.whl |
|---|---|
| Size | 458.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dac690add48514692534e231c7bedc67f5b86947560b7ccfe010ff4a3ab1e06a
|
|
BLAKE2b-256 checksum How to use checksums |
38ee1e2948b0cf4fa1ee55a7839080fef93bc11fedf6f269eec60cd571c85726
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.16
|
