Building opentelemetry-cpp

CMake and Bazel are the official build systems for opentelemetry-cpp.

Dependencies

You can link OpenTelemetry C++ SDK with libraries provided in dependencies.md (complete list of libraries with versions used in our CI can be found here).

Build instructions using CMake

Prerequisites for CMake build

A supported platform (e.g. Windows, macOS or Linux). Refer to Platforms Supported for more information.
A compatible C++ compiler supporting at least C++14. Major compilers are supported. Refer to Supported Compilers for more information.
Git for fetching opentelemetry-cpp source code from repository. To install Git, consult the Set up Git guide on GitHub.
CMake for building opentelemetry-cpp API, SDK with their unittests. The minimum CMake version is 3.14. CMake 3.15+ is recommended on Windows due to known CI test failures with 3.14. To install CMake, consult the Installing CMake guide.
GoogleTest framework to build and run the unittests. Refer to third_party_release for version of GoogleTest used in CI. To install GoogleTest, consult the GoogleTest Build Instructions.
Google Benchmark framework to build and run benchmark tests. Refer to third_party_release for version of Benchmark used in CI. To install Benchmark, consult the GoogleBenchmark Build Instructions.
Apart from above core requirements, the Exporters and Propagators have their build dependencies.

Building dependencies for the OTLP exporters

The opentelemetry-cpp OTLP exporters depend on Protobuf and gRPC (in the case of the otlp grpc exporters). Protobuf (since version 3.22.0) and gRPC depend on Abseil. For cmake builds, it is best practice to build and install Abseil , Protobuf, and gPRC as independent packages - configuring cmake for Protobuf and gRPC to build against the installed packages instead of using their submodule option.

If building and installing Protobuf and gRPC manually with cmake the recommended approach is:

Choose the desired tag version of grpc. Find the compatible versions of abseil and protobuf by inspecting the submodules of grpc at that tag.
Build and install the required version of abseil
Build and install the required version of protobuf
- Set the cmake option of Protobuf to build against the installed package of Abseil (protobuf_ABSL_PROVIDER=package)
Build and install the required version of grpc
- Set the cmake option of grpc to build against the installed packages of Abseil and Protobuf (cmake options - gRPC_ABSL_PROVIDER=package and gRPC_PROTOBUF_PROVIDER=package)

Building as standalone CMake Project

Getting the opentelemetry-cpp source with its submodules:

# Change to the directory where you want to create the code repository
$ cd ~
$ mkdir source && cd source && git clone --recurse-submodules https://github.com/open-telemetry/opentelemetry-cpp
Cloning into 'opentelemetry-cpp'...
...
Resolving deltas: 100% (3225/3225), done.
$

Navigate to the repository cloned above, and create the CMake build configuration.
```
$ cd opentelemetry-cpp
$ mkdir build && cd build && cmake ..
-- The C compiler identification is GNU 9.3.0
-- The CXX compiler identification is GNU 9.3.0
...
-- Configuring done
-- Generating done
-- Build files have been written to: /home/<user>/source/opentelemetry-cpp/build
$
```
Some of the available cmake build variables we can use during cmake configuration:
- -DCMAKE_POSITION_INDEPENDENT_CODE=ON : Please note that with default configuration, the code is compiled without -fpic option, so it is not suitable for inclusion in shared libraries. To enable the code for inclusion in shared libraries, this variable is used.
- -DBUILD_SHARED_LIBS=ON : To build shared libraries for the targets. Please refer to note below for Windows DLL support.
- -DWITH_OTLP_GRPC=ON : To enable building OTLP GRPC exporter.
- -DWITH_OTLP_HTTP=ON : To enable building OTLP HTTP exporter.
- -DWITH_PROMETHEUS=ON : To enable building prometheus exporter.
- -DOPENTELEMETRY_INSTALL=ON: To install otel-cpp library needed for external code linking.

Once the build configuration is created, build the CMake targets - this includes building SDKs and unittests for API and SDK. Note that since API is header only library, no separate build is triggered for it.

$ cmake --build . --target all
Scanning dependencies of target timestamp_test
[  0%] Building CXX object api/test/core/CMakeFiles/timestamp_test.dir/timestamp_test.cc.o
[  1%] Linking CXX executable timestamp_test
...
Scanning dependencies of target w3c_tracecontext_test
[ 99%] Building CXX object ext/test/w3c_tracecontext_test/CMakeFiles/w3c_tracecontext_test.dir/main.cc.o
[100%] Linking CXX executable w3c_tracecontext_test
[100%] Built target w3c_tracecontext_test
$

Once CMake tests are built, run them with ctest command

$ ctest
Test project /tmp/opentelemetry-cpp/build
     Start   1: trace.SystemTimestampTest.Construction
...
     Start 380: ext.http.urlparser.UrlParserTests.BasicTests
...
100% tests passed, 0 tests failed out of 380
$

Optionally install the header files for API, and generated targets and header files for SDK at custom/default install location.

$ cmake --install . --prefix /<install-root>/
-- Installing: /<install-root>/lib/cmake/opentelemetry-cpp/opentelemetry-cpp-config.cmake
-- Installing: /<install-root>/lib/cmake/opentelemetry-cpp/opentelemetry-cpp-config-version.cmake
...
$

Incorporating into an existing CMake Project

To use the library from a CMake project, you can locate it directly with find_package and use the imported targets from generated package configurations. As of now, this will import targets for both API and SDK. In future, there may be separate packages for API and SDK which can be installed and imported separately according to need.

# CMakeLists.txt
find_package(opentelemetry-cpp CONFIG REQUIRED)
...
target_include_directories(foo PRIVATE ${OPENTELEMETRY_CPP_INCLUDE_DIRS})
target_link_libraries(foo PRIVATE ${OPENTELEMETRY_CPP_LIBRARIES})

Using opentelemetry-cpp package components

Note: opentelemetry-cpp CMake package components were introduced in v1.21.0

The opentelemetry-cpp package supports using the COMPONENTS argument to find_package. The following example illustrates using this feature to include and link the api header only target to an instrumented foo_lib while only including and linking the sdk and otlp_grpc_exporter targets to the foo_app.

# foo_lib/CMakeLists.txt
find_package(opentelemetry-cpp CONFIG REQUIRED COMPONENTS api)
add_library(foo_lib foo.cpp)
target_link_libraries(foo_lib PRIVATE opentelemetry-cpp::api)

# foo_app/CMakeLists.txt
find_package(opentelemetry-cpp CONFIG REQUIRED COMPONENTS api sdk exporters_otlp_grpc)
add_executable(foo_app main.cpp)
target_link_libraries(foo_app PRIVATE foo_lib opentelemetry-cpp::api opentelemetry-cpp::sdk opentelemetry-cpp::otlp_grpc_exporter )

The following table provides the mapping between components and targets. Components and targets available in the installation depends on the opentelemetry-cpp package build configuration.

Component	Targets
api	opentelemetry-cpp::api
sdk	opentelemetry-cpp::sdk
	opentelemetry-cpp::version
	opentelemetry-cpp::common
	opentelemetry-cpp::resources
	opentelemetry-cpp::trace
	opentelemetry-cpp::metrics
	opentelemetry-cpp::logs
ext_common	opentelemetry-cpp::ext
ext_http_curl	opentelemetry-cpp::http_client_curl
ext_dll	opentelemetry-cpp::opentelemetry_cpp
exporters_in_memory	opentelemetry-cpp::in_memory_span_exporter
	opentelemetry-cpp::in_memory_metric_exporter
exporters_ostream	opentelemetry-cpp::ostream_log_record_exporter
	opentelemetry-cpp::ostream_metrics_exporter
	opentelemetry-cpp::ostream_span_exporter
exporters_otlp_common	opentelemetry-cpp::proto
	opentelemetry-cpp::otlp_recordable
exporters_otlp_file	opentelemetry-cpp::otlp_file_client
	opentelemetry-cpp::otlp_file_exporter
	opentelemetry-cpp::otlp_file_log_record_exporter
	opentelemetry-cpp::otlp_file_metric_exporter
exporters_otlp_grpc	opentelemetry-cpp::proto_grpc
	opentelemetry-cpp::otlp_grpc_client
	opentelemetry-cpp::otlp_grpc_exporter
	opentelemetry-cpp::otlp_grpc_log_record_exporter
	opentelemetry-cpp::otlp_grpc_metrics_exporter
exporters_otlp_http	opentelemetry-cpp::otlp_http_client
	opentelemetry-cpp::otlp_http_exporter
	opentelemetry-cpp::otlp_http_log_record_exporter
	opentelemetry-cpp::otlp_http_metric_exporter
exporters_prometheus	opentelemetry-cpp::prometheus_exporter
exporters_elasticsearch	opentelemetry-cpp::elasticsearch_log_record_exporter
exporters_etw	opentelemetry-cpp::etw_exporter
exporters_zipkin	opentelemetry-cpp::zipkin_trace_exporter
shims_opentracing	opentelemetry-cpp::opentracing_shim

Build instructions using Bazel

NOTE: Experimental, and not supported for all the components. Make sure the GoogleTest installation may fail if there is a different version of googletest already installed in system-defined path.

Prerequisites for Bazel build

A supported platform (e.g. Windows, macOS or Linux). Refer to Platforms Supported for more information.
A compatible C++ compiler supporting at least C++14. Major compilers are supported. Refer to Supported Compilers for more information.
Git for fetching opentelemetry-cpp source code from repository. To install Git, consult the Set up Git guide on GitHub.
Bazel for building opentelemetry-cpp API, SDK with their unittests. We use 3.7.2 in our build system.

To install Bazel, consult the Installing Bazel guide.

Building as standalone Bazel Project

Getting the opentelemetry-cpp source:

# Change to the directory where you want to create the code repository
$ cd ~
$ mkdir source && cd source
$ git clone https://github.com/open-telemetry/opentelemetry-cpp
Cloning into 'opentelemetry-cpp'...
...
Resolving deltas: 100% (3225/3225), done.
$

Navigate to the repository cloned above, download the dependencies and build the source code:

$ cd opentelemetry-cpp
$ bazel build //...
bazel build -- //... -//exporters/otlp/... -//exporters/prometheus/...
Extracting Bazel installation...
Starting local Bazel server and connecting to it...
INFO: Analyzed 121 targets (98 packages loaded, 3815 targets configured).
INFO: Found 121 targets...
INFO: From Compiling sdk/src/trace/tracer_context.cc:
...

Once Bazel tests are built, run them with bazel test //... command
```
$ bazel test //...
..
$
```
The build artifacts will be located under bazel-bin

Incorporating into an existing Bazel Project

WORKSPACE file:

http_archive(
    name = "io_opentelemetry_cpp",
    sha256 = "<sha256>",
    strip_prefix = "opentelemetry-cpp-1.0.1",
    urls = [
        "https://github.com/open-telemetry/opentelemetry-cpp/archive/refs/tags/v1.0.1.tar.gz"
    ],
)

# Load OpenTelemetry dependencies after load.
load("@io_opentelemetry_cpp//bazel:repository.bzl", "opentelemetry_cpp_deps")

opentelemetry_cpp_deps()

# (required after v1.8.0) Load extra dependencies required for OpenTelemetry
load("@io_opentelemetry_cpp//bazel:extra_deps.bzl", "opentelemetry_extra_deps")

opentelemetry_extra_deps()

# Load gRPC dependencies after load.
load("@com_github_grpc_grpc//bazel:grpc_deps.bzl", "grpc_deps")

grpc_deps()

# Load extra gRPC dependencies due to https://github.com/grpc/grpc/issues/20511
load("@com_github_grpc_grpc//bazel:grpc_extra_deps.bzl", "grpc_extra_deps")

grpc_extra_deps()

Component level BUILD file:

cc_library(
   name = "<name>"
   ...
   deps = [
      "@io_opentelemetry_cpp//api",
      "@io_opentelemetry_cpp//exporters/otlp:otlp_exporter",
      "@io_opentelemetry_cpp//sdk/src/trace",
      ...
   ],
   ...
)

Building shared libs for Windows

Windows DLL build is supported under preview. Please check the doc for more details.

Generating binary packages

OpenTelemetry C++ supports generating platform specific binary packages from CMake configuration. The packages generated through this mayn't be production ready, and user may have to customize it further before using it as distribution.

Linux : deb, rpm, tgz
MacOS : tgz
Windows : NuGet, zip

This requires platform specific package generators already installed. The package generation can subsequently be enabled by using BUILD_PACKAGE option during cmake configuration

$ cd opentelemetry-cpp
$ mkdir build && cd build && cmake -DBUILD_PACKAGE=ON ..

-- Package name: opentelemetry-cpp-1.8.1-ubuntu-20.04-x86_64.deb
-- Configuring done
-- Generating done
...
$

Once build is complete as specified in standalone build section, the package can be generated as below.

$ cpack -C debug
CPack: Create package using DEB
...
CPack: - package: /home/<user>/opentelemetry-cpp/build/opentelemetry-cpp-1.8.1-ubuntu-20.04-x86_64.deb generated.
$

Using Package Managers

If you are using Conan to manage your dependencies, add opentelemetry-cpp/x.y.z to your conanfile's requires, where x.y.z is the release version you want to use. Please file issues here if you experience problems with the packages.

If you are using vcpkg on your project for external dependencies, then you can install the opentelemetry-cpp package with vcpkg install opentelemetry-cpp and follow the then displayed descriptions. Please see the vcpkg project for any issues regarding the packaging.

If you are using alpine linux you can install the opentelemetry-cpp packages with apk add -X http://dl-cdn.alpinelinux.org/alpine/edge/testing opentelemetry-cpp-dev.

Please note, these packages are not officially provided and maintained by OpenTelemetry C++ project, and are just listed here to consolidate all such efforts for ease of developers.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

INSTALL.md

INSTALL.md

Building opentelemetry-cpp

Dependencies

Build instructions using CMake

Prerequisites for CMake build

Building dependencies for the OTLP exporters

Building as standalone CMake Project

Incorporating into an existing CMake Project

Using opentelemetry-cpp package components

Build instructions using Bazel

Prerequisites for Bazel build

Building as standalone Bazel Project

Incorporating into an existing Bazel Project

Building shared libs for Windows

Generating binary packages

Using Package Managers

Files

INSTALL.md

Latest commit

History

INSTALL.md

File metadata and controls

Building opentelemetry-cpp

Dependencies

Build instructions using CMake

Prerequisites for CMake build

Building dependencies for the OTLP exporters

Building as standalone CMake Project

Incorporating into an existing CMake Project

Using opentelemetry-cpp package components

Build instructions using Bazel

Prerequisites for Bazel build

Building as standalone Bazel Project

Incorporating into an existing Bazel Project

Building shared libs for Windows

Generating binary packages

Using Package Managers