How to send OpenTelemetry Collector traces to HoneyHive

The OpenTelemetry Collector receives telemetry from your services, processes it, and forwards it to one or more backends. HoneyHive ingests OTLP/HTTP traces directly, so any application or framework that already exports OTLP can reach HoneyHive through a collector you run, with no HoneyHive SDK code in the application.

Application (OTLP gRPC :4317 or HTTP :4318)  ->  OpenTelemetry Collector  ->  HoneyHive (OTLP/HTTP)

Use a collector when you want one place to manage credentials, batching, retries, and fan-out to several backends, or when your platform can only export to a local OTLP endpoint.

Prerequisites

OpenTelemetry Collector Contrib (otelcol-contrib), as a binary, container, or Kubernetes deployment. The session grouping step below uses the transform processor, which ships in Contrib.
A HoneyHive ingestion API key from Settings → Project → API Keys, on the Ingestion tab
An application that exports OTLP traces, either through an OpenTelemetry SDK or a framework with built-in OTLP export

Provider host and OTLP traces URL

HoneyHive routes OTLP ingestion through your deployment’s API host. Replace <provider-host> with the hostname shown in your HoneyHive dashboard or API settings:

https://<provider-host>/opentelemetry/v1/traces

Example for a US production deployment:

https://api.dp1.us.prod.honeyhive.ai/opentelemetry/v1/traces

Use the exact host for your org and environment. If ingest fails, confirm the hostname matches the region where your project lives.

Configure the collector

Create a HoneyHive ingestion API key

In HoneyHive, open Settings → Project → API Keys, click Create API Key on the Ingestion tab, and copy the key. The key determines which HoneyHive project receives traces, and an ingestion key can do nothing else.

Set the HoneyHive environment variables

Store the endpoint and key in the collector’s environment rather than in the config file:

export HH_OTLP_TRACES_ENDPOINT="https://<provider-host>/opentelemetry/v1/traces"
export HH_INGESTION_API_KEY="<HH_INGESTION_API_KEY>"

In Kubernetes, load HH_INGESTION_API_KEY from a Secret.

Write the collector config

Save this as config.yaml. It accepts OTLP over gRPC and HTTP, groups each trace into one HoneyHive session, batches spans, and exports them to HoneyHive over OTLP/HTTP:

config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  transform/honeyhive_session:
    error_mode: ignore
    trace_statements:
      - set(span.attributes["honeyhive.session_id"], span.trace_id.string) where span.attributes["honeyhive.session_id"] == nil
  batch: {}

exporters:
  otlp_http/honeyhive:
    traces_endpoint: ${env:HH_OTLP_TRACES_ENDPOINT}
    headers:
      Authorization: "Bearer ${env:HH_INGESTION_API_KEY}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [transform/honeyhive_session, batch]
      exporters: [otlp_http/honeyhive]

Set traces_endpoint to the full HoneyHive URL. The exporter’s generic endpoint setting appends /v1/traces to whatever you pass, so it does not produce the /opentelemetry/v1/traces path on its own.

Start the collector

With Docker:

docker run -d --name otelcol \
  -p 4317:4317 -p 4318:4318 \
  -e HH_OTLP_TRACES_ENDPOINT \
  -e HH_INGESTION_API_KEY \
  -v "$PWD/config.yaml:/etc/otelcol-contrib/config.yaml" \
  otel/opentelemetry-collector-contrib:0.161.0

This page was tested with 0.161.0. Older releases that reject the otlp_http exporter name use otlphttp instead. The collector logs Everything is ready. Begin running and processing data. once both receivers are listening.

Point your application at the collector

Applications that use the standard OpenTelemetry environment variables only need the collector address. HoneyHive credentials stay in the collector.

Variable	Value	Notes
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://<collector-host>:4318`	OTLP/HTTP receiver. Use `http://<collector-host>:4317` for gRPC
`OTEL_EXPORTER_OTLP_PROTOCOL`	`http/protobuf`	Set to `grpc` when you target port `4317`
`OTEL_SERVICE_NAME`	`<your-service>`	Appears on each HoneyHive event as `service.name` metadata

With OTEL_EXPORTER_OTLP_ENDPOINT, SDKs append /v1/traces for HTTP, which matches the collector’s HTTP receiver path. Remove any OTEL_EXPORTER_OTLP_HEADERS value that carried a HoneyHive key, since the collector adds the Authorization header.

Group spans into sessions

HoneyHive groups events into sessions by session_id. Raw OTLP spans usually do not carry one, so spans from the same trace can land in separate sessions. The transform/honeyhive_session processor copies each span’s trace ID into the honeyhive.session_id attribute, so every span in a trace shares one session and keeps its parent-child hierarchy. HoneyHive stores the session under a UUID derived from that value, so search for sessions by event or span name rather than by trace ID. The where clause leaves spans that already set honeyhive.session_id, such as spans from the HoneyHive SDK, unchanged. Remove the processor from the pipeline if you set session IDs in your application.

Verify traces in HoneyHive

Send a request through your application, then open the Traces tab for the project tied to your ingestion key. Events from the collector have source set to otlp, and the root span and its children appear in one session. Spans that follow the OpenTelemetry GenAI semantic conventions, such as gen_ai.request.model, gen_ai.input.messages, and gen_ai.usage.input_tokens, appear as model events with the prompt, completion, model, and token counts filled in. See the semantic conventions reference for every attribute HoneyHive maps. If traces do not appear:

Confirm HH_OTLP_TRACES_ENDPOINT uses your HoneyHive API host and ends with /opentelemetry/v1/traces.
Confirm the exporter header is exactly Authorization: Bearer <HH_INGESTION_API_KEY> and the variable is set in the collector’s environment. A 401 in the collector logs means the key is missing or invalid.
Confirm the ingestion key was created in the HoneyHive project where you expect the traces to appear.
Check that the collector can reach the HoneyHive API host over outbound HTTPS.
If the collector fails to start with an unknown exporter type, your release predates otlp_http. Rename the exporter to otlphttp. Do not use the otlp exporter, which sends gRPC.
To confirm spans reach the collector, add the debug exporter to the traces pipeline and check the collector logs for span counts.

Configuration reference

Setting	Value
Exporter	`otlp_http`
Protocol	OTLP/HTTP, protobuf or JSON
Traces endpoint	`https://<provider-host>/opentelemetry/v1/traces`
Auth header	`Authorization: Bearer <HH_INGESTION_API_KEY>`
Session attribute	`honeyhive.session_id`
Collector receivers	gRPC `4317`, HTTP `4318`

OpenTelemetry concepts

Learn how HoneyHive stores OTLP traces and AI span attributes

Distributed tracing

Connect spans across services into one trace

Semantic conventions

See which span attributes HoneyHive maps to inputs, outputs, and metadata

API keys

Create and manage project-bound ingestion keys

Agent Frameworks & Platforms

Model Providers

AI Gateways

Coding Agents

OpenTelemetry

Evaluation

How to send OpenTelemetry Collector traces to HoneyHive

Prerequisites

Provider host and OTLP traces URL

Configure the collector

Group spans into sessions

Verify traces in HoneyHive

Configuration reference

OpenTelemetry concepts

Distributed tracing

Semantic conventions

API keys

Resources

​Prerequisites

​Provider host and OTLP traces URL

​Configure the collector

​Group spans into sessions

​Verify traces in HoneyHive

​Configuration reference

​Related

OpenTelemetry concepts

Distributed tracing

Semantic conventions

API keys

​Resources

Prerequisites

Provider host and OTLP traces URL

Configure the collector

Group spans into sessions

Verify traces in HoneyHive

Configuration reference

Related

Resources