> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How to send OpenTelemetry Collector traces to HoneyHive

> Configure an OpenTelemetry Collector to forward OTLP traces to HoneyHive. Receive gRPC or HTTP spans, batch them, and export OTLP/HTTP to your HoneyHive project.

The [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/) receives telemetry from your services, processes it, and forwards it to one or more backends. [HoneyHive](https://www.honeyhive.ai/) 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.

```text theme={null}
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](https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-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](/v2/workspace/api-keys#ingestion-keys) from [**Settings → Project → API Keys**](https://app.us.honeyhive.ai/settings/project/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:

```text theme={null}
https://<provider-host>/opentelemetry/v1/traces
```

Example for a US production deployment:

```text theme={null}
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

<Steps>
  <Step title="Create a HoneyHive ingestion API key">
    In HoneyHive, open [**Settings → Project → API Keys**](https://app.us.honeyhive.ai/settings/project/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](/v2/workspace/api-keys#ingestion-keys) can do nothing else.
  </Step>

  <Step title="Set the HoneyHive environment variables">
    Store the endpoint and key in the collector's environment rather than in the config file:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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:

    ```yaml config.yaml theme={null}
    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.
  </Step>

  <Step title="Start the collector">
    With Docker:

    ```bash theme={null}
    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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Group spans into sessions

HoneyHive groups events into [sessions](/v2/tracing/concepts) 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`](/v2/sdk-reference/semconv-alignment) 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](https://opentelemetry.io/docs/specs/semconv/gen-ai/), 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](/v2/sdk-reference/semconv-reference) for every attribute HoneyHive maps.

If traces do not appear:

1. Confirm `HH_OTLP_TRACES_ENDPOINT` uses your HoneyHive API host and ends with `/opentelemetry/v1/traces`.
2. 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.
3. Confirm the ingestion key was created in the HoneyHive project where you expect the traces to appear.
4. Check that the collector can reach the HoneyHive API host over outbound HTTPS.
5. 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.
6. To confirm spans reach the collector, add the [`debug` exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/debugexporter) 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` |

## Related

<CardGroup cols={2}>
  <Card title="OpenTelemetry concepts" icon="network-wired" href="/v2/tracing/concepts">
    Learn how HoneyHive stores OTLP traces and AI span attributes
  </Card>

  <Card title="Distributed tracing" icon="share-nodes" href="/v2/tutorials/distributed-tracing">
    Connect spans across services into one trace
  </Card>

  <Card title="Semantic conventions" icon="tags" href="/v2/sdk-reference/semconv-reference">
    See which span attributes HoneyHive maps to inputs, outputs, and metadata
  </Card>

  <Card title="API keys" icon="key" href="/v2/workspace/api-keys">
    Create and manage project-bound ingestion keys
  </Card>
</CardGroup>

## Resources

* [OpenTelemetry Collector documentation](https://opentelemetry.io/docs/collector/)
* [OTLP/HTTP exporter](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/otlphttpexporter)
* [Transform processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor)


## Related topics

- [How to migrate from Langfuse to HoneyHive](/v2/tracing/migrate-from-langfuse.md)
- [HoneyHive Tracing Concepts](/v2/tracing/concepts.md)
- [Introducing HoneyHive](/v2/introduction/what-is-hhai.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.