Skip to main content
This guide provides instructions for integrating Honeycomb with the TrueFoundry AI Gateway to export OpenTelemetry traces and metrics.

​
What is Honeycomb?

Honeycomb is an observability platform designed for debugging and understanding complex distributed systems. It ingests OpenTelemetry data natively over OTLP (HTTP and gRPC) and provides a query builder, trace viewer, and dashboards for analysing LLM gateway behaviour in production.

​
Key Features of Honeycomb

  • Trace Query Builder: Slice and filter spans by any attribute, including TrueFoundry-emitted fields like tfy.span_type and gen_ai.request.model.
  • Metrics Explorer: Visualise OTLP metrics over time with aggregations and groupings across models, users, and environments.
  • Environments and Datasets: Organise telemetry into named datasets per service or team, with the x-honeycomb-dataset header controlling routing.

​
Prerequisites

Before integrating Honeycomb with TrueFoundry, ensure you have:
  1. TrueFoundry Account: Create a TrueFoundry account and follow the instructions in our Gateway Quick Start Guide.
  2. Honeycomb Account: Sign up at honeycomb.io and create an ingest API key with Send Events permission.

​
Understanding the Honeycomb Endpoint

Honeycomb exposes two regional base URLs:
RegionBase URL
US (default)https://api.honeycomb.io
EUhttps://api.eu1.honeycomb.io
TrueFoundry does not auto-append signal paths, so you must supply the full path including /v1/traces or /v1/metrics. For example, a US traces endpoint is https://api.honeycomb.io/v1/traces. Your account region is shown in the Honeycomb UI URL — ui.honeycomb.io indicates US; ui.eu1.honeycomb.io indicates EU.

​
Integration Steps

1

Create a Honeycomb Ingest API Key

  1. Log into your Honeycomb account and navigate to Team Settings → API Keys.
  2. Click Create API Key and select the Send Events permission scope.
  3. Copy the generated API key — you will need it in the next step.
Honeycomb routes traces into a dataset matching your service.name attribute. TrueFoundry sets this to tfy-llm-gateway automatically, so your traces will appear under a dataset of that name unless you override it via the x-honeycomb-dataset header.
2

Configure OTEL Export in TrueFoundry

  1. Go to AI Gateway → Controls → Settings in the TrueFoundry dashboard.
  2. Scroll down to the OTEL Config section and click the edit (✏️) button.
TrueFoundry AI Gateway Settings page showing the OTEL Config section with Traces Endpoint and Headers
  1. Enable the Otel Traces Exporter Configuration toggle and fill in:
FieldValue
ToggleEnabled
ProtocolHTTP Configuration
Endpointhttps://api.honeycomb.io/v1/traces (US) or https://api.eu1.honeycomb.io/v1/traces (EU)
EncodingProto
Header Keyx-honeycomb-team
Header Value<your-honeycomb-api-key>
TrueFoundry OTEL Traces Exporter Configuration showing Honeycomb endpoint and x-honeycomb-team header
  1. Enable the Otel Metrics Exporter Configuration toggle and fill in:
FieldValue
ToggleEnabled
ProtocolHTTP Configuration
Endpointhttps://api.honeycomb.io/v1/metrics (US) or https://api.eu1.honeycomb.io/v1/metrics (EU)
EncodingProto
Header Keyx-honeycomb-team
Header Value<your-honeycomb-api-key>
  1. Click Save to apply the configuration.
To route metrics into a specific Honeycomb dataset rather than the default unknown_metrics, add a second header: key x-honeycomb-dataset, value set to your chosen dataset name. Click + Add Headers in TrueFoundry to add multiple header pairs.
3

Verify the Integration

  1. Make a request through the TrueFoundry AI Gateway.
  2. Log into your Honeycomb account and open the Traces tab on the tfy-llm-gateway dataset.
  3. You will see a list of traces with Root Service set to tfy-llm-gateway. Span names follow the pattern MCPGateway: resources/list, ChatCompletion, and so on depending on the operation type.
Honeycomb Traces tab showing tfy-llm-gateway traces with Root Service, Root Name, Duration, and Trace ID columns
  1. Click any Trace ID to expand it and inspect individual spans. You will see the full span waterfall including nested child spans with latency breakdowns.
Honeycomb expanded trace view showing span waterfall for a tfy-llm-gateway MCPGateway operation with nested spans
  1. From the dataset Overview tab you can also monitor aggregate Trace Volume, Span Volume, and Error Volume over time to confirm data is flowing continuously.
Honeycomb dataset overview showing Total Spans, Total Errors, Trace Volume, Span Volume, and Error Volume charts for tfy-llm-gateway

​
Configuration Reference

ConfigurationValue
Traces Endpoint (US)https://api.honeycomb.io/v1/traces
Traces Endpoint (EU)https://api.eu1.honeycomb.io/v1/traces
Metrics Endpoint (US)https://api.honeycomb.io/v1/metrics
Metrics Endpoint (EU)https://api.eu1.honeycomb.io/v1/metrics
ProtocolHTTP
EncodingProto
Auth Header Keyx-honeycomb-team
Auth Header ValueYour Honeycomb ingest API key
Dataset Header Key (optional)x-honeycomb-dataset
Dataset Header Value (optional)Your chosen Honeycomb dataset name