Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt

Use this file to discover all available pages before exploring further.

Once you have a Collector configuration file, you can run the Collector locally with Docker to test your instrumentation and verify that data is reaching Honeycomb.

​
Setting up and running the Collector

Follow these steps to get your Collector running and confirm data is flowing before you tune it for production.
1

Choose your Collector image

The OpenTelemetry project publishes two Collector images. Choose the one that matches your use case:
  • opentelemetry-collector-contrib: Includes a broad set of receivers, processors, and exporters from the community, including Jaeger, Prometheus, and many vendor-specific components. Use this image if you need components beyond the core set.
  • opentelemetry-collector: The core image with a limited set of components maintained by the OpenTelemetry project. Use this image if you only need OTLP receivers and exporters and want a smaller footprint.
If you are unsure which to use, start with the contrib image.
2

Run the Collector with Docker

If your configuration file is called otel_collector_config.yaml in the current working directory, the following command pulls the image automatically on first run and starts the Collector with open ports for receiving OTLP data over gRPC (port 4317), HTTP (port 4318), and Jaeger Thrift HTTP (port 14268):
Run the following command to start the contrib Collector:
docker run \
  -p 14268:14268 \
  -p 4317-4318:4317-4318 \
  -v $(pwd)/otel_collector_config.yaml:/etc/otelcol-contrib/config.yaml \
  ghcr.io/open-telemetry/opentelemetry-collector-releases/opentelemetry-collector-contrib:latest
If you don’t need Jaeger support, you can omit -p 14268:14268 from the command.For additional deployment options, including Kubernetes and binary installs, visit the OpenTelemetry Collector documentation.
3

Verify data is reaching Honeycomb

After starting the Collector, send a test trace from your application and confirm it appears in Honeycomb. If data does not appear within a few minutes:
  • Check the Collector logs for errors. Docker will output these to stdout.
  • Confirm your API key is correct in the exporter configuration.
  • Confirm your application is exporting to the correct Collector port (4317 for gRPC, 4318 for HTTP).
  • Visit Common Issues with Sending Data in Honeycomb for additional troubleshooting tips.

​
Handling large requests

Honeycomb enforces a 15MB request size limit. Requests that exceed this limit return an error. To keep requests within this limit, set a batch size limit and enable compression when exporting to Honeycomb.

​
Configure maximum batch size

A Batch Processor has configuration options for send_batch_size and send_batch_max_size. Both options specify the number of spans, metric data points, or log records to include in each batch, but they behave differently:
  • send_batch_size: A soft target. The processor sends a batch when it reaches this size, but will not split data to enforce it. If a batch naturally exceeds the target, it sends as-is.
  • send_batch_max_size: A hard cap. The processor will split data if necessary to enforce it, guaranteeing no batch exceeds this size.
To stay reliably under Honeycomb’s 15MB request size limit, use send_batch_max_size. Note that these options count data points, not bytes. If your individual spans or metrics are large, you may need to set a lower limit than you expect. To enforce a hard maximum batch size with no delay: 
processors:
  batch:
    send_batch_max_size: 10000
    timeout: 0s

​
Enable compression

Collector exporters support compression for both gRPC and HTTP, which reduces request sizes and helps keep requests under the 15MB limit. Supported compression types are gzip, snappy, and zstd. To add compression to your exporter configuration: 
exporters:
  otlp_http:
    endpoint: "https://api.honeycomb.io:443"
    headers:
      "x-honeycomb-team": "YOUR_API_KEY"
    compression: gzip
For the full list of compression and transport options, visit HTTP Configuration Settings and gRPC Configuration Settings in the OpenTelemetry Collector GitHub repository.

​
Troubleshooting

To explore common issues when sending data, visit Common Issues with Sending Data in Honeycomb.