OpenTelemetry Collector: architecture, configuration, and operation

The OpenTelemetry Collector receives telemetry, processes it, and sends it to one or more destinations. Its usual data path is receiver → processors → exporters, with separate pipelines for traces, metrics, and logs. This moves transport and processing policy out of individual applications and into an independently managed service.

A Collector can buffer, retry, redact, filter, and route data when the relevant components are configured. Those capabilities are not all enabled automatically, and they do not provide unlimited durability. The distribution, pipeline configuration, and deployment topology determine what the instance can actually do.

Why put a Collector between applications and the backend?

Using OTLP gives applications a common export protocol. A Collector can then change destinations without changing every application's instrumentation. Backend-specific data models, queries, authentication, and supported features still need migration work; a common transport reduces coupling rather than eliminating every form of vendor dependence.

A Collector can also consolidate collection for several sources if its distribution includes the required receivers. Before replacing existing Agents, compare signal coverage, parsing, resource detection, operational controls, and failure behavior.

Processing near the source can remove unwanted fields before data leaves the environment. Apply redaction and filtering before the first untrusted destination, and verify every export branch. Trace sampling can reduce downstream volume but loses evidence according to the policy. See the sampling guide; the sensitive-data guide is currently in Chinese.

Queues and retries help absorb temporary backend failures. Persistent queues require a compatible storage extension and explicit configuration. They still depend on storage capacity, process lifecycle, retry limits, and receiver acknowledgment behavior. Monitor the Collector itself so a healthy application is not mistaken for a healthy telemetry path.

Understand what the configuration enables

The main component roles are:

Defining a receiver, processor, or exporter does not activate it. Reference it in an appropriate service.pipelines entry. Enable extensions through service.extensions. A component must also support the signal in that pipeline.

This trace-only example targets a Collector Contrib 0.162.0 distribution containing the listed components. Save it as collector.yaml:

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

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 256
    spike_limit_mib: 64
  attributes/environment:
    actions:
      - key: deployment.environment.name
        value: production
        action: insert
  batch:
    timeout: 5s
    send_batch_size: 8192

exporters:
  debug:
    verbosity: detailed

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [memory_limiter, attributes/environment, batch]
      exporters: [debug]

The receiver binds to loopback for a local demonstration. Applications in another container or host cannot reach it through their own loopback address; choose a reachable listener and deliberate network protections for that topology.

The attributes processor inserts an attribute on spans when the key is absent. It does not set a Resource attribute. Prefer setting deployment.environment.name on the application's Resource when it describes the service deployment; use a resource processor if the Collector must add it at that level. insert also preserves an existing value, which differs from overwriting it.

Place memory_limiter early to apply backpressure before additional processing. Its limits are illustrative and must fit the process/container memory budget. It can refuse data under pressure, but it is not a guarantee against an out-of-memory kill. Batching after transformations and sampling usually avoids doing export work on data that will be dropped; exact ordering depends on component requirements.

Validate locally, then connect the real destination

Choose the distribution and pinned version from the official installation options, which include container images, operating-system packages, and Kubernetes deployment guidance. Match the installed binary to the components required by the configuration.

Use the executable belonging to the selected distribution:

otelcol-contrib components
otelcol-contrib validate --config=collector.yaml
otelcol-contrib --config=collector.yaml

components reports what the binary includes. validate checks that the configuration is valid for that binary; it does not prove network reachability or backend acceptance. Send a known trace while the process is running and inspect the debug export output. Debug output may contain sensitive attributes, so use controlled data and remove verbose output when it is no longer needed.

The old logging exporter has been replaced by debug. Use the documented validate subcommand rather than assuming a --dry-run flag exists. See Collector configuration for the current command and configuration model.

For Guance, first enable the actual DataKit OpenTelemetry receiver. Obtain its full HTTP trace-ingestion URL, including its configured port and path. Then replace the example's exporter and pipeline exporter list:

exporters:
  otlp_http/datakit:
    traces_endpoint: ${env:DATAKIT_TRACES_URL}

# In service.pipelines.traces:
# exporters: [otlp_http/datakit]

Set DATAKIT_TRACES_URL through the deployment's configuration or secret-management mechanism. Add authentication only according to that receiver's documented requirements. Do not assume DataKit's port is 4318 or invent an authorization header. For a gRPC destination, use the matching otlp_grpc exporter, host/port, and TLS settings instead of an HTTP route.

The 0.162.0 component names shown here differ from older examples using otlp or otlphttp exporters. Check aliases and migration guidance for the actual binary. A receiver named otlp is a separate component from those exporters.

Choose an Agent or Gateway deployment

An Agent runs near the source, such as a host process, Kubernetes DaemonSet, or sidecar. It can collect local files and host signals and perform processing before forwarding. A Gateway is a separately managed tier receiving data from applications or Agents and centralizing routing, policy, or export.

A two-tier design is useful when local collection and shared processing have different responsibilities. It also introduces another hop, queue, and failure boundary. Start with the topology the workload needs and test capacity rather than adding tiers by habit. For Kubernetes configuration, see the Collector Helm guide.

Multiple Gateway replicas improve availability only when routing, capacity, and stateful processing are designed accordingly. Tail sampling needs trace-aware routing; a generic round-robin load balancer can scatter one trace across instances. An Agent on each node is distributed placement, not redundant protection for data buffered on a failed node.

Know which components your distribution includes

Common receivers cover OTLP, Jaeger, Zipkin, Prometheus scraping, file logs, and host metrics. Common processors include batch, memory_limiter, attributes, transform, filter, and tail_sampling. Exporters include OTLP, Prometheus, Kafka, and debug output. Names and availability vary by release—for example, newer releases use names such as file_log where older examples use filelog.

“Core” does not mean every bundled component has the same stability level, and “Contrib” does not mean every component ever contributed is included. Inspect the release manifest, component documentation, signal-specific stability, and binary inventory. A custom Collector can include only selected components, at the cost of owning its build and update process.

Common questions

Can DataKit replace an existing Collector?

For an application that only needs an appropriate OTLP receiving path, direct export to DataKit may be sufficient. Compare every existing receiver, processor, queue, routing rule, and signal before removing a Collector. Receiving one trace does not prove that metrics, logs, transformations, or outage handling have migrated correctly.

Can the Collector collect logs from files?

Yes, with a distribution containing the relevant file-log receiver and a logs pipeline. Test multiline records, rotation, checkpointing, permissions, and parse failures. An OTLP receiver alone does not tail application files.

How should we assess reliability?

Observe accepted, refused, sent, and failed telemetry, exporter queue pressure, memory, and process restarts. Test a destination outage and recovery within the intended queue capacity. Persistent buffering is one mechanism, not a substitute for that failure test.

The Collector monitoring guide, OTTL guide, OTLP explanation, and OpenTelemetry introduction are currently in Chinese. Browse the guides index for related tutorials.