Before reading the map, it helps to know what the building does.

Applications and servers produce telemetry, which is the general name for the information a running system emits about itself so people can understand its behaviour. OpenTelemetry groups telemetry into signals. Traces follow one request through many services. Metrics are numbers measured over time, such as requests per second. Logs are timestamped records of events. Each of these is called a signal.

The OpenTelemetry Collector is a standalone program that receives telemetry, optionally changes it, and sends it onward. It is vendor-neutral, which means it is not tied to any one monitoring product. It can accept data in many formats, and it can deliver data to many destinations at once. Teams run it so that their applications can send data to one nearby place, while all the careful work of filtering, batching, retrying and routing happens in a single, central, configurable program rather than being repeated inside every application.

Why does it need a configuration file at all?

The Collector program ships without any built-in opinion about what you want. It does not know which formats you will send, which services should receive your data, or what cleaning your data needs. All of that is described in a configuration file, a plain text document that you hand to the Collector when it starts. The Collector reads the file, builds the described components, connects them, and begins working.

Because the file is the single source of truth, changing how telemetry flows is usually a matter of editing the file and restarting, or reloading, the Collector. No application code needs to change. That separation is one of the main reasons teams adopt the Collector in the first place.

flowchart LR
  A["Applications and hosts"] --> B["Collector"]
  C["Configuration file"] --> B
  B --> D["Backend 1"]
  B --> E["Backend 2"]
  B --> F["Storage or archive"]
        

Every Collector configuration is built from the same six building blocks.

A Collector configuration file is organised into a small number of top-level sections. These are the headings at the very left edge of the file, and each one introduces a family of components. Five of them describe the components themselves. The sixth, called service, decides which of those components are switched on and how they are wired together. Learn these six names and you can orient yourself in any file.

flowchart TD
  R["receivers: define the doors"]
  P["processors: define the workers"]
  E["exporters: define the trucks"]
  C["connectors: define the bridges"]
  X["extensions: define the services"]
  S["service: switch on and connect"]
  R --> S
  P --> S
  E --> S
  C --> S
  X --> S
        

Define first, enable second

The most important idea in the whole file is the split between defining a component and enabling it. The five definition sections are like a catalogue: they describe what is available and how each item is set up. The service section is like an order form: it picks which catalogue items you actually want and in which arrangement. A component that is defined but never mentioned in the service section does nothing at all.

The configuration is written in a gentle, human-friendly format, and a few simple rules cover almost everything.

Collector configuration files are written in YAML, a text format designed to be easy for people to read. You do not need to be an expert to read a Collector file. You only need to recognise four ideas, which are described here in words so you can spot them quickly.

Empty definitions are allowed

Many components work perfectly with their default settings. In that case, you simply write the component’s name followed by nothing, or by an empty pair of braces. This is called using the defaults, and it is very common for small, simple components. You only add settings when you want to change something from the default.

A receiver is the part of the configuration that decides how telemetry enters.

A receiver accepts telemetry and hands it to the pipeline. Receivers come in two broad styles. A push-based receiver waits and listens: your application sends data to an address, and the receiver accepts it. A pull-based receiver goes out and collects: at regular intervals it contacts something, such as a database or a metrics endpoint, and reads data from it.

What a receiver definition contains

Each receiver entry has a name that identifies its type, and underneath it, the settings that tune it. For a listening receiver, the settings usually include the address and port to listen on, which protocols are accepted, and optional security settings. For a collecting receiver, settings usually include the target to contact and how often to do so. Whatever the type, the entry is only a description until a pipeline uses it.

One receiver can serve several signals

Some receivers can bring in more than one kind of signal. An OTLP receiver, for example, can accept traces, metrics and logs through the same door. A single definition can then be used in a traces pipeline, a metrics pipeline and a logs pipeline. Other receivers are limited to one signal, such as a metrics-only receiver. A pipeline can only use a receiver that supports that pipeline’s signal.

Processors are where the Collector earns its keep, by cleaning and shaping data between the door and the truck.

A processor sits between receivers and exporters. It can modify the data, drop parts of it, add information to it, group it into larger bundles, or protect the Collector from overload. Processors are entirely optional, but nearly every real configuration uses at least a few, because raw telemetry is rarely perfect for delivery.

Typical jobs of a processor

Order is part of the meaning

When a pipeline lists several processors, the Collector applies them in exactly the order they are listed. The first processor in the list sees the data first, and its output feeds the second, and so on. Reversing two processors can change the result, or even undermine a safety feature.

An exporter takes finished telemetry and delivers it to its destination.

An exporter sends data out of the Collector. The destination might be a commercial monitoring service, an open-source backend, a message queue, a file on disk, the terminal screen, or even another Collector. As with receivers, each exporter entry has a type and a set of settings. For a network exporter, the settings usually include the destination address, security details such as certificates or tokens, and rules for timeouts, retries and queuing.

Resilience settings you will often see

Networks fail and backends have bad days. Many exporters therefore include settings that make delivery more dependable. These are worth knowing by name, because they appear again and again in real files.

Exporters you will meet often

A connector is a clever component that plays two roles at once.

A connector joins two pipelines together. In the first pipeline, it behaves like an exporter: data flows into it as the pipeline’s final step. In the second pipeline, it behaves like a receiver: it is where data enters. Whatever the connector emits on the receiving side may be the same data it was given, or something newly created from that data.

What connectors make possible

flowchart LR
  A["Traces pipeline: receiver, processors"] --> B["Connector (acts as exporter)"]
  B --> C["Connector (acts as receiver)"]
  C --> D["Metrics pipeline: processors, exporter"]
        

A rule about signals

A connector has an input signal type on its exporting side and an output signal type on its receiving side. These must match the pipelines it joins. A connector that turns traces into metrics must be placed as an exporter in a traces pipeline and as a receiver in a metrics pipeline. If the signal types do not match, the configuration is not valid.

Not everything the Collector does involves moving telemetry. Extensions cover the rest.

An extension adds a capability to the Collector that is not part of the receive, process and export flow. Extensions never sit inside a pipeline. They run alongside, offering services to the Collector itself or to its other components.

Extensions need to be listed, too

Just like other components, an extension is only a description until it is enabled. Extensions are enabled by listing them in the extensions list inside the service section. Interestingly, this list is separate from the pipelines, because extensions do not take part in the flow of data.

The service section is the most important part of the file, because it decides what really runs.

The service section has three parts. Each answers a different question, and together they turn a collection of definitions into a working system.

flowchart TD
  S["service"] --> X["extensions: list of enabled extensions"]
  S --> P["pipelines: traces, metrics, logs"]
  S --> T["telemetry: Collector's own logs and metrics"]
  P --> P1["receivers list"]
  P --> P2["processors list (ordered)"]
  P --> P3["exporters list"]
        

Pipelines: the heart of the file

A pipeline is a complete route for one type of signal. It names which receivers feed it, which processors run on the data in what order, and which exporters deliver the result. Each pipeline belongs to exactly one signal type, so there are traces pipelines, metrics pipelines and logs pipelines. You may define as many pipelines as you need, including more than one for the same signal.

Telemetry: watching the Collector itself

The Collector is also software that can go wrong, so it produces its own telemetry. The telemetry part of the service section controls how much the Collector says about itself: how detailed its own logs are, and how its own metrics are exposed. This is separate from the data flowing through pipelines. It is a way to answer questions such as how many items were received, how many were refused, and whether exports are failing.

The same kind of component can appear more than once, as long as each copy has its own name.

Every component in the file is identified by a label built from two pieces: its type and an optional name, joined by a slash. The type says what kind of component it is, such as an OTLP receiver or a batch processor. The name is a label you choose, which makes this particular copy distinct from other copies of the same type.

Why you would want more than one

Configuring a component and activating it are two different acts.

We have mentioned this idea several times, because it is the number one source of confusion. The Collector’s documentation states it plainly: configuring a receiver does not enable it. Receivers, processors, exporters and connectors are enabled only by being named inside a pipeline. Extensions are enabled by being listed in the service section’s extensions list. Anything defined but never referenced is simply ignored.

A pipeline can take data from many doors and deliver it to many trucks.

Pipelines are more flexible than they first appear. They are not limited to one receiver and one exporter. Understanding how data behaves when several components are listed lets you design setups that are both simple and powerful.

Fan-in: several receivers, one pipeline

When a pipeline lists more than one receiver, data from all of them is merged into the same stream and then passes through the same processors. This is called fan-in. It is handy when the same kind of data arrives in several formats, for example traces from older applications in one format and from newer applications in another, but you want them cleaned and delivered in the same way.

Fan-out: one pipeline, several exporters

When a pipeline lists more than one exporter, the processed data is sent to every one of them. This is called fan-out. It lets you deliver the same data to a production backend and an archive, or to two different vendors during a migration. Each exporter has its own queue and retry behaviour, so a slow destination does not need to hold up the others in principle, although a very slow or failing one can still add pressure on shared resources.

flowchart LR
  R1["Receiver A"] --> P["Processors in order"]
  R2["Receiver B"] --> P
  P --> E1["Exporter 1"]
  P --> E2["Exporter 2"]
  P --> E3["Exporter 3"]
        

One pipeline per signal type

A pipeline handles exactly one signal type. If you want traces, metrics and logs to travel through the Collector, you define at least one pipeline for each. Each uses receivers, processors and exporters that support that signal. A component such as the OTLP receiver may appear in all three, but a component that only understands metrics can only appear in metrics pipelines.

Naming pipelines

Pipelines follow the same type-and-name idea as components. A pipeline is identified by its signal type, optionally followed by a slash and a name. Having two traces pipelines, one called default and one called sensitive, for example, lets you give different treatments to different data while staying inside the rules.

A good configuration file avoids hard-coding values that change between machines or must stay secret.

Real configurations need values that differ between environments: an address that is different in testing and production, an access token that must never be written in a file that people share. The Collector lets you put placeholders in the file and fill them in when the Collector starts.

Environment variable expansion

An environment variable is a named value supplied by the operating system or the container platform to a running program. In a Collector file, you refer to one with a dollar sign, curly braces, and the word env followed by a colon and the variable’s name. At start-up, the Collector replaces the placeholder with the real value. You can also give a fallback value, which is used when the variable is not set. If you need a literal dollar sign in the file, you write it twice.

Providers: other places to fetch values

The Collector fetches values through components called providers. The environment variable provider is the one most people meet first. Others can read the contents of a file or fetch a value from a web address. Each provider is selected by the word that comes before the colon in the placeholder. This keeps secrets in dedicated places, such as mounted files from a secrets manager, instead of in the configuration itself.

Splitting configuration across several files

As configurations grow, a single huge file becomes hard to read. The Collector accepts more than one configuration file at start-up, and merges them into one. You provide each file with its own configuration option on the command line. Each file may be partial, but the combined result must form a complete, valid configuration.

Catch mistakes on your own machine instead of in the middle of an incident.

The Collector includes commands that check a configuration without running it. These are a great safety net, because they catch spelling errors, missing components, signal mismatches and other structural problems before anything is deployed.

What validation typically catches

Let us practise on a typical, small configuration, described in words so you can learn the reading routine.

Imagine a modest configuration for a service that sends traces, metrics and logs to one backend. In the file, you would see the following, in roughly this order.

flowchart LR
  A["OTLP receiver"] --> B["memory limiter"]
  B --> C["resource processor"]
  C --> D["batch processor"]
  D --> E["OTLP exporter to backend"]
  D --> F["debug exporter (temporary)"]
        

A reading routine you can reuse

The file layout stays the same, but its contents change depending on where the Collector runs.

Teams commonly run the Collector in two roles. As an agent, it runs close to the applications, often on the same machine or alongside the application in the same group of containers. As a gateway, it runs as a central service that receives data from many agents and applications, and forwards it to the backends. Both roles use exactly the same six sections. What differs is which components are chosen.

flowchart LR
  A["App + agent Collector"] --> G["Gateway Collector"]
  B["App + agent Collector"] --> G
  C["App + agent Collector"] --> G
  G --> D["Backend 1"]
  G --> E["Backend 2"]
        

A Collector sits on the path of everything your systems report, so it deserves careful settings.

The configuration file is not only about functionality. It is also where you decide how safe and dependable the Collector will be. A few themes appear in nearly every careful setup.

Almost everyone makes these mistakes once. Knowing them in advance saves hours.

A short list to keep beside you whenever you write or review a configuration.

Quick answers to the questions beginners ask most often.

Six: receivers, processors, exporters, connectors, extensions and service. The first five define components, and the service section enables them and connects them into pipelines.

The service section is required, and a useful configuration needs at least one receiver and one exporter in a pipeline. Processors, connectors and extensions are optional.

Configuring a component does not enable it. Check that the receiver is listed in at least one pipeline inside the service section, and that the pipeline’s signal type is supported by that receiver.

Yes. Processors run in the order they are listed in the pipeline. A common arrangement is memory protection first, then enrichment or cleaning, and batching last.

Not in the same way. Several receivers merge into one stream, and data is sent to every listed exporter. Order matters for processors, not for these two lists.

It is an identifier that lets you define several instances of the same component type. The type says what it is, and the name tells copies apart.

An exporter sends data out of the Collector. A connector sends data out of one pipeline and into another, acting as an exporter on one side and a receiver on the other.

No. Extensions are enabled through the extensions list in the service section, because they provide side services rather than handling telemetry data.

Use placeholders that read from environment variables or files supplied by your platform’s secrets mechanism, and keep the real values out of version control.

Yes. Provide each file as its own configuration option. The files are merged, and the combined result must be a complete, valid configuration.

Use the Collector’s validate command to check structure and references, and the print-config command to see the final merged result. Then test with sample data, because a valid file can still be wrong.

The structure is identical, but the contents differ. Agents usually collect locally and forward, while gateways apply central policy such as filtering and redaction before delivering to backends.

A Collector configuration file is a plan with six parts. Receivers bring data in, processors change it, exporters send it out, connectors join pipelines together, and extensions add side services. The service section is where the plan becomes real: it lists the enabled extensions, defines the pipelines that route each signal from receivers through ordered processors to exporters, and configures the Collector’s own telemetry. Components can be defined several times using a type-and-name identifier, but only the ones referenced in the service section are ever created. With placeholders for environment-specific values, validation before deployment, careful processor order, and sensible security and memory settings, the same simple structure scales from a laptop experiment to a production gateway.