otelgen with Docker – Simulate Telemetry for the OTel Collector

When you’re first getting started with the OpenTelemetry Collector (or “OTel collector”), one of the biggest challenges is simply testing and validating your configuration. How do you know if your receivers are working? Are your filters doing what you expect? Is anything actually being exported? A utility called “otelgen” can help.

In previous how-tos, we’ve leveraged otelgen extensively to test our various collector configs, processors and optimizations.

otelgen: is a simple but powerful tool that generates synthetic telemetry data (traces, metrics, and logs) using the OTLP protocol — perfect for testing your pipeline.

And the best part? You can use it directly with Docker — no Go install, no local builds.

🐳 Why Use otelgen in Docker?

• ✅ No need to install Go or build from source
• ✅ Works on any machine with Docker
• ✅ Easily integrate with your local or containerized OpenTelemetry Collector
• ✅ Quickly test receivers, processors, filters, and exporters

🚀 Quickstart: Running otelgen in Docker Step 1: Start Your OpenTelemetry Collector

Ensure you have the OTLP receiver enabled in your collector config.

Example minimal OTel collector config snippet with Traces Pipeline:

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

exporters:
  debug:

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

Run your Collector locally (or in Docker), exposing the OTLP gRPC port (typically 4317) or HTTP port (4318).

Assuming the configuration is saved to a file called otel-config.yaml, run the OTel collector (OTel collector contrib) as a Docker container as follows:

docker run -v ./otel-config.yaml:/etc/otelcol-contrib/config.yaml -p 4317:4317 -p 4318:4318 otel/opentelemetry-collector-contrib:0.123.0

Step 2: Run otelgen via Docker

The otelgen project provides a ready-to-use container image:

docker run --rm ghcr.io/krzko/otelgen \
  --otel-exporter-otlp-endpoint host.docker.internal:4317

🔁 If you’re using Linux (vs Mac), replace host.docker.internal with localhost or your host IP.

🛠 Options and Customization

By default, otelgen sends a mix of traces, metrics, and logs using OTLP/gRPC.

You can control the behavior with flags:

Example: Generate 150 traces at 50 TPS (Traces per Second)

docker run --rm ghcr.io/krzko/otelgen \
  --otel-exporter-otlp-endpoint host.docker.internal:4317 \
  --rate 50 \
  --service-name test-app \
  --insecure \
  t m -t 150

Example: Generate (Gauge) Metrics

docker run --rm ghcr.io/krzko/otelgen:latest --otel-exporter-otlp-endpoint host.docker.internal:4317 --insecure metrics g

Example: Generate Logs

docker run --rm ghcr.io/krzko/otelgen:latest --otel-exporter-otlp-endpoint host.docker.internal:4317 --insecure logs m

🔍 Use Cases for otelgen

• ✅ Validate Collector configs before pushing to staging or prod
• ✅ Test sampling, filtering, aggregation, and routing rules
• ✅ Experiment with OTTL transforms in the collector
• ✅ Observe behavior in real-time using debug, file, or Prometheus exporters

📦 Example: Combine otelgen with OTel Collector in Docker Compose

Here’s a minimal docker-compose.yml setup:

services:
  collector:
    image: otel/opentelemetry-collector-contrib:0.123.0
    volumes:
      - ./otel-config.yaml:/etc/otel/config.yaml
    ports:
      - "4317:4317"  # OTLP gRPC
      - "4318:4318"  # OTLP HTTP
    command: ["--config=/etc/otelcol-contrib/config.yaml"]

  otelgen:
    image: ghcr.io/krzko/otelgen:latest
    depends_on:
      - collector
    command: ["--otel-exporter-otlp-endpoint=host.docker.internal:4317", "--insecure", "metrics", "g"]

🔁 Again, if you’re using Linux (vs Mac), replace host.docker.internal with localhost or your host IP.

🧠 Pro Tips

• Use otelgen in CI/CD to validate Collector configs before deployment.
• Pair with the OTLP debug exporter for visibility.
• Combine with MetaMetrics from ControlTheory to track cost-impacting telemetry patterns.

🧩 TL;DR

• otelgen is a fast, lightweight way to simulate telemetry.
• Use it with Docker to avoid local installs.
• Perfect for engineers and SREs validating OTel collector pipelines.

You don’t need real workloads to test your observability stack — just a controlled stream of synthetic data.

And with Docker + otelgen, that’s only one command away.

Want help building out a full control harness for your OpenTelemetry collectors and pipelines?

Reach out to ControlTheory →

Back

Share