This is an experience report for my future reference (and yours).

The OpenTelemetry Collector is useful for receiving trace data in whatever format and exporting it to the back-end of your choice for storage and querying. For instance, I wanted to receive traces over HTTP/JSON from this sneaky browser extensionLINK and send them to Honeycomb. Honeycomb requires some headers that say whose event it is, plus it doesn’t yet receive OpenTelemetry traces over HTTP/JSON. The collector forward the traces on with the right headers and over gRPC.

I want to run the collector in Docker on my local computer. The instructions didn’t work (as of 10 Aug 2021). (This blog post didn’t work for a long time, as yaml changed. Updated 25 Nov 2023 4 October 2024)

Here’s what worked: one config file, and one docker command.

The simplest config I could get

One config file, called otel-local-config.yaml

receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318
        cors:
          allowed_origins:
            - "*"

processors:
  batch:

exporters:
  debug:
    verbosity: normal
  otlp:
    endpoint: "api.honeycomb.io:443"
    headers:
      "x-honeycomb-team": "HONEYCOMB-API-KEY-GOES-HERE"

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug, otlp]

This says:

“Receive OTLP events over HTTP. Allow all cross-origin requests.” OTLP is the protocol standard specified by OpenTelemetry.

“Handle batched events.”

“Export to the log, and also send the events over OTLP to the honeycomb endpoint, with the headers I need.” Don’t forget to substitute your Honeycomb API key and dataset name.

“Wire all that together so that all incoming OTLP events go out over both the logging and OTLP-to-honeycomb exporters.” Logging means it prints stuff to your screen.

This config is minimal, and suitable for local use, not production.

Run their docker container

Here it is, the secret command:

docker run \
-v "${PWD}/otel-local-config.yaml":/otel-local-config.yaml \
-p 4318:4318 \
-p 4317:4317 \
otel/opentelemetry-collector \
--config otel-local-config.yaml;

This says,

“run docker” (you knew that part)

“mount this config file from my current directory into the root directory in the container.”

“map the port 4318” which happens to be the standard port for OTLP over HTTP.

oh and 4317, the standard port for GRPC, because some of the instrumentation SDKs use that by default.

“Use the image otel/opentelemetry-collector from DockerHub.”

“pass into the container’s process this config argument to use that config file we mounted in from our local computer.” The container is running otelcol, assuming I found its Dockerfile.

Send traces here

Now you can send traces to http://localhost:4318/v1/traces

Instructions on the quickest way to do that are in this post.