What are OpenTelemetry distros?

When you get started with OpenTelemetry, you may notice something: there are multiple distros. Most appear to be vendor-specific. What the heck are these shenanigans?

The short, short version: Most of the configuration in OpenTelemetry revolves around which backend you are going to send data to. Distros package up the set of plugins and configuration options needed to connect OpenTelemetry to a particular back end.

Distros are not forks. They are downstream releases of the exact same OpenTelemetryOpenTelemetry components available upstream. The only difference between using a downstream distro and using OpenTelemetry directly is the amount of configuration you may need to do.

What is a distro?

There are two types of distros: client distros and Collector distros.

Client distros are a set of configuration options and plugins for the OpenTelemetry SDK, which connect OpenTelemetry to a particular backend. They are basically a convenience wrapper around the SDK constructor.

Collector distros, on the other hand, are compiled binaries which contain a version of the Collector along with a set of recommended plugins.

Distros primarily perform two helpful functions.

Distros install necessary plugins

A backend may require a specific exporter and sampler combination in order to function correctly. For example, the AWS distro installs the XRay exporter, which is not present by default.

Distros set defaults and fill in required configuration options

The default endpoint when exporting data is often different between backends. Backends may also require certain options to be set in order to function correctly.

For example, Lightstep uses OTLP, OpenTelemetry’s native protocol. But we require the lightstep-access-token header to be added to the OTLP connection. To make this easier, the Lightstep Launchers install the OTLP exporter and check to ensure that the Lightstep header is present.

Why should we use distros?

Hopefully, the above explanation makes a case for the primary reason organizations make distros: simplicity.

New users don’t want to be presented with a large pile of options and configurations. And it would be bad news to forget to install the correct sampling plugin if a backend requires one. Providing a simple wrapper around SDK construction makes setup more of a one-liner.

Over the summer, the OpenTelemetry project will be working to make this type of preconfiguration easier, especially for the default OpenTelemetry setup: propagating W3C Trace-ContextW3C Trace-Context and Baggage headers while exporting OTLP data to a collector via Protobuf over HTTP. As more backends adopt those default settings natively, there may be less need for client distros going forwards.

There are also pragmatic reasons for an organization to create a distro. Some companies have security and support guarantees they would like to provide to their customers. Since OpenTelemetry has a plugin architecture, distros allow companies a way to express which plugins and versions of OpenTelemetry their support covers.

What isn’t a distro?

Putting my OpenTelemetry co-founder hat on for a second. I’d like to express several anti-patterns that I never wish to see. If you encounter any of the following in the wild, please DM me on Twitter or Slack.

I haven’t pushed for official language on this subject yet. That said, in my opinion, the following are not distros.

Forks are never distros. A distro is a packaging of plugins which work with an official release of the OpenTelemetry SDK or the OpenTelemetry CollectorOpenTelemetry Collector. If the SDK or Collector is forked in order to add or change functionality, rather than adding functionality via a plugin, it isn’t a distro. Distros are only packaging of upstream components. Any changes should be committed upstream, and then consumed via the next release.

To be clear, open source is open source, and OpenTelemetry uses the Apache v2.0 license. So, fork away if you like. It is even possible to provide an alternative implementation! No forking required. You can actually create any implementation you like, from scratch, and connect it to the OpenTelemetry API. But that would not be a distro. Simply call your alternative implementation something else, and do not attempt to confuse users by implying that this new project is officially part of OpenTelemetry.

Likewise, a version of the Collector which includes proprietary plugins is not a distro. That kind of mystery meat will never be part of OpenTelemetry.

However, there is one package which should never, ever be forked or extended: the OpenTelemetry API. The API is special.

All instrumentation is written against the API. This is an ecosystem containing millions of lines of code. This is where standards come in. We work hard on the API to ensure that instrumentation written in different libraries will always compose well together, and will always work with future versions of the API. We plan to support the v1.0 API for many years.

A common, stable API is how OpenTelemetry achieves vendor-neutrality, allowing users to switch providers and implementations whenever they choose to. This stability also allows open source libraries to include instrumentation natively: library instrumentation will always work correctly in every application the library is added to, without creating dependency conflicts or broken traces.

If anyone ever proposes that they have “extended” the OpenTelemetry API – that is an attempt at vendor lock-in, not to mention a terrible idea. Don’t. use. it.

Try a distro today

Ok, rant mode off. As of this writing, everything that calls itself a distro is legit. If you are giving OpenTelemetry a spin, and your provider is offering you a distro, I recommend taking them up on the offer: it’s simply convenient.

The other option I recommend is to run OpenTelemetry with a Collector and use the default settings I recommended above (OTLP exporter, W3C Trace-Context trace propagator). As much as possible, move all of your configuration from the client to the Collector. That way, operators can control configuration and data processing via their Collector deployment, and never have to disturb the running applications.

Hope that helps; enjoy your observability! If you haven’t tried it yet, get a free Lightstep accountfree Lightstep account and see what we can do. OpenTelemetry makes it easy!

Interested in joining our team? See our open positions herehere.