To understand why distributions exist, we first need to see how many different things a telemetry pipeline might need to do.

The world is full of formats and destinations

Software produces telemetry in many shapes. Some applications speak the OpenTelemetry Protocol, called OTLP. Others use older formats such as Jaeger, Zipkin, or Prometheus. Some write logs into files. Some run inside Kubernetes and need extra labels added automatically. On the other side, telemetry must reach many different destinations: open-source databases, cloud provider services, and commercial observability vendors. Every one of these needs a piece of code that knows how to talk to it.

If one program included every possible piece of code, it would be huge, hard to keep secure, and slow to update. If it included only a few, it would not be useful to most teams. The OpenTelemetry project solved this tension by making the Collector modular and then offering several pre-packaged selections of modules, called distributions.

What goes wrong without a clear choice

Why the project split things in the first place

In the early days, the Collector lived in a single place, and every component, from the engine to the most specialised vendor exporter, was maintained together. As interest grew, hundreds of people wanted to add support for their own favourite system. The central maintainers could not carefully review, test, and support every one of those contributions, and they did not want the heart of the project to be slowed down by them.

The solution was to separate the foundation from the contributions. The foundation, which every user needs, stays small and receives the most careful attention. The contributions, which only some users need, live in their own repository with their own owners. This split lets the project welcome many contributors without lowering the quality bar of the core. The two distributions you see today are the packaged result of that decision.

The short answer, before the long one

The core distribution is a small, carefully maintained build with a minimal set of essential components. The contrib distribution is a large build that adds hundreds of community and vendor components on top. For serious production use, the project itself recommends a third path: building your own custom distribution that contains only what you need. The rest of this guide explains each of these in depth.

A short, friendly refresher on how the Collector is built from parts.

What the Collector is

The OpenTelemetry Collector is a standalone program that receives telemetry, processes it, and exports it. It is vendor neutral, which means it can accept data in many formats and send it to many places. It is configured through a file that lists which components to use and how to connect them.

The five kinds of component

Components are chosen at build time

Here is the idea that explains everything else. The Collector is written in the Go programming language, and Go programs are compiled into a single executable file. The components are compiled into that file. You cannot add a new component to a running Collector by dropping a plug-in file next to it, the way you might add a plug-in to a web browser. The list of available components is fixed when the executable is built.

This design has real benefits. The result is a single file that is easy to copy and run, with no hidden plug-in folders. It also means that the question “which components can I use” is answered by which executable you downloaded, and that is the question distributions answer.

flowchart LR
  M["Manifest: list of chosen components"] --> B["Build step"]
  S["Component source code"] --> B
  B --> X["Single Collector executable"]
  X --> R["Runs with your configuration file"]
        

What is inside an executable

It helps to picture the executable as three layers. At the bottom is the engine, which reads configuration, builds the pipelines, and starts and stops components in the right order. In the middle are the components themselves. At the top, quietly included, are all the third-party libraries that those components need in order to talk to other systems. When you choose a distribution, you are choosing the middle layer, and the top layer comes along with it.

The configuration must match the build

A configuration file can only mention components that exist in the executable you run. If the file names a component that was not compiled in, the Collector stops at startup and complains that it does not know that component type. This is the single most common reason people first discover the difference between distributions.

The word is used in a precise way, and knowing it avoids many confusions.

A working definition

In OpenTelemetry, a distribution is a customised version of an OpenTelemetry component. It is a particular packaging, with a chosen set of parts, sometimes with extra defaults or settings, that someone prepares and releases. The word is used for the Collector, and also for language agents and SDKs. In this guide we focus on Collector distributions.

Importantly, a distribution is not a fork or a separate project. It is built from the same upstream parts, often with the same source code. What differs is the selection, the packaging, and the promises made about support.

Distribution, fork, plug-in, and image: four different ideas

These four words are often mixed up, so it is worth separating them. A distribution is a selection of upstream parts. A fork is a copy of the code that has gone its own way. A plug-in is a part loaded into a running program. An image is a container package that may hold any distribution. The table shows how they differ.

Who can make a distribution

Three questions every distribution answers

Whenever you look at a distribution, ask three questions. Which components does it contain? Who tests and supports it? And how is it delivered to you, as a binary file, a container image, or an operating system package? The differences between core and contrib are best understood as different answers to these three questions.

The core distribution is the small, carefully maintained foundation of the Collector.

What it is

The core distribution is built from the main Collector repository. It includes the Collector’s engine, which handles configuration, pipelines, and lifecycle, plus a deliberately small set of components. It is the reference build that shows what the Collector can do on its own.

What it typically contains

The exact list changes between releases, so treat the following as a guide to the idea rather than a fixed inventory. The core distribution focuses on the essentials: a receiver and exporters for OTLP, the open standard of the project; a handful of general-purpose helpers such as a processor that groups data into batches and a processor that protects against running out of memory; a debugging exporter that prints data for inspection; and a connector that forwards data between pipelines. It also offers a few simple extensions for diagnostics.

A small example: what a core-only pipeline can do

Imagine an application that sends traces in OTLP to a local Collector, and you want the Collector to group the data into batches and forward it to a backend that also accepts OTLP. A core-style build can do this completely. It has the OTLP receiver, the batch processor, a memory limiter, and the OTLP exporter. The pipeline is short, clear, and easy to reason about.

Now imagine that you also want to read logs from files on the machine, add the name of the Kubernetes pod to every trace, and send some data to a cloud provider’s own service. Each of those needs a component that core does not contain. The configuration that describes them will not start on core. This small contrast, one pipeline that fits and one that does not, is the best way to remember what core is for.

Why it is kept small

The small size is deliberate. Every component in core is held to a high standard of testing, documentation, and maintenance by the central maintainers. Keeping the set small makes that promise possible. It also keeps the executable lean, reduces the number of external libraries it depends on, and shrinks the surface that must be watched for security problems.

The contrib distribution is the big workshop trolley: nearly everything the community has built.

What it is

The contrib distribution is built from a second, much larger repository, often called the contributions repository. It includes everything in core plus a very large number of additional components contributed by the community, by vendors, and by cloud providers. The word “contrib” is short for “contributed”.

What it typically contains

The collection spans hundreds of components, and it grows with almost every release. To give a feel for the range without promising an exact list, here are the kinds of things you find in contrib that you do not find in core.

The main families inside contrib

With hundreds of components, it helps to see them in families. The table groups them by purpose, with examples of the kinds of things you will find. Remember that the exact members change from release to release.

Who maintains it

Unlike core, most contrib components are looked after by their individual owners, who are often engineers from the vendor or project the component relates to. A central group coordinates releases and keeps the shared infrastructure healthy, but they do not personally maintain hundreds of vendor-specific parts. Each component lists its owners and its current level of stability, which we explore in a later chapter.

Why people love it

Contrib is the answer to “will it work with my setup”. Almost any configuration copied from a tutorial will start on contrib, because the components it mentions are almost certainly present. That makes it the favourite for learning, experimenting, building prototypes, and trying out ideas quickly.

Now that each distribution has been introduced, let us put them next to each other and compare them on every dimension that matters.

The big picture

The easiest way to hold the difference in your head is to remember that contrib is a superset of core. Everything that core offers is also present in contrib, with the same names and the same settings. The reverse is not true. Contrib adds a large number of components, and with them a larger executable, a wider set of dependencies, and a mix of stability levels.

flowchart TD
  subgraph CT["Contrib distribution"]
    subgraph CR["Core distribution"]
      A["Engine and essential components"]
    end
    B["Hundreds of community and vendor components"]
  end
        

The same configuration on three builds

A concrete scenario makes the differences vivid. Take one realistic configuration that receives OTLP, reads log files, adds cluster labels, samples traces, and exports to two backends. Try it on three builds and watch what happens.

The lesson is that contrib and the custom build behave the same for this configuration, but the custom one carries no unused weight. That is the whole case for building your own, in one table.

The same engine underneath

It is worth stressing that the two distributions share the same engine. The way pipelines are defined, the way configuration is read, the way data is represented internally, and the way components are started and stopped are identical. If you learn to configure one, you can configure the other. The difference is only in which components are available.

Size and why it matters

The contrib executable is many times larger than the core one, because it carries the code and the third-party libraries of all those extra components. Larger images take longer to download, use more storage, and start more slowly. On a single server this hardly matters. On thousands of nodes, or on small edge devices, or in environments where every container image is scanned, it matters a lot.

Behind each distribution is a repository, a group of owners, and a release process. Understanding them explains why things behave as they do.

Where the code lives

flowchart LR
  CORE["Core repository: engine, core components, builder"] --> REL["Releases repository: build recipes and publishing"]
  CONTRIB["Contributions repository: community and vendor components"] --> REL
  CORE --> CONTRIB
  REL --> BIN["Binaries"]
  REL --> IMG["Container images"]
  REL --> PKG["Operating system packages"]
        

How to read a component’s page

Each component has a documentation page, and learning to read it quickly saves hours. At the top, you will find a short description and a table of stability levels by signal. Next come the owners, which tell you who to ask or who to join if you want to help. Then comes the list of settings, with defaults and examples. Finally, many pages list known limitations, which are often the most valuable part. Before you commit to a component, read the stability table, the owners, and the limitations, in that order.

Who looks after what

In the core repository, a central group of maintainers reviews changes and carries responsibility for each component. In the contributions repository, every component has named owners, listed in an ownership file, who review changes to that component and answer questions about it. When owners leave a project and nobody takes over, a component can become unmaintained, and in time it may be removed. This is a normal part of a large community collection, and it is why reading the stability label matters.

Releases move together

The core and contrib distributions are released on a regular, frequent rhythm, and their version numbers move together, so that a given version of contrib corresponds to the same version of core. This pairing is important: the contrib components of a release are built and tested against the matching core engine. Mixing a contrib component from one release with a core engine from another is a recipe for compile errors or strange behaviour.

Version numbers and promises

Many parts of the Collector still carry version numbers beginning with zero, which signals that breaking changes can occur between releases. Some foundational parts have reached a stable one-point-zero line, with stronger promises about compatibility. The practical lesson is the same either way: read the release notes before upgrading, especially for components you depend on, and do not assume that a settings file that worked last month will work unchanged on a new release.

Components can move

As a component matures and becomes broadly important, it can move from contrib into core, and the reverse can happen for parts that are better maintained by a community. When this happens the component’s behaviour usually stays the same, but the distributions that contain it change. A configuration that worked on core-plus-nothing one year may need contrib the next, or the other way around.

Whether a component sits in core or contrib tells you less than its stability level does.

The stability scale

Every component declares a stability level, separately for each kind of signal it handles. The project uses a common scale that describes how much you can rely on the component not to change under you.

Stability is per signal

A single component can be stable for one kind of data and experimental for another. For example, a receiver might be mature for traces yet still early for logs. Always check the level for the specific signal you plan to use. This is easy to miss, because the component’s name is the same in every case.

Feature gates and experimental options

Besides stability levels for whole components, the Collector uses switches called feature gates to control individual behaviours that are still changing. A gate has its own life cycle: it starts off by default while the idea is tested, is then switched on by default when it is judged safe, and finally disappears when the behaviour becomes permanent. If a release note tells you that a gate is changing its default, it means the behaviour of your pipeline may change on upgrade, even if you changed nothing.

This is a further reason to read release notes before upgrading, and to test on a copy of your real configuration. Gates are a gentle way for the project to introduce change, but only if the people running the Collector notice them.

Where to find the label

Each component’s documentation lists its stability level and its owners. The Collector executable itself can also print the list of components it contains, together with their stability levels, through a built-in command. Running that command on your chosen distribution is a quick way to see exactly what you have and how mature each part is.

How a component grows up

Components do not start life at the top of the scale. A typical journey begins when someone proposes a component and builds a first version at the development level. As real users try it, the design settles, bugs are fixed, and the component is promoted to alpha and then beta. Reaching stable requires evidence that the component behaves well in real use, that its settings are unlikely to change, and that it has active owners who will keep it healthy.

Understanding this journey helps you judge risk. A component at an early level is not bad; it is simply young. If you choose to adopt a young component, you accept the job of reading release notes more carefully and testing upgrades more thoroughly.

Why this matters for core versus contrib

Core components tend to be at higher stability levels simply because the central team holds them to a high standard. Contrib contains the full range, from stable and widely used components to experimental ones. This means that the sensible question is not “is it in contrib” but “what is its stability level for my signal”. A beta or stable contrib component may be a better choice than a poorly maintained alternative, and an alpha component should be treated with care wherever it lives.

Core and contrib are not the only choices. The ecosystem offers more prepared selections.

Other official distributions

Besides core and contrib, the project publishes additional distributions aimed at particular needs. Examples include a build focused on Kubernetes, which includes the components commonly needed to collect telemetry from clusters, and a build that includes only the OTLP components for the simplest forwarding jobs. The set of official distributions changes over time, so check the project’s current list before choosing.

Vendor and cloud distributions

Many vendors and cloud providers publish their own Collector distributions. These typically bundle the exporters and extensions relevant to their products, set convenient defaults, and offer support under their own agreements. Some of them track the upstream project closely, while others add custom components. They are a good fit when you have a support relationship with the vendor and want a build that the vendor has tested with its own service.

A checklist for evaluating a vendor distribution

The word “distribution” beyond the Collector

The project also uses the word for language-specific pieces such as agents and SDKs. A language distribution is a customised packaging of the standard SDK with vendor defaults. The ideas in this guide apply there too: ask what it contains, who supports it, and how closely it follows upstream.

The third path, and the one the project recommends for production, is to assemble exactly the Collector you need.

The builder tool

The project provides a tool, called the OpenTelemetry Collector Builder, that creates a custom Collector executable from a short list of components. You write a manifest that names the receivers, processors, exporters, connectors, and extensions you want, together with the versions to use. The tool fetches the code, compiles it, and produces a single executable that contains exactly that selection and nothing more.

flowchart TD
  A["Write a manifest listing the components you need"] --> B["Run the builder tool"]
  B --> C["Builder downloads matching component code"]
  C --> D["Compile one executable"]
  D --> E["Package as container image"]
  E --> F["Scan, test, and deploy"]
        

The steps in plain words

Writing your own component

The builder can include components that you write yourself, which is one of the strongest reasons to build a custom distribution. An organisation might need a receiver for an internal protocol, a processor that applies company-specific rules, or an exporter for an in-house system. By writing a component and listing it in the manifest next to the standard ones, you get a single executable that contains both. You do not have to fork the project, and you can keep up with new upstream releases by changing the versions in the manifest.

Treat your own component with the same care as the official ones: give it an owner, tests, documentation, and a stability label in your own records. A private component that nobody understands is a quiet risk that grows every month.

What you gain

What it costs

A custom build is not free. Someone must own the manifest, run the build pipeline, watch for new releases, and rebuild and roll out on a regular schedule. Teams with no appetite for this work sometimes find that a vendor distribution or a smaller official distribution offers a happy middle ground.

With the options clear, here is a practical way to decide.

Match the choice to the stage of work

A decision flow

flowchart TD
  S["Start"] --> Q1{"Is this only for learning or a quick prototype?"}
  Q1 -->|"Yes"| C1["Use contrib"]
  Q1 -->|"No"| Q2{"Do you only need OTLP in and out?"}
  Q2 -->|"Yes"| C2["Use core or the OTLP-only build"]
  Q2 -->|"No"| Q3{"Do you have a vendor with a supported build?"}
  Q3 -->|"Yes"| C3["Consider the vendor distribution"]
  Q3 -->|"No"| C4["Build a custom distribution"]
        

Comparing total cost of ownership

The cheapest choice on day one is rarely the cheapest choice after a year. Consider the whole cost, including the time of the people involved, not only the cost of downloading an image.

Questions to ask yourself

• Which components do I truly use? Write the list down. If it is short, a custom build is cheap to make.
• How much do I care about size and startup time? Edge and large fleets care a great deal.
• How strict is my security review? Fewer components means less to review.
• Who will maintain a build pipeline? If nobody, prefer an official smaller build or a vendor build.
• Do I need components that are not yet stable? If so, plan for change and test every upgrade.

The Collector often sits in the middle of your network and sees all your telemetry. What you compile into it is a security decision.

Why the Collector deserves care

A Collector usually runs with network access to many applications and to external backends, and it handles data that may contain internal addresses, identifiers, and fragments of user information. It often holds credentials for the backends it sends to. A weakness in the Collector, or in any library compiled into it, is therefore more serious than a weakness in an ordinary helper program.

Every component brings dependencies

Each component is built on third-party libraries: client libraries for cloud services, database drivers, message system clients, and many others. When you compile a component in, you also compile in its libraries. Contrib, with hundreds of components, carries an enormous number of these libraries. Security teams track vulnerabilities by library, so a contrib-based image will appear in scanner reports far more often than a lean custom build, even when you use only a tiny part of it.

Practical protections

Compliance and approvals

In regulated organisations, every piece of software in production may need approval. A distribution containing hundreds of components may be harder to approve than one with a dozen, because reviewers must consider each. A custom build gives you a short, named list to submit for review and a clear way to show that nothing else is present.

Questions a security reviewer will ask

• What exactly is inside this executable? Be ready to supply the component list and the bill of materials.
• Which components touch the network, and where do they connect? Reviewers care most about components that open ports or call external services.
• Where do credentials come from? They should be loaded from secure sources, not stored in plain text.
• How quickly can you patch? Show the build pipeline and the last time you used it.
• What happens if a component is abandoned? Have a plan to replace or maintain it.

How supply chain problems can arrive

The supply chain is everything that your executable is made from, and every link can be attacked. A library that a component depends on may be found to contain a flaw. A malicious package with a name similar to a real one may trick a build into downloading the wrong code. A compromised account may publish a harmful release. A container base image may carry old, vulnerable software.

You cannot remove these risks, but you can reduce them. Fewer components mean fewer libraries and therefore fewer chances for something to go wrong. Pinning exact versions, building in a controlled pipeline, verifying downloads, and storing approved copies in your own registry all make it harder for a surprise to reach production. Records of what you built, kept for each release, let you answer questions quickly when news of a new problem appears.

Least privilege inside the pipeline

Even with a clean build, apply least privilege to the configuration. Give the Collector only the network access and credentials it needs, keep credentials out of configuration files by loading them from secure sources, and limit which components are enabled in each pipeline. A component that is compiled in but not configured does not process data, although it still counts as code that exists in the file.

Choosing a distribution is the first step. Running it well over months and years is the second.

Pin versions deliberately

Always run a specific, named version rather than a floating label such as “latest”. A floating label can change underneath you during a routine restart and bring in breaking changes without warning. Write the version in your deployment files, and update it as a deliberate change that is reviewed, tested, and rolled out.

A safe upgrade routine

Knowing what you are running

Two built-in commands save a great deal of time. One checks that a configuration file is valid for the executable. The other lists every component compiled into the executable together with its stability level. Run both whenever you move to a new version or a new distribution, and keep the component list as part of your documentation so that colleagues can see what the production build contains.

sequenceDiagram
  participant E as Engineer
  participant CI as Build pipeline
  participant R as Registry
  participant C as Collector fleet
  E->>CI: Update manifest to new release
  CI->>CI: Build, list components, validate configuration
  CI->>CI: Scan image and create bill of materials
  CI->>R: Publish pinned image
  E->>C: Roll out to a small share
  C-->>E: Health and metrics look normal
  E->>C: Roll out to the rest
        

When something goes wrong

Most problems after a change of distribution or version fall into a handful of patterns. The table below is a starting point for your own troubleshooting notes.

Resource use and sizing

Contrib and custom builds use the same engine, so for the same pipelines their processing performance is similar. The visible differences are in the size of the executable, the startup time, and the baseline memory used by compiled-in code. When you move from contrib to a custom build, you may see a smaller image, a faster start, and a slightly lower baseline memory use, but you should not expect dramatic differences in throughput unless you also changed the pipelines.

The cost of size at scale

Size seems unimportant until it is multiplied. Suppose a contrib image is several times larger than a lean custom image. On one server, the difference is a few seconds of download. Now suppose you run an agent on each of 2,000 nodes, and every node pulls a fresh image during each rolling update. The extra data transferred, the extra time for the rollout to finish, and the extra storage on each node all multiply by 2,000.

The same multiplication applies to scanning. If every image is scanned, a larger image takes longer to scan and produces a longer report. At the scale of a large organisation, a smaller image saves both machine time and human attention. Measure the sizes in your own registry and do the arithmetic for your fleet. It often turns a vague preference into a clear business case.

Monitoring the Collector itself

Whichever distribution you use, the Collector reports metrics about its own health: how much data it accepts, how much it sends, how many items are refused or dropped, and how full its queues are. Collect and alert on these. After any change of distribution or version, compare them with the previous baseline to detect subtle differences early.

Teams keep rediscovering the same good habits and the same expensive mistakes. Here they are, named.

Patterns worth copying

Anti-patterns to avoid

A practical checklist, grouped by the stage of your journey.

Before you start

• Write down what you need. List the data sources, processing steps, and destinations. This list decides everything else.
• Check each component’s stability. Note the level for the signal you will use.
• Decide who owns the distribution. A build that nobody owns will go stale.

While you build

• Explore on contrib but do not assume production will use it.
• Pin every version of the engine, the components, and the base image.
• Keep the manifest in version control and review it like code.
• Validate the configuration against the real executable in your build pipeline.
• Scan the image and store a bill of materials.
• Run as a non-privileged user on a minimal base image.

After you launch

• Rebuild on a schedule and test every upgrade.
• Watch release notes for deprecations of components you use.
• Monitor the Collector’s own metrics and compare them after every change.
• Review the component list each quarter and remove anything you no longer use.

A vocabulary cheat sheet

The distribution you choose reaches your machines in a few common ways. Each has small traps worth knowing.

Delivery formats

Choosing the image in Kubernetes

Tools that deploy the Collector in Kubernetes are not tied to one distribution. They let you set the image, so you can point them at the official contrib image while experimenting and at your own custom image in production. Some deployment tools choose a default image for convenience, and the default may differ between tools and versions. Always check which image you are really running, and set it explicitly.

flowchart LR
  subgraph NODE["Each node"]
    AG["Agent Collector: small custom build"]
  end
  APPS["Applications"] --> AG
  AG --> GW["Gateway Collector: richer custom build"]
  GW --> BE["Backends"]
  REG[("Private image registry")] -.->|"pinned images"| AG
  REG -.->|"pinned images"| GW
        

Agents and gateways can differ

In many designs, a small Collector runs on every node as an agent, and a larger Collector runs centrally as a gateway. The agent mostly receives data and forwards it, so a very small build is enough. The gateway does the heavier work of enriching, filtering, sampling, and routing, and needs a richer set of components. Building two distributions, each shaped for its role, reduces size and risk on the many nodes while giving the few gateways the tools they need.

Migrating from a contrib image to a custom image

Many teams start on contrib and later want to move. The migration is safer than it sounds, because the configuration language does not change. Follow these steps in order.

Servers without internet access

Some environments, such as secure data centres, cannot reach the public internet at all. In these places, the ability to build a custom distribution in a connected build environment and copy the finished executable or image across is very valuable. You control exactly what enters the secure network, and you can include the bill of materials and scan results as part of the transfer. Contrib’s size makes such transfers heavier, and its hundreds of components make approval harder, so a lean build is especially welcome here.

Windows, Linux, and processor types

Official distributions are published for several operating systems and processor types, and custom builds can target the same ones. When you build your own, decide which platforms you need, such as Linux on both common processor families and perhaps Windows for some servers, and build for each. Test each platform, because behaviour of some components, especially those that read host information, can differ between operating systems.

Private registries and reproducibility

Pulling images directly from a public registry at deploy time makes your production depend on a service you do not control. Copy the exact images you approved into your own registry, and deploy from there. This also lets you keep the scan reports and bills of materials next to the images they describe.

How the ideas show up in practice. These situations are illustrative, built from patterns that teams commonly describe.

A year in the life of a platform team

Questions to ask before you adopt

• Which components do we actually use today? Start from facts, not from wishes.
• Who will own the build pipeline? A named owner prevents drift.
• How will we hear about security fixes? Decide how releases and advisories reach the team.
• How fast can we roll out a patch? Practise it before you need it.
• Do any components we use have low stability? Plan for their changes.

You do not need to build a custom distribution on day one. Move from easy to careful, one proven step at a time.

Six stages

How mature is your setup?

Short, direct answers to the questions people ask most often.

Core is a small build with the engine and a minimal set of essential components, maintained centrally. Contrib is a large build that includes everything in core plus hundreds of community and vendor components, each maintained by its own owners and carrying its own stability level.

Yes. Everything in core is also in contrib, with the same names and settings. Contrib adds many more components on top.

Not as a rule. Many contrib components are mature and widely used. The difference is in who maintains them and how consistently they are held to the same level. Check each component’s stability label rather than judging by the repository.

Because the configuration mentions a component that is not compiled into the executable you are running. Switch to a distribution that contains it, or build a custom distribution that adds it.

No. Components are compiled in when the executable is built. To add one, you need a different distribution or a custom build.

The project advises against running it as is in production, because of its size, large dependency set, and varied component quality. It is excellent for learning and prototyping. For production, build a custom distribution with only the components you need.

Use the OpenTelemetry Collector Builder. You write a manifest that lists the components and their versions, run the tool, and it produces an executable containing just those components. Keep the manifest in version control and rebuild on a schedule.

They are released on a regular rhythm with matching version numbers, because the contrib components are built against the corresponding core engine. Keep all components in a build on the same release line.

For the same pipelines, throughput is similar, because both use the same engine. A custom build is smaller, starts faster, and carries less baseline code, but it will not process data dramatically faster by itself.

The Collector has a built-in command that lists the compiled-in components along with their stability levels. Run it against the exact executable you plan to deploy.

Beta means the component is mostly settled and generally suitable for production with testing, but changes are still possible. Read release notes before upgrading and test every change.

Yes. As components mature or ownership changes, they can move. The behaviour usually stays the same, but the distributions that contain it change. Release notes announce such moves.

It depends on your needs. A vendor build gives you tested integration and support from a company you pay. A custom build gives you control and a smaller surface. Check how closely a vendor build follows upstream and whether it adds private components.

List the components your working configuration uses, write them into a manifest at one pinned release, build the executable, and validate your configuration against it. That single exercise often shows how much smaller and simpler production can be.

No. The configuration language is the same. The only difference is which components you can name in it.

Regularly, on a rhythm your team can sustain, such as monthly, with a faster path for security fixes. Small frequent upgrades are easier than rare large ones, because the gap to upstream stays small.

Yes. They are separate executables and can run on the same machine, for example on different ports, or in different containers. Some teams run contrib in a sandbox and a lean build in production.

You do not write Go code to use standard components, because the builder handles the compilation from your manifest. You do need a build environment that can run the builder, and you need to write code only if you want to create your own components.

Your existing build keeps working, because it contains the code you compiled. The problem comes at your next upgrade, when the component may no longer be available at the new version. Read release notes in advance so that you can plan a replacement.

Yes. Besides the official specialised builds, such as one aimed at Kubernetes, a custom distribution is the most flexible middle path. You take the exact components you need from both core and contrib and nothing else.

Because tutorials usually demonstrate several components, and contrib is the only official build that is certain to contain all of them. It is the right choice for learning, but the same tutorials rarely suggest that it is the best choice for running a production service.

Choose a recent release that all the components you need support, read its notes, and test it with your real configuration. Then use that same version for every component in the manifest and move them together when you upgrade.

The OpenTelemetry Collector is built from components that are compiled together into one executable, and a distribution is a particular selection of those components. The core distribution is small and carefully maintained, with a minimal set of essentials. The contrib distribution is a large superset that adds hundreds of community and vendor components, each with its own owners and stability level. Both share the same engine and the same configuration language, so the difference is which components you can use, how big and how exposed the build is, and who stands behind each part. For learning and prototyping, contrib is wonderfully convenient. For production, the project recommends a custom distribution built from exactly the components you use, or a vendor distribution you trust. Whatever you choose, pin versions, check stability, validate configuration against the real executable, scan what you ship, and rebuild on a rhythm.