How to Set Up the OpenTelemetry Collector

The OpenTelemetry Collector is a vendor-neutral service that receives telemetry, optionally processes it, and exports it to one or more destinations. Its configuration model is easiest to understand as a pipeline: receiver → processor → exporter.

This tutorial creates a deliberately small local trace pipeline with OTLP input and a debug exporter. It validates the YAML before startup and sends deterministic test traces so you can prove that the Collector receives and processes data.

It is a learning and verification setup—not a production architecture.

Last verified: September 10, 2026. The current official Collector release is 0.160.0, released September 2, 2026. The official quick start also uses 0.160.0 and explicitly says its local demo is not production-ready.

What You'll Accomplish

You will:

1. choose the current core Collector distribution;
2. create an explicit OTLP trace pipeline;
3. validate the configuration before startup;
4. run the Collector locally with OTLP ports bound to localhost;
5. send deterministic traces using the official telemetrygen tool;
6. verify the Collector receives and exports the spans; and
7. understand what must change before a production deployment.

Prerequisites

You need:

• Docker or a compatible container runtime;
• Go if you want to use the official telemetrygen command from the quick start;
• a shell;
• local ports 4317 and/or 4318 available;
• basic YAML familiarity.

The official quick start also uses Go to install telemetrygen. If you already have another OTLP-capable test client, you can use that instead.

Quick Answer

Create a collector.yaml with an OTLP receiver, a batch processor, a debug exporter, and a traces pipeline that references all three. Validate it with the Collector's validate command, then run otel/opentelemetry-collector:0.160.0 while mounting the config and binding OTLP ports to 127.0.0.1. Install the official telemetrygen utility and send several traces to the local Collector. If the Collector output shows the generated spans, the receive/process/export path works. Do not expose OTLP receivers publicly or use the debug exporter as a production backend.

Step 1: Understand the Pipeline Before Writing YAML

Collector configuration defines components, but defining a component does not automatically enable it.

A trace pipeline can contain:

• receiver — accepts telemetry, such as OTLP;
• processor — transforms/batches/filters data;
• exporter — sends data to a destination;
• service pipeline — connects those components.

A common configuration mistake is defining an exporter or receiver but forgetting to reference it in service.pipelines.

For this tutorial the data path is:

OTLP receiver → batch processor → debug exporter

The debug exporter is useful because it makes successful processing visible without requiring an external observability backend.

Step 2: Create a Minimal Collector Configuration

Create collector.yaml:

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

processors:
  batch:

exporters:
  debug:
    verbosity: normal

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

The YAML uses current Collector terminology. OpenTelemetry's configuration documentation notes that the old logging exporter name was replaced by debug in modern releases.

Why bind 0.0.0.0 inside the container?

Inside a container, the Collector must listen on the container interface for Docker's port mapping to reach it.

We will restrict exposure at the host layer by publishing only to 127.0.0.1.

That distinction matters:

• 0.0.0.0 inside the container lets Docker forward traffic;
• 127.0.0.1:4317:4317 on the host prevents remote clients from reaching that port through the host's normal external interfaces.

Production receiver exposure requires a separate security design.

Step 3: Validate the Configuration

The current Collector documentation provides a validate subcommand.

Run validation with the same Collector version you plan to execute:

docker run --rm \
  -v "$PWD/collector.yaml:/etc/otelcol/config.yaml:ro" \
  otel/opentelemetry-collector:0.160.0 \
  validate --config=/etc/otelcol/config.yaml

If validation fails, fix the YAML before starting the service.

Typical errors include:

• misspelled component type;
• invalid indentation;
• exporter defined but not available in the distribution;
• pipeline referencing a component that does not exist.

You can also inspect available components with the Collector's components command. This is valuable when moving between the core and contrib distributions because they do not contain identical component sets.

Step 4: Run the Collector

Start the core Collector:

docker run --rm \
  --name otelcol-local \
  -p 127.0.0.1:4317:4317 \
  -p 127.0.0.1:4318:4318 \
  -v "$PWD/collector.yaml:/etc/otelcol/config.yaml:ro" \
  otel/opentelemetry-collector:0.160.0 \
  --config=/etc/otelcol/config.yaml

Keep this terminal open.

You should see startup messages showing the configured service and pipelines.

If Docker reports that 4317 or 4318 is already in use, another local service may already own the port. Find the process/container instead of changing ports randomly and forgetting to update the client.

Step 5: Install telemetrygen

The official Collector quick start uses telemetrygen from the OpenTelemetry Collector Contrib repository.

If GOBIN is not set:

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

Then install:

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

For highly reproducible CI/labs, pinning the generator to a reviewed version can be preferable. The official quick start currently uses @latest, so this article preserves that upstream testing pattern while pinning the Collector itself to the verified release.

Step 6: Send Deterministic Test Traces

In another terminal:

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

The command uses the default local OTLP/gRPC endpoint and sends three traces without TLS.

--otlp-insecure is appropriate only because this test is local and the port is bound to localhost.

Do not carry an insecure local example into a remote production deployment.

Step 7: Verify Collector Output

Return to the Collector terminal.

The debug exporter should print trace/span information. Look for:

• trace IDs;
• span IDs;
• span names;
• timestamps;
• status;
• resource attributes.

The exact formatting can change between versions. The required proof is that the generated telemetry entered the Collector and reached the exporter.

If telemetrygen reports success but the Collector prints no spans, verify the endpoint/protocol and ensure the trace pipeline references the OTLP receiver and debug exporter.

Step 8: Know the Difference Between Core and Contrib

OpenTelemetry publishes multiple Collector distributions, including:

• otelcol / core;
• otelcol-contrib;
• Kubernetes-focused distributions.

A configuration that works with contrib can fail with core if it references a component not included in core.

Before copying a config from a blog:

otelcol components

or the equivalent command inside the selected image to confirm the component exists.

Do not choose contrib automatically just because it contains more components. A smaller distribution can reduce unused surface area when core provides everything required.

Verify the Setup

The setup is complete when:

• collector.yaml validates successfully;
• the Collector starts without component errors;
• OTLP ports are bound only as intended;
• telemetrygen sends traces successfully;
• the debug exporter shows the generated spans;
• the pipeline clearly identifies receiver, processor, and exporter.

That proves the local pipeline works. It does not prove production readiness.

Common Problems and Fixes

Problem: unknown type or unavailable component

Cause: the selected Collector distribution does not include that component.

Fix: run components and check the component registry. Choose the correct distribution or remove the unsupported component.

Problem: telemetrygen cannot connect

Cause: wrong port/protocol, Collector not running, Docker port mapping missing, or another process owns the endpoint.

Fix: confirm the Collector listener, host mapping, and whether the client uses gRPC 4317 or HTTP 4318.

Problem: Collector starts but prints no spans

Cause: receiver defined but not referenced in the traces pipeline, client sends to another endpoint, or exporter is missing from the pipeline.

Fix: inspect service.pipelines.traces.

Problem: validation succeeds but startup fails

Cause: syntactically valid config can still encounter runtime problems such as port conflicts, file permissions, DNS, TLS, or exporter connectivity.

Fix: read startup logs and distinguish config-schema errors from runtime/environment failures.

Problem: remote clients cannot reach the Collector

Cause: this tutorial intentionally binds host ports to localhost.

Fix: do not remove that protection blindly. For remote collection, design network exposure, TLS, authentication, and firewall rules before changing bindings.

Best Practices

Validate config before rollout

Run validate in CI or deployment checks so malformed configuration does not reach production.

Pin Collector releases

OpenTelemetry Collector releases move quickly. Pin a reviewed version and upgrade deliberately.

Minimize exposed receivers

Bind locally when clients are local. Remote receiver exposure should use network controls plus TLS/authentication where appropriate.

Use batching

The batch processor is a practical baseline for exported telemetry. Production pipelines may also need memory limiting, retries/queues, or backend-specific settings.

Monitor the Collector itself

A production Collector is infrastructure. Monitor its health, dropped telemetry, exporter failures, queue pressure, and resource usage.

Separate demo exporters from production destinations

The debug exporter is for visibility and troubleshooting, not long-term storage.

When This Setup Makes Sense

This setup is appropriate when learning Collector fundamentals, validating a client, or reproducing a telemetry pipeline locally.

For production, choose an agent/gateway deployment pattern, a resilient exporter, authentication/TLS, resource controls, and scaling based on expected traffic.

FAQ

What is the difference between a receiver and exporter?

A receiver accepts telemetry into the Collector. An exporter sends processed telemetry out to a backend or another Collector.

Should I use the core or contrib Collector?

Use the distribution containing the components you actually need. Verify with components rather than assuming every online configuration works in every distribution.

Which Collector version was used here?

Version 0.160.0, the latest official release listed on September 10, 2026.

Is this configuration production-ready?

No. The official quick start itself says its local setup is not production-ready, and this tutorial preserves that boundary.

Conclusion

The best way to understand the Collector is to make a small pipeline observable. Define OTLP input, batch processing, and a debug exporter; validate the YAML; send deterministic traces; and prove the spans reach the exporter.

Only after that should you add a real backend, remote exposure, authentication, scaling, and resilience.

References

1. OpenTelemetry Documentation — "Quick start" — https://opentelemetry.io/docs/collector/quick-start/ — accessed September 10, 2026; last modified August 27, 2026.
2. OpenTelemetry Documentation — "Configuration" — https://opentelemetry.io/docs/collector/configuration/ — accessed September 10, 2026.
3. OpenTelemetry Documentation — "Install the Collector" — https://opentelemetry.io/docs/collector/install/ — accessed September 10, 2026.
4. OpenTelemetry Collector Releases — "v0.160.0" — https://github.com/open-telemetry/opentelemetry-collector-releases/releases/tag/v0.160.0 — accessed September 10, 2026.