HoneyHive Docs

Portkey is an AI gateway that provides a unified API to access 1,600+ LLMs with features like fallbacks, load balancing, caching, and budget limits. Since Portkey exposes an OpenAI-compatible API, HoneyHive automatically traces all requests routed through the gateway via the OpenAI instrumentor.

Quick Start

Add HoneyHive tracing to your Portkey-routed app. Initialize HoneyHive with the OpenAI instrumentor, then point your OpenAI client to Portkey’s gateway. All completions are automatically traced regardless of the underlying provider.

To see where to initialize the tracer for your environment, including AWS Lambda and long-running servers, see Tracer Initialization.

pip install honeyhive openinference-instrumentation-openai openai portkey-ai

import os
from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

# Point OpenAI client to Portkey's gateway
client = OpenAI(
    api_key=os.getenv("PORTKEY_API_KEY"),
    base_url=PORTKEY_GATEWAY_URL
)

# Use @provider-slug/model format from Portkey's Model Catalog
response = client.chat.completions.create(
    model="@openai-prod/gpt-4o-mini",
    messages=[{"role": "user", "content": "Hello, world!"}]
)
print(response.choices[0].message.content)

The @provider-slug/model format routes requests to the correct provider. Set up providers in Portkey’s Model Catalog by adding your provider credentials and naming the provider (e.g., openai-prod). The slug becomes @openai-prod.

What Gets Traced

The OpenAI instrumentor captures all calls through Portkey’s gateway:

Chat completions - Inputs, outputs, and token usage across any provider
Tool / function calls - Arguments and results for each tool invocation
Streaming responses - Streamed completions with aggregated tokens

No Portkey-specific instrumentor is required. The OpenAI instrumentor works because Portkey implements the OpenAI-compatible API format.

Example: Multi-Provider Routing

Switch between providers by changing the model slug. Each @provider-slug maps to credentials you configured in Portkey’s Model Catalog:

import os
from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL
from honeyhive import HoneyHiveTracer, trace
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

client = OpenAI(
    api_key=os.getenv("PORTKEY_API_KEY"),
    base_url=PORTKEY_GATEWAY_URL
)

@trace
def query_multiple_providers():
    # Route to OpenAI
    openai_response = client.chat.completions.create(
        model="@openai-prod/gpt-4o-mini",
        messages=[{"role": "user", "content": "Explain quantum computing briefly."}]
    )

    # Route to Anthropic
    anthropic_response = client.chat.completions.create(
        model="@anthropic-prod/claude-sonnet-4-5-20250929",
        messages=[{"role": "user", "content": "Explain quantum computing briefly."}],
        max_tokens=250
    )

    return openai_response, anthropic_response

query_multiple_providers()

Add each provider in the Model Catalog with a name like openai-prod or anthropic-prod. The provider slug becomes @openai-prod or @anthropic-prod.

Example: Fallbacks and Load Balancing

Use a Portkey config to define fallback or load-balancing rules. Create the config in the Portkey dashboard and pass its ID via the config header. HoneyHive traces whichever provider handles the request:

import os
from openai import OpenAI
from portkey_ai import PORTKEY_GATEWAY_URL, createHeaders
from honeyhive import HoneyHiveTracer, trace
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIInstrumentor().instrument(tracer_provider=tracer.provider)

client = OpenAI(
    api_key=os.getenv("PORTKEY_API_KEY"),
    base_url=PORTKEY_GATEWAY_URL,
    default_headers=createHeaders(
        api_key=os.getenv("PORTKEY_API_KEY"),
        config=os.getenv("PORTKEY_CONFIG_ID")
    )
)

@trace
def resilient_completion(prompt: str):
    return client.chat.completions.create(
        model="@openai-prod/gpt-4o",
        messages=[{"role": "user", "content": prompt}]
    )

resilient_completion("What are the benefits of AI observability?")

Example config JSON for fallback between providers:

{
  "strategy": { "mode": "fallback" },
  "targets": [
    { "override_params": { "model": "@openai-prod/gpt-4o" } },
    { "override_params": { "model": "@anthropic-prod/claude-sonnet-4-5-20250929" } }
  ]
}

See Portkey’s configs docs for more patterns including load balancing, conditional routing, and caching.

Environment Configuration

# HoneyHive
export HH_API_KEY="your-honeyhive-api-key"

# Portkey
export PORTKEY_API_KEY="your-portkey-api-key"
export PORTKEY_CONFIG_ID="your-config-id"   # optional, for fallback/routing configs

Troubleshooting

Traces not appearing

Check the instrumentor - Ensure OpenAIInstrumentor is initialized with tracer_provider=tracer.provider before making any calls
Verify base_url - The OpenAI client must point to Portkey’s gateway (PORTKEY_GATEWAY_URL or https://api.portkey.ai/v1)
Check HH_API_KEY - Ensure your HoneyHive API key is set correctly

Requests failing with provider errors

Check the model slug - Use the @provider-slug/model-name format (e.g., @openai-prod/gpt-4o-mini). The provider slug must match a provider you configured in Model Catalog
Verify model name - Use the model name expected by the target provider (e.g., gpt-4o-mini for OpenAI, claude-sonnet-4-5-20250929 for Anthropic)

Duplicate spans

If you use both a Portkey client and a direct OpenAI client in the same app, both will be traced by the same instrumentor. Use HoneyHive’s @trace decorator to group related calls into named spans for clarity.

OpenAI Integration

Base OpenAI integration that powers Portkey tracing

LiteLLM Integration

Alternative multi-provider gateway with HoneyHive support

Use Portkey for LLM Evaluators

Route LLM evaluator calls through Portkey to access any supported model

Custom Spans

Create spans for business logic around API calls

Enrich Your Traces

Add user IDs and custom metadata to traces

How to integrate HoneyHive with Portkey

Quick Start

What Gets Traced

Example: Multi-Provider Routing

Example: Fallbacks and Load Balancing

Environment Configuration

Troubleshooting

Traces not appearing

Requests failing with provider errors

Duplicate spans

OpenAI Integration

LiteLLM Integration

Use Portkey for LLM Evaluators

Custom Spans

Enrich Your Traces

Resources

​Quick Start

​What Gets Traced

​Example: Multi-Provider Routing

​Example: Fallbacks and Load Balancing

​Environment Configuration

​Troubleshooting

​Traces not appearing

​Requests failing with provider errors

​Duplicate spans

​Related

OpenAI Integration

LiteLLM Integration

Use Portkey for LLM Evaluators

Custom Spans

Enrich Your Traces

​Resources

Quick Start

What Gets Traced

Example: Multi-Provider Routing

Example: Fallbacks and Load Balancing

Environment Configuration

Troubleshooting

Traces not appearing

Requests failing with provider errors

Duplicate spans

Related

Resources