How-to Guides

Note

Problem-oriented documentation

These guides help you solve specific problems and accomplish particular tasks. They assume you have basic familiarity with HoneyHive and focus on practical solutions.

Quick Navigation:

Overview 

How-to guides are organized by problem domain. Each guide provides step-by-step instructions to solve real-world challenges you might encounter when using HoneyHive.

When to use these guides:

You have a specific problem to solve
You need to integrate with a particular system
You want to implement a specific pattern or technique
You’re troubleshooting an issue

Getting Started 

Start here - Essential setup patterns for successful HoneyHive integration:

Where Should I Initialize the Tracer?

Note

Most Common Question: “Where should I initialize the tracer?”

This guide covers 5 scenarios: local development, evaluate(), serverless (Lambda), long-running servers, and testing. Read this first to avoid common initialization pitfalls.

Migration & Compatibility 

Guides for migrating from older versions and ensuring backwards compatibility.

Quick solutions for specific provider integration challenges. HoneyHive supports both OpenInference and OpenLLMetry instrumentors to automatically trace LLM calls from any provider with zero code changes.

Custom Tracing 

Build sophisticated observability:

Build Custom Tracing

Testing Your Application 

Test your LLM application with HoneyHive tracing:

Testing Applications with HoneyHive

Note

SDK Development Testing

For testing the HoneyHive SDK itself (SDK contributors), see SDK Development.

Evaluate LLM Outputs 

Set up quality monitoring and evaluation:

Evaluation & Analysis Guides

Deploy to Production 

Keep applications running reliably:

Monitor & Export 

Track and export your observability data:

How to Export Traces

Build Common Patterns 

Implement proven architectural patterns:

LLM Application Patterns

Quick Solutions:

See “Troubleshooting” section below - Fix common issues and setup problems
Integrate with OpenAI - Add OpenAI tracing in 5 minutes
Custom Span Management - Create custom trace spans
Multi-Provider Integration - Use multiple LLM providers
Evaluation & Analysis Guides - Set up basic evaluation

Production Workflows:

Where Should I Initialize the Tracer? - Where should I initialize the tracer? (local, serverless, server, evaluate)
Setting up HoneyHive in your Python Package Manager - Include HoneyHive in your pyproject.toml
Production Deployment Guide - Deploy HoneyHive to production
Evaluation & Analysis Guides - Build comprehensive evaluation pipelines
LLM Application Patterns - Agent patterns (ReAct, Plan-Execute, RAG) with tradeoffs and trace hierarchies

Troubleshooting 

Common issues and step-by-step solutions for HoneyHive integration challenges.

Not seeing traces in your dashboard?

Check API key configuration:

import os
print(f"API Key set: {'HH_API_KEY' in os.environ}")
print(f"Source set: {'HH_SOURCE' in os.environ}")  # Optional environment identifier

Verify network connectivity:

# Test HoneyHive API connectivity
curl -H "Authorization: Bearer YOUR_API_KEY" https://api.honeyhive.ai/health

Check project settings - Ensure your project name matches exactly in the HoneyHive dashboard.

Import or installation errors?

Installation problems:

# Update pip and install in clean environment
pip install --upgrade pip
python -m venv honeyhive-env
source honeyhive-env/bin/activate  # Linux/Mac
# honeyhive-env\Scripts\activate   # Windows
pip install honeyhive

Dependency conflicts:

# Check for conflicts
pip check

# Use fresh virtual environment (recommended)
python -m venv fresh-env
source fresh-env/bin/activate
pip install honeyhive

Python version compatibility - HoneyHive requires Python 3.11+:

import sys
if sys.version_info < (3, 11):
    print("❌ Python 3.11+ required")
else:
    print("✅ Python version compatible")

Tracing not working as expected?

Debug trace collection:

# Enable tracer debug logging (recommended - shows tracer internals)
from honeyhive import HoneyHiveTracer
tracer = HoneyHiveTracer.init(
    api_key="your-key",      # Or set HH_API_KEY environment variable
    project="your-project",  # Or set HH_PROJECT environment variable
    source="debug",          # Or set HH_SOURCE environment variable
    verbose=True             # Enable detailed debug logging for tracer
)
print(f"Tracer initialized: {tracer is not None}")

# Alternative: Enable Python's standard debug logging (shows all modules)
import logging
logging.basicConfig(level=logging.DEBUG)

Validate event_type values - Use proper EventType enum:

from honeyhive.models import EventType

# ✅ Correct usage
with tracer.trace("my_operation", event_type=EventType.tool) as span:
    pass

# ❌ Incorrect - don't use strings
# event_type="tool"

Instrumentor initialization order - Initialize tracer before instrumentors:

# ✅ Correct order
from honeyhive import HoneyHiveTracer

# Step 1: Initialize HoneyHive tracer FIRST (without instrumentors)
tracer = HoneyHiveTracer.init(
    api_key="...",           # Or set HH_API_KEY environment variable
    project="your-project"   # Or set HH_PROJECT environment variable
)

# Step 2: Initialize instrumentors separately with tracer_provider
from openinference.instrumentation.openai import OpenAIInstrumentor
instrumentor = OpenAIInstrumentor()
instrumentor.instrument(tracer_provider=tracer.provider)

Warning

Common Issue: If you see “⚠️ Existing provider doesn’t support span processors”, this indicates a ProxyTracerProvider issue. The fix above resolves this by ensuring HoneyHive creates a real TracerProvider first.

Network & SSL Issues?

SSL Certificate Verification Errors (SSLCertVerificationError, CERTIFICATE_VERIFY_FAILED):

from honeyhive import HoneyHiveTracer

# Option 1: Use custom CA bundle (recommended for corporate environments)
import os
os.environ['REQUESTS_CA_BUNDLE'] = '/path/to/ca-bundle.crt'

tracer = HoneyHiveTracer.init(
    api_key="your-key",
    project="your-project"
)

# Option 2: Disable SSL verification (NOT recommended for production)
tracer = HoneyHiveTracer.init(
    api_key="your-key",
    project="your-project",
    verify_ssl=False  # Use only for local development/testing
)

Corporate Proxy / Firewall Issues:

# Set proxy environment variables
export HTTPS_PROXY=http://proxy.company.com:8080
export HTTP_PROXY=http://proxy.company.com:8080

# Test connectivity
curl -x $HTTPS_PROXY https://api.honeyhive.ai/health

# Configure in Python code
import os
os.environ['HTTPS_PROXY'] = 'http://proxy.company.com:8080'

from honeyhive import HoneyHiveTracer
tracer = HoneyHiveTracer.init(api_key="your-key")

Timeout Errors (ConnectionTimeout, ReadTimeout):

# Increase timeout for slow networks
tracer = HoneyHiveTracer.init(
    api_key="your-key",
    project="your-project",
    timeout=60.0  # Increase from default 30s
)

DNS Resolution Issues:

# Verify DNS resolution
nslookup api.honeyhive.ai

# Test direct connectivity
ping api.honeyhive.ai

# Check SSL certificate
openssl s_client -connect api.honeyhive.ai:443 -showcerts

For additional troubleshooting resources, see Production Deployment Guide for production deployment best practices or contact support.

Getting Help 

If you can’t find what you’re looking for:

Check the “Troubleshooting” section above for common issues
Search the API Reference for API details
Read Explanation for conceptual understanding
Join our Discord community
Email support@honeyhive.ai

Contributing:

Found a gap in our guides? We’d love to add more how-to content based on real user needs. Please let us know what problems you’re trying to solve!