# opentelemetry-collector-contrib: the component library behind most Collector deployments

> The contrib repository is not a binary you install so much as a catalogue of receivers, processors, exporters, extensions and connectors that sit outside the Collector core. Here is how the pieces fit, how to run the contrib distribution in Docker, and where the support model gets thin.

**open-telemetry/opentelemetry-collector-contrib** — Contrib repository for the OpenTelemetry Collector

- Repository: https://github.com/open-telemetry/opentelemetry-collector-contrib
- Website: https://opentelemetry.io
- Stars: 4,953 · Forks: 3,942
- Language: Go
- License: Apache-2.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/open-telemetry-opentelemetry-collector-contrib

## What opentelemetry-collector-contrib actually is

The README opens with a boundary statement: this is a repository for OpenTelemetry Collector components that are not suitable for the core repository of the collector. That single sentence answers the most common confusion. The contrib repository is not a fork of the Collector and not a competing implementation. It is the place where components live until they are judged core material, or permanently, if they never are.

The repository layout reflects that. Top-level directories are receiver/, processor/, exporter/, extension/, connector/, scraper/, pkg/, internal/ and cmd/, each holding many Go modules rather than one. The root go.mod carries an explicit warning that it is not used to build any official binary, and points at the opentelemetry-collector-releases repository for the builder manifests used for official binaries. So a user who clones this repository and runs go build at the root has misunderstood the packaging. The unit of consumption is a distribution, not the repository.

Who is this for? Two groups. Operators who want a Collector that speaks to a system the core components do not cover. And vendors or platform teams who assemble their own distribution from a chosen subset of components. The README states that users are encouraged to build custom distributions with the OpenTelemetry Collector Builder, pulling components from core, contrib, and possibly third-party or internal repositories.

## Stability levels are per signal, not per component

The most important operational detail in the README is easy to skim past. Each component has its own support levels, and for each signal a component supports there is a stability level. The README gives the concrete example directly: a component can be Stable for traces, Alpha for metrics and Development for logs. Stability definitions follow those in the core collector repository.

That granularity has consequences for how you write configuration. A pipeline that handles traces and metrics through the same receiver is not operating at one maturity level. If you are running that receiver in production for traces, the trace half may be settled while the metrics half is still Alpha and free to change shape between releases. The README does not offer a per-component compatibility guarantee, so the honest reading is that Alpha and Development signals should be treated as moving targets.

The README also describes gated features. Some functionality is hidden behind feature gates before it becomes part of the component's main code path, and the README notes that the gates themselves may be at different lifecycle stages than the component. This is a second axis of instability: a component can be Stable while a specific behaviour inside it is still behind a gate that is off by default. Neither the README nor the repository root tells you which gates exist for which component. That information lives in the individual component README files, which the root README points to rather than reproduces.

## Installing the contrib distribution with Docker

The root README does not contain install steps. It links to the Getting Started page at opentelemetry.io/docs/collector/getting-started/ and states that the official core and contrib distributions are published from the opentelemetry-collector-releases repository, where the contrib distribution lives under distributions/otelcol-contrib. The related searches show people looking for the contrib Docker image, so the practical path is the prebuilt distribution rather than a source build.

A Collector needs a configuration file before it will do anything useful. The examples directory in this repository is the best starting point because each subdirectory is a working scenario rather than an abstract snippet. The available examples are couchbase, fault-tolerant-logs-collection, kubernetes, logline-filtering, nomad and secure-tracing. The kubernetes example is the one most readers will want, since it pairs with the Helm chart that also appears in the search data.

The repository Makefile sets RUN_CONFIG to local/config.yaml, which is the configuration file the local run target reads. That is the file you point the Collector at when you run it from a checkout. The Makefile also defines a CMD variable that is empty by default, and a GROUP variable defaulting to all, which selects which module group the per-module targets act on. None of these are runtime flags for the Collector binary itself; they are make targets for working inside the repository. For a container, the configuration is mounted into the image at the path the distribution expects, and the examples directory is where you copy a working file from before editing it. If you only need the prebuilt binary, the README's Getting Started link is the documented entry point rather than any command in this repository.

## The support model is the real limitation

The README devotes a whole section to support, and it is blunt. Each component is supported either by the community of Collector Contrib maintainers, as defined by the GitHub group @open-telemetry/collector-contrib-maintainers, or by specific vendors, with details in the individual component README files. Then comes the sentence that matters most for anyone planning a long-lived deployment: the maintainers may at any time downgrade specific components if they are deemed unmaintained or if they pose a risk to the repository or the binary distribution.

Downgrade is not defined further in the root README, and no rollback or deprecation timeline is documented there. What the README does say is that although the maintainers are ultimately responsible for the components hosted here, actual support will likely be provided by individual contributors, typically a code owner for the specific component. In practice that means the quality of your experience depends on which component you picked, not on the repository as a whole. A component with an attentive code owner behaves differently from one whose owner has moved on.

The wrong-tool case follows from this. If your requirement is a single, well-defined pipeline that the core repository already covers, contrib adds surface area for no benefit. If you need a component whose stability level is Development, contrib is not the component's fault, but you are the one absorbing the churn. And if your organisation needs a contractual support commitment, the README's community-support framing is not that; vendor-supported components exist here, but the README directs you to the individual component README to find out which.

## Contrib versus core, and the builder in between

The natural alternative is the core repository, open-telemetry/opentelemetry-collector. The difference is not a matter of quality but of scope and packaging. Core holds the components considered suitable for it; contrib holds everything else. The README notes that some contrib components, such as the Jaeger and Prometheus components, are part of the core distribution anyway, while most components here ship only in the contrib distribution.

That overlap is the reason the two distributions are not cleanly separable in practice. Choosing core means choosing a smaller binary and a narrower component set, with the trade-off that anything outside it requires you to build your own.

Which is the third option, and the one the README explicitly encourages: the OpenTelemetry Collector Builder, at cmd/builder in the core repository. Instead of shipping every contrib component in one binary, you write a manifest listing the components you use and build a Collector containing only those. The difference from the contrib distribution is binary size and attack surface rather than behaviour, since the component code is the same. It also gives you a place to pin versions, which the prebuilt distribution does not do for you. The repository supports this workflow directly: the Makefile defines a COMP_REL_PATH pointing at cmd/otelcontribcol/components.go, which is the generated component list for the contrib collector, and a distributions.yaml sits at the repository root alongside it.

## Release cadence, licensing and what an upgrade costs

Releases are frequent. The listed versions are v0.159.0 on 2026-08-17, v0.158.0 on 2026-08-04 and v0.157.0 on 2026-07-21, which is roughly a two-week interval. The last push to the default branch was on 2026-08-17. The version numbering stays below 1.0, and the root go.mod carries retract directives for v0.76.2, v0.76.1, v0.65.0 and v0.37.0, with a comment explaining that v0.37.0 depended on v0.36.0 components. Retractions are part of this project's normal history, not an anomaly.

For an operator, a two-week cadence means upgrades are cheap to perform and easy to defer. The cost is not the upgrade itself but the audit: because stability is per signal, you need to know which of your pipelines touch Alpha or Development signals before you move a version forward. The repository has a CHANGELOG.md at the root and a .chloggen/ directory, which is the changelog fragment tooling contributors use, so the per-release notes are the place to check for breaking changes to the components you actually run.

Licensing is Apache-2.0, stated in the repository metadata and present as a LICENSE file at the root, with a NOTICE file beside it. Apache-2.0 permits commercial use and modification and includes an explicit patent grant. It also requires that you preserve the licence and notice files when you redistribute, which matters if you build a custom distribution with the builder and ship it internally or to customers. That is a description of the licence text, not legal advice; if redistribution is part of your plan, have your own counsel read the NOTICE file.

## Conclusion

Adopt opentelemetry-collector-contrib if you need a specific receiver, processor or exporter that the core repository does not carry, and you accept the per-component stability levels that the README describes. Do not adopt it expecting uniform support: the README states that maintainers may downgrade components deemed unmaintained, and that actual support usually comes from an individual code owner. Before committing, check the stability level of the exact component you plan to depend on, and decide whether you want the prebuilt otelcol-contrib distribution or a custom build with the OpenTelemetry Collector Builder using only the components you need.

## FAQ

### What is opentelemetry-collector-contrib?

It is the repository for OpenTelemetry Collector components that are not suitable for the core collector repository. It holds receivers, processors, exporters, extensions and connectors, each as its own Go module with its own support and stability levels.

### What is an OpenTelemetry collector?

The README treats the Collector as the process that runs components: it links to the Getting Started page for setup and to the core repository for stability definitions. The official core and contrib distributions are published from the opentelemetry-collector-releases repository.

### Is there an open source OpenTelemetry collector available?

Yes. This repository is Apache-2.0 licensed, with a LICENSE and NOTICE file at the root, and the official core and contrib distributions are published from the opentelemetry-collector-releases repository.

### How do I install opentelemetry collector contrib?

The root README does not document installation and points to the Getting Started page instead. The practical route is the otelcol-contrib distribution published from opentelemetry-collector-releases, configured through a file such as the local/config.yaml that the repository Makefile names.

### What is the difference between an OpenTelemetry exporter and a collector?

In this repository an exporter is a component type, alongside receiver, processor, extension and connector, each in its own top-level directory. The Collector is the process that runs a configured set of those components inside a pipeline.

### How do I use opentelemetry-collector-contrib?

Either run the prebuilt contrib distribution with a configuration file, or build a custom distribution with the OpenTelemetry Collector Builder listing only the components you need. The README encourages the custom-build route and the examples directory holds working scenarios such as kubernetes and secure-tracing.

## Sources

- [Official documentation](https://opentelemetry.io)
- [Official README](https://github.com/open-telemetry/opentelemetry-collector-contrib#readme)
- [Project repository](https://github.com/open-telemetry/opentelemetry-collector-contrib)
- [Release notes](https://github.com/open-telemetry/opentelemetry-collector-contrib/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/open-telemetry-opentelemetry-collector-contrib