Binary releases and package management

[svrnm]

Is your feature request related to a problem?

When I want to use OpenTelemetry C++ I currently have 2 options to do so:

1. I build the code myself from the sources
2. I use an "unofficial", maybe not stable package if it is available for my environment (see below)

For most users only option (1) is available and it's a huge entry barrier for people to get started with OpenTelemtry C++. A good example on the level of complexity is the Getting Started, which asks a lot of steps that need to be accomplished to get an app up and running.

Describe the solution you'd like

We discussed this during one of the last SIG meetings and this is a follow up issue on that: to make it easier for end-users to get started with OpenTelemetry C++ there are two options to address that:

1. Provide binary releases for major platforms (OS + arch), similar to the releases the collector provides (see https://github.com/open-telemetry/opentelemetry-collector-releases/releases)
2. Add support for common package managers (rpm, deb, ebuild, apk, homebrew), or if available already, collaborate with the maintainers of those packages to provide first-level support.

Both options are not mutually exclusive, indeed by providing binary releases some publications for package managers are easier as well (except they require reproducable builds).

I suggest the following steps:

• Create a github workflow that builds & releases binaries for major platforms, similar to https://github.com/open-telemetry/opentelemetry-collector-releases/blob/main/.github/workflows/release-core.yaml
• Review different package managers if they allow (a) the use of binary releases and (b) automatic updates

Describe alternatives you've considered

Do nothing.

Additional context

Addressing this issue does not require deep understanding of C++ but knowledge around releasing and publishing open source packages. Therefore I suggest this issue gets tagged with "help wanted".

Existing packages from 3rd parties:

• vcpkg: https://vcpkg.link/ports/opentelemetry-cpp
• alpine (apk): https://gitlab.alpinelinux.org/alpine/aports/-/tree/master/testing/opentelemetry-cpp?ref_type=heads
• homebrew: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/o/opentelemetry-cpp.rb
• ebuild: https://cgit.gentoo.org/repo/gentoo.git/tree/dev-cpp/opentelemetry-cpp

[marcalff]

Thanks for putting this together.

There is also:

• https://repology.org/project/opentelemetry-cpp/versions
• https://github.com/bazelbuild/bazel-central-registry/tree/main/modules/opentelemetry-cpp
• https://github.com/conan-io/conan-center-index/tree/master/recipes/opentelemetry-cpp
• https://www.freshports.org/devel/opentelemetry-cpp
• https://gitlab.com/liguros/liguros-repo/-/tree/stable/dev-cpp/opentelemetry-cpp
• https://github.com/NixOS/nixpkgs/blob/nixos-unstable/pkgs/by-name/op/opentelemetry-cpp/package.nix
• https://github.com/fd00/yacp/tree/master/opentelemetry-cpp

In summary, the landscape is a wild zoo of unmaintained and obsolete ports, which increases confusion, and raises the barrier of entry even more with outdated (and most likely broken) packages.

[svrnm]

Thanks for completing that list @marcalff

I am wondering, are there other C++ based projects we can learn from? How are some of them managing that? Or how do they make it easy for package providers to stay up-to-date and provide consistent solutions?

[svrnm]

So, I thought about this a little bit more, I think the easiest thing to begin with are the binary builds. I am wondering if the existing CI pipeline (or benchmark?) could be the foundation for that?

[malkia]

I fear the build matrix would be rather large, and have to be somewhat opinionated.

For example OPENTELEMETRY_ABI_VERSION_NO can take two versions, then static / dynamic, then what components are added by default (and their dependencies).

Lastly how these dependencies are pulled, for example when building .dll/.so/.dylib - are these dependencies also .dll/.so/.dylib, or are they bundled and hidden in the dynamic(shared) library itself.

Would I get debug builds, and debug builds with different .dll names so I can place both .dll in the same "bin" folder (typical gamedev setup would be like this for us).

I feel best of the buck would be dynamic library distribution, as precompiled .lib files go only so far.

Oh, and also what flavor of C++ runtime and ABI version there too (I'm glad MSVC is now compatible from vs2015 to vs2022, and even clang-cl supports it, but no idea how Linux/OSX is)

[lalitb]

• The API in otel-cpp is header-only and is the most used component (as used for library instrumentation), so binary package is not required. We could distribute a source package (for most common distros) containing only the API headers if needed.
• The SDK and exporters, however, require binary packages. I agree that the matrix of build configurations, architectures, compilers, platforms, and distributions is too extensive to support fully.

[svrnm]

The API in otel-cpp is header-only and is the most used component (as used for library instrumentation), so binary package is not required. We could distribute a source package (for most common distros) containing only the API headers if needed.

If this would be possible, I think that would already be a great starting point. The API is especially relevant for projects that want to provide "native instrumentation", so having an easy way to take dependency would be great!

The SDK and exporters, however, require binary packages. I agree that the matrix of build configurations, architectures, compilers, platforms, and distributions is too extensive to support fully.

If we want to do that, we might consider to start as small as possible, i.e. what are the one or two build configurations/architectures/etc. with the most value?

I think we should start as small as possible and then start from there. I also heard from last SIG meeting that maybe making sure that vcpkg/conan are up-to-date would already be a great improvement?

[malkia]

A binary with (minimum) OTLP/grpc support would make most sense to me.

[svrnm]

Sounds to me like a starting point could be the following:

• Work towards "official"[^1] support for conan and vcpkg
• Provide a binary release with a minimum amount of features (otlp/grpc support, no other exporters, strip all features with "too many dependencies", etc.). Platform-wise maybe starting with linux+glibc on x86_64 might be good to begin with?

[^1]: Providing official support is a multi-step effort with "support" meaning very different things. To begin with this would just mean that OTel Community Members make sure that updates are supplied to conan&vcpkg, this could be still a "best effort"/"alpha" support without any guarantees and with the potential to be withdrawn again.

[marcalff]

Random collection of notes, which have an impact on packaging:

• the situation with all the ABI flavors needs to be clarified, we can't mix several flavors together
• releasing binary packages for each operating system implies having access to runners
• releasing binary packages timely, in case of changes in dependencies, requires a lot of resources, and is a great responsibility
• to make a package, dependencies must also provide packages to build upon (for example, prometheus-cpp)
• an alternate possibility is to not provide binary packages, but provide the packages specs, so that anyone can build a binary package from specs (on their own hardware, which increases the os coverage), and at their own pace (which resolves the issue of re releasing a package when a dependency changes)

---

Tentative list of packages:

• opentelemetry-cpp-api
• opentelemetry-cpp-sdk
• opentelemetry-cpp-exporter-otlp-http-trace
• opentelemetry-cpp-exporter-otlp-grpc-trace
• opentelemetry-cpp-exporter-otlp-file-trace
• opentelemetry-cpp-exporter-otlp-http-metric
• opentelemetry-cpp-exporter-otlp-grpc-metric
• opentelemetry-cpp-exporter-otlp-file-metric
• opentelemetry-cpp-exporter-otlp-http-log
• opentelemetry-cpp-exporter-otlp-grpc-log
• opentelemetry-cpp-exporter-otlp-file-log
• opentelemetry-cpp-exporter-ostream-trace
• opentelemetry-cpp-exporter-ostream-metric
• opentelemetry-cpp-exporter-ostream-log
• opentelemetry-cpp-exporter-prometheus
• opentelemetry-cpp-exporter-zipkin

Packages can also provide -debug and -release options

For implementing third party exporters, we also need the -dev packages with header files.

The overall scope of packaging gets big very fast, this is neither trivial nor minor.

[svrnm]

* releasing binary packages for each operating system implies having access to runners

Via CNCF we have access to a variety of runners, this is doable.

* releasing binary packages timely, in case of changes in dependencies, requires a lot of resources, and is a great responsibility

This is a very valid concern!

* to make a package, dependencies must also provide packages to build upon (for example, prometheus-cpp)

What list of the packages below hast the least amount of dependencies, or which packages have dependencies that require mainly dependencies one can expect endusers have readily available?

* an alternate possibility is to not provide binary packages, but provide the packages specs, so that anyone can build a binary package from specs (on their own hardware, which increases the os coverage), and at their own pace (which resolves the issue of re releasing a package when a dependency changes)

Can you elaborate? This might be a valuable piece to provide

Tentative list of packages:

* opentelemetry-cpp-api

* opentelemetry-cpp-sdk

* opentelemetry-cpp-exporter-otlp-http-trace

* opentelemetry-cpp-exporter-otlp-grpc-trace

* opentelemetry-cpp-exporter-otlp-file-trace

* opentelemetry-cpp-exporter-otlp-http-metric

* opentelemetry-cpp-exporter-otlp-grpc-metric

* opentelemetry-cpp-exporter-otlp-file-metric

* opentelemetry-cpp-exporter-otlp-http-log

* opentelemetry-cpp-exporter-otlp-grpc-log

* opentelemetry-cpp-exporter-otlp-file-log

* opentelemetry-cpp-exporter-ostream-trace

* opentelemetry-cpp-exporter-ostream-metric

* opentelemetry-cpp-exporter-ostream-log

* opentelemetry-cpp-exporter-prometheus

* opentelemetry-cpp-exporter-zipkin

Packages can also provide -debug and -release options

For implementing third party exporters, we also need the -dev packages with header files.

Doe we really need all of them, maybe starting with a subset like -api, -sdk, exporter-otlp-http-trace, -exporter-ostream-trace?

The overall scope of packaging gets big very fast, this is neither trivial nor minor.

Yes, it absolutely is, so thanks for taking a look anyway. I think not doing it now is still a valid outcome but in the future this issue can be used as reference to either continue this discussion or to validate if things have changed and can be addressed