Full lesson
Explore the full explanation, examples, and visuals at your own pace.
Part 1
The OpenTelemetry Collector receives telemetry, processes it, and forwards it to backends. Telemetry just means traces, metrics, and logs from your apps. Here, telemetrygen sends traces to the receivers, then processors and exporters pass them on. This demo runs locally to show how it works, not to be production-ready.
Before you begin
You need three things first. Docker, or a compatible container runtime, runs the Collector. Go installs telemetrygen, our test client. And GOBIN needs to be set, so installed Go binaries land on your PATH. The commands use bash.
- Docker or compatible container runtime
- Go, one of latest two minors
- GOBIN environment variable set
Set up the environment
Three commands, in order. First, the export line sets GOBIN only if it's missing, so installed Go tools land on your PATH. Next, docker pull downloads the Collector core image, pinned to version 0.164.0. Last, go install fetches telemetrygen, a tool that simulates a client sending telemetry.
# Only if GOBIN isn't set
export GOBIN=${GOBIN:-$(go env GOPATH)/bin}
# Pull the Collector core distribution
docker pull otel/opentelemetry-collector:0.164.0
# Install the telemetry generator
go install github.com/open-telemetry/opentelemetry-collector-contrib/cmd/telemetrygen@latestStart the Collector
General knowledgeThis docker run command starts the Collector. Each dash p flag publishes a container port, and the 127.0.0.1 prefix limits it to your own machine. Then 2>&1 merges error output into standard output, and tee both prints it on screen and saves it to collector-output.txt, so we can search it later.
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.164.0 \
2>&1 | tee collector-output.txtThree ports, three ways in
Each port serves a different visitor. Port 4317 takes OTLP over gRPC, the default for most SDKs. OTLP is OpenTelemetry's own protocol for sending telemetry. Port 4318 takes OTLP over HTTP, for clients that don't support gRPC. Port 55679 is zPages, a debug page you open in a browser.
Second terminal: send traces, then check
Open a second terminal and run telemetrygen with the traces command, asking for three traces. It prints a confirmation line showing traces: 3. Then go back to the Collector terminal and grep collector-output.txt. That pulls out the span IDs, names, kinds, times, and statuses the Collector received.
$GOBIN/telemetrygen traces --otlp-insecure --traces 3
# Expected output
INFO traces/worker.go:99 traces generated {"worker": 0, "traces": 3}
INFO traces/traces.go:58 stop the batch span processor
# Back in the Collector terminal
grep -E '^Span|(ID|Name|Kind|time|Status \w+)\s+:' ./collector-output.txtVerifying the pipeline end to end
General knowledgeFollow the path once. telemetrygen sends three traces to the Collector over OTLP. The insecure flag means no TLS in this local demo. The Collector writes span details to its terminal, and tee saves that output to collector-output.txt. Then you grep that file to confirm the spans arrived. Finally, Control-C stops the Collector.
Next steps from the page
From here, the page points you toward real setups. Learn the config file and connect a backend like Jaeger or Prometheus. Compare running the Collector as an agent versus a gateway. Then explore Kubernetes installs, and browse the receivers, processors, and exporters.
- Configuration: connect Jaeger or Prometheus
- Deployment patterns: agent versus gateway
- Install options and component registry
The Collector is a pipeline: receive telemetry, process it, forward it.
The Collector is a pipeline: receive telemetry, process it, forward it. You now have a working local one to experiment with before production.