OpenTelemetry Collector Quick Start; Documentation Audit

Observations

• Time estimate may be optimistic; "less than five minutes" doesn't account for installing Go, configuring GOBIN, or pulling the Docker image for the first time. If these steps take longer than expected, it can affect user confidence early on.
• Prerequisites lack context; Docker, Go, and GOBIN are listed without indicating which steps depend on each tool. This makes it harder for readers to understand their relevance upfront.
• ZPages is introduced without explanation; port 55679 appears in the docker run command, but its purpose isn't explained until later. This can make the command feel like boilerplate rather than intentional configuration.
• Versioning lacks discoverability; the Collector version (0.149.0) is pinned, but there's no direct reference for checking newer releases. Readers may need to search externally to verify it.
• Optional commands interrupt the main flow; the grep command appears inline with core steps, which can make it unclear whether it's required. This adds unnecessary complexity for beginners.
• Next steps lack guidance; multiple links are presented with equal weight, including advanced topics like building a custom Collector. A more guided progression would help users decide what to explore next.

These observations were submitted to the OpenTelemetry documentation repository — Issue #9589.

Open Source Contribution

These observations were submitted to the OpenTelemetry documentation repository — Issue #9589.

Rewrite

Introduction

Get the OpenTelemetry Collector running locally and see traces flowing through it in minutes.

In this guide, you will:

• Run the Collector on your machine
• Send sample traces using a test utility
• Verify that traces are received and processed

You'll need Docker and Go installed before starting. This guide takes about 10–15 minutes to complete.

By the end, you'll have a working telemetry pipeline you can build on. For a deeper explanation of how the Collector works, see the Collector overview.

Prerequisites

You'll need the following tools installed:

• Docker — used to run the Collector container
• Go 1.20 or later — used to install the telemetry generator
• GOBIN set — ensures installed Go binaries are available in your PATH

If GOBIN isn't set, run:

export GOBIN=${GOBIN:-$(go env GOPATH)/bin}

This guide uses bash. If you're using a different shell, you may need to adjust the command syntax.

Set up the environment

Pull the OpenTelemetry Collector Docker image:

docker pull otel/opentelemetry-collector:0.149.0

This command uses a fixed version for consistency. Check the Collector releases page for newer versions.

Next, install telemetrygen, a tool used to generate sample telemetry data:

go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latest

Generate and collect telemetry

Start the Collector

In your first terminal, run:

docker run \
  -p 127.0.0.1:4317:4317 \
  -p 127.0.0.1:4318:4318 \
  -p 127.0.0.1:55679:55679 \
  otel/opentelemetry-collector:0.149.0

This starts the Collector and exposes:

• 4317 — OTLP (gRPC)
• 4318 — OTLP (HTTP)
• 55679 — ZPages

ZPages is the Collector's built-in debug interface. It lets you inspect traces directly in your browser without connecting an external backend.

Generate sample traces

Open a second terminal and run:

$GOBIN/telemetrygen traces --otlp-insecure --traces 3

You should see output similar to:

traces generated {"worker": 0, "traces": 3}

This confirms that telemetry was successfully generated and sent to the Collector.

View traces in the browser

Open:

http://localhost:55679/debug/tracez

Select any trace from the table to inspect it.

Stop the Collector

Press Ctrl+C to stop the Collector.

(Optional) Inspect Collector logs

If you want to dig deeper into the Collector's output, you can pipe logs to a file:

docker run \
  -p 127.0.0.1:4317:4317 \
  -p 127.0.0.1:4318:4318 \
  -p 127.0.0.1:55679:55679 \
  otel/opentelemetry-collector:0.149.0 \
  2>&1 | tee collector-output.txt

Then filter relevant entries:

grep -E '^Span|(ID|Name|Kind|time|Status \w+)\s+:' collector-output.txt

Next steps

You've run the OpenTelemetry Collector locally and verified that traces flow through it. Here's where to go next, in order of what makes the most sense after this guide:

• Configuration; Learn how the Collector's config file works and how to connect it to a real backend like Jaeger or Prometheus
• Deployment methods; Understand the difference between running the Collector as an agent versus a gateway
• Install the Collector; Explore installation options beyond Docker, including binaries and Kubernetes
• Component registry; Browse available receivers, processors, and exporters to extend your pipeline