OpenTelemetry Collector Contrib: where collector components live before they ship

The repository that holds what the core repository would not take

opentelemetry-collector-contrib exists for one reason: to hold OpenTelemetry Collector components that are not suitable for the core repository. Most of what lives here never reaches a core distribution. A handful are exceptions, and the two named are Jaeger and Prometheus, whose source sits here even though they ship as part of the core distribution. Everything else is contrib only, which means the binary you run decides whether a component exists for you at all, not the documentation. There is a third path as well: build your own distribution with the OpenTelemetry Collector Builder, picking components from the core repository, from contrib, and if you need them, from third-party or internal repositories. The repository steers you toward that builder as well as toward the two official distributions, so the practical question is never whether contrib is good, but which set of components your pipeline actually needs.

go.mod says it does not build the official binary

Start with the module file, because it disclaims the job people assume it has. It declares module github.com/open-telemetry/opentelemetry-collector-contrib and go 1.26.0, then states in a comment that it is NOT used to build any official binary, that the builder manifests for official binaries live in opentelemetry-collector-releases, and that the contrib distribution manifest sits under distributions/otelcol-contrib in that other repository. So this go.mod is a coordination file rather than a build entry point, and the file that actually decides what goes into a release is a manifest you will not find here. Locally, the root Makefile includes Makefile.Common and exposes the knobs a first run needs:

RUN_CONFIG?=local/config.yaml
CMD?=
OTEL_VERSION=main
OTEL_STABLE_VERSION=main

COMP_REL_PATH=cmd/otelcontribcol/components.go
MOD_NAME=github.com/open-telemetry/opentelemetry-collector-contrib

RUN_CONFIG points at local/config.yaml by default, so a config that does not exist there is the first thing that stops a local run. OTEL_VERSION and OTEL_STABLE_VERSION both default to main, and VERSION is derived from git describe against HEAD using a v[0-9]* match.

Stability is decided per signal, so one component carries three maturities

Component maturity here is not one label. Each component declares a stability level for every signal it supports, and the combination is the number that matters: a component can be Stable for traces while being Alpha for metrics and Development for logs. The definitions are inherited from the core collector repository, so the words keep their upstream meaning, but the per-signal split is what surprises people who read Stable as a statement about the whole component. Feature gates add a second axis. Some features stay behind a gate until they join the main code path for that component, and the gates have their own lifecycle stages, so a gate and the feature it hides can sit at different points in their lives. The consequence for a config you ship is concrete: a Development signal inside an otherwise Stable component can change shape, and the key that reaches it can arrive without the notice a stable interface would carry.

Maintainers can downgrade a component at any time, and support is per component

Support is not repository wide. Each component is backed either by the community of contrib maintainers, the GitHub group @open-telemetry/collector-contrib-maintainers, or by specific vendors, and the individual component files are where that split is spelled out. The maintainer group is explicitly allowed to downgrade specific components whenever they are judged unmaintained, or whenever they pose a risk to the repository or to the binary distribution. That is the clause to read twice before you depend on something: a component you rely on today can drop a level, and a component you adopt tomorrow may have dropped already. The README also makes the point about who actually answers your issue. Although the maintainers are ultimately responsible for what is hosted here, day to day support comes from individual contributors, usually the code owner for that component, which means a bug against a vendor-backed component goes to that vendor's owner with the maintainers behind them.

Every component is a separate Go module, so the build globs by first letter

The receiver, processor, exporter, extension and connector trees are not one package. They are separate Go modules, and the root Makefile discovers them by searching for go.mod before it delegates per module. The receiver set is even split into four alphabetical groups, and the third one carries a comment saying Prometheus is special and gets its own section:

RECEIVER_MODS_0 := $(shell find ./receiver/[a-f]* $(FIND_MOD_ARGS) -exec $(TO_MOD_DIR) )
RECEIVER_MODS_1 := $(shell find ./receiver/[g-o]* $(FIND_MOD_ARGS) -exec $(TO_MOD_DIR) )
RECEIVER_MODS_2 := $(shell find ./receiver/[p]* $(FIND_MOD_ARGS) -exec $(TO_MOD_DIR) ) # Prometheus is special and gets its own section.
RECEIVER_MODS_3 := $(shell find ./receiver/[q-z]* $(FIND_MOD_ARGS) -exec $(TO_MOD_DIR) )
RECEIVER_MODS := $(RECEIVER_MODS_0) $(RECEIVER_MODS_1) $(RECEIVER_MODS_2) $(RECEIVER_MODS_3)

Scope selection runs through GROUP, which defaults to all. A GROUP containing a slash, such as receiver/hostmetrics or a space-separated list of module paths, invokes the per-module delegation targets directly, while any other value maps to the for-<name>-target rule. Around that sit the exclusion filters EX_COMPONENTS, EX_INTERNAL, EX_PKG and EX_CMD, which drop the receiver, processor, exporter, extension, connector, internal, pkg and cmd trees from the wider sweeps. The practical result is a repository where one build target only ever covers part of the tree.

Four retracted versions, and only one of them explains itself

The module file also carries a retract block, which is the nearest thing here to an upgrade warning:

retract (
	v0.76.2
	v0.76.1
	v0.65.0
	v0.37.0 // Contains dependencies on v0.36.0 components, which should have been updated to v0.37.0.
)

Three entries are bare version numbers. The fourth explains itself: v0.37.0 was retracted because it carried dependencies on v0.36.0 components that should have been updated to v0.37.0. That is a component version mismatch rather than a defect in the collector itself, and it is the sort of skew a mixed-version build produces. Treat the list as the signal that those are not the versions to pin. The releases add a second versioning wrinkle: v0.164.1 shipped on 2026-10-26 under the pair of tags v1.3.1/v0.164.1, v0.164.0 shipped the same day as v1.3.0/v0.164.0, and v0.163.0 shipped on 2026-10-14 as v1.2.0/v0.163.0. The last push to main landed on 2026-11-02.

The root of the tree shows how much machinery surrounds the components

Beyond the component directories, the top level shows how much sits around them. There are three Makefiles: Makefile, Makefile.Common which the root one includes, and Makefile.Weaver. Tooling configuration sits in .golangci.yml, .codecov.yml, .checkapi.yaml and two files whose names end in gen, .mdatagen.yaml and .schemagen.yaml, alongside renovate.json. Release plumbing has a directory of its own in .chloggen/, and CHANGELOG.md sits next to a separate CHANGELOG-API.md, so interface changes are tracked apart from everything else. There are also AGENTS.md and CLAUDE.md for coding agents, issue-triaging.md for triage policy, NOTICE beside LICENSE, and the data files versions.yaml and distributions.yaml. The directory worth opening first is examples, because it holds runnable setups rather than component source: examples/kubernetes/, examples/couchbase/, examples/nomad/, examples/logline-filtering/, examples/fault-tolerant-logs-collection/ and examples/secure-tracing/. Those six directories say more about working configurations than any component index would.

No install command, no per-component level list, no upgrade notes

Two things a reader will not find here. There is no install command and no binary download, because the core and contrib distributions are published from opentelemetry-collector-releases and this repository explicitly disclaims building them. There is no single stability list in the README text: the levels live with the components, and the README sends you to the individual files for support information. The people lists are more complete than that, and they are worth reading as a signal about who carries what: thirteen maintainers spread across Grafana Labs, Elastic, Splunk, Snowflake, Google, DataDog and Dynatrace, twelve approvers from Grafana Labs, Elastic, Splunk, Google, Coralogix, Microsoft, Dash0, Honeycomb and Five9, fourteen triagers, and a triager group that says outright it is seeking contributors.

Editorial conclusion

Choose this repository when you need a receiver, processor, exporter, extension or connector that the core distribution does not carry, or when you want to assemble your own binary with the Collector Builder. Do not treat it as an install source, because the released core and contrib distributions are built elsewhere and this module file says so. Before you pin a component, read its own file for the support level and the support owner, and check whether the version you want sits in the retract list.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes