OpenTelemetry C++ client SDK package

The OpenTelemetry C++ client SDK package is an OpenTelemetry OTLP exporter for C++. This package helps you include OpenTelemetry instrumentation in your applications. Then, the data can be sent to Instana over the OTLP protocol. The package is built on Opentelemetry-cpp.

Supported operating systems
Prerequisites
Installing the package
Verifying the installation

Supported operating systems

Linux: Ubuntu 20.04 (GCC 9.4.0) (64-bit)
Windows: Windows Server 2016 (Visual Studio Enterprise 2019) (32-bit and 64-bit)

Prerequisites

Check that the following prerequisites are met:

Linux:

GNU Compiler Collection (GCC) 9.4.0 or later is installed.
Git, Python 3, and Perl are installed.

vcpkg is installed by running the following command:

git clone https://github.com/Microsoft/vcpkg.git
./vcpkg/bootstrap-vcpkg.sh
./vcpkg/vcpkg install abseil
./vcpkg/vcpkg install c-ares
./vcpkg/vcpkg install curl[non-http,openssl,ssl]
./vcpkg/vcpkg install grpc[codegen]

Windows platforms:
- MSVC or MinGW compiler with CMake is installed.
- CMake or Visual studio 2019 is installed.
  - To install CMake, go to the official CMake website and download the Windows installer for the latest stable version of CMake. Choose the appropriate version for your system, either 32-bit or 64-bit.
  - To install Visual Studio 2019, go to the Visual Studio download page and download the Visual Studio Windows installer. Run the installer that you downloaded. During the installation process, you must select workloads, which are a set of tools and components for specific development scenarios. If you install the MSVC compiler, select the Desktop development with C++ workload.
- vcpkg is installed by running the following commands:
```
git clone https://github.com/Microsoft/vcpkg.git
.\vcpkg\bootstrap-vcpkg.cmd
.\vcpkg.exe integrate
.\vcpkg.exe install abseil
.\vcpkg.exe install c-ares
.\vcpkg.exe install curl
.\vcpkg.exe install grpc
```

To build a C++ working environment, you need a C++ library management system such as Vcpkg. For more information on how to build a secure OpenTelemetry C++ development environment, see OTel C++ Client SDK.

Installing the package

To install the package, download the package file, and then extract it to a local directory.

Linux: Download the opentelemetry-cpp-1.9.1-gcc9.4.0-ubuntu20.04_x64.tar.gz file, and extract the file by running the following command:

tar xzf opentelemetry-cpp-1.9.1-gcc9.4.0-ubuntu20.04_x64.tar.gz

Windows (64 bit): Download the opentelemetry-cpp-1.9.1-vs2019-windows_x64.zip file, and extract the file by running the following command:

unzip opentelemetry-cpp-1.9.1-vs2019-windows_x64.zip

Windows (32 bit): Download the opentelemetry-cpp-1.9.1-vs2019-windows_x86.zip file, and extract the file by running the following command:

unzip opentelemetry-cpp-1.9.1-vs2019-windows_x86.zip

Verifying the installation

Complete the following steps to verify whether the OpenTelemetry C++ client SDK package works in your host machine:

Download the OpenTelemetry examples.
1. Download the grpc_main.cc and http_main.cc files from Opentelemetry-cpp example OTeL. Then save them to the otlp directory.
2. Download the foo_library.cc and foo_libary.h file from Opentelemetry-cpp example foo_library. Then save them to the otlp/foo_library directory.

Create a CMakeLists.txt file in the otlp directory.

Linux:

cmake_minimum_required(VERSION 3.12.0)

project(sample)

set(CMAKE_CXX_STANDARD 14)
set(OTEL_CPP_DIR "/opt/otel-cppclient/opentelemetry-cpp_x64-linux")
set(OTEL_LIBS_PATH "${OTEL_CPP_DIR}/lib")
set(VCPKGL_LIBS_PATH "<path to vcpkg>/installed/x64-linux/lib")

include_directories("${OTEL_CPP_DIR}/include")

find_package(absl REQUIRED)
find_package(Protobuf CONFIG REQUIRED)
find_package(CURL REQUIRED)
find_package(gRPC REQUIRED)

# HTTP
add_executable(otel_http_sample http_main.cc
    "foo_library/foo_library.cc"
)

target_link_libraries(otel_http_sample
    -pthread
    ${OTEL_LIBS_PATH}/libopentelemetry_trace.a
    ${OTEL_LIBS_PATH}/libopentelemetry_proto.a
    ${OTEL_LIBS_PATH}/libopentelemetry_http_client_curl.a
    ${OTEL_LIBS_PATH}/libopentelemetry_exporter_otlp_http.a
    ${OTEL_LIBS_PATH}/libopentelemetry_exporter_otlp_http_client.a
    ${OTEL_LIBS_PATH}/libopentelemetry_logs.a
    ${OTEL_LIBS_PATH}/libopentelemetry_otlp_recordable.a
    ${OTEL_LIBS_PATH}/libopentelemetry_common.a
    ${OTEL_LIBS_PATH}/libopentelemetry_trace.a
    ${OTEL_LIBS_PATH}/libopentelemetry_resources.a
    ${VCPKGL_LIBS_PATH}/libprotobuf.a
    ${VCPKGL_LIBS_PATH}/libcurl.a
    ${VCPKGL_LIBS_PATH}/libssl.a
    ${VCPKGL_LIBS_PATH}/libcrypto.a
    -lpthread
    -ldl
    ${VCPKGL_LIBS_PATH}/libz.a
    )

# GRPC
add_executable(otel_grpc_sample grpc_main.cc
    "foo_library/foo_library.cc"
)

target_link_libraries(otel_grpc_sample
    -pthread
    ${OTEL_LIBS_PATH}/libopentelemetry_trace.a
    ${OTEL_LIBS_PATH}/libopentelemetry_exporter_otlp_grpc.a
    -pthread
    ${OTEL_LIBS_PATH}/libopentelemetry_otlp_recordable.a
    ${OTEL_LIBS_PATH}/libopentelemetry_trace.a
    ${OTEL_LIBS_PATH}/libopentelemetry_logs.a
    ${OTEL_LIBS_PATH}/libopentelemetry_resources.a
    ${OTEL_LIBS_PATH}/libopentelemetry_metrics.a
    ${OTEL_LIBS_PATH}/libopentelemetry_common.a
    ${OTEL_LIBS_PATH}/libopentelemetry_exporter_otlp_grpc_client.a
    ${OTEL_LIBS_PATH}/libopentelemetry_proto.a
)
target_link_libraries(otel_grpc_sample absl::flat_hash_map absl::strings absl::str_format)
target_link_libraries(otel_grpc_sample gRPC::gpr gRPC::grpc gRPC::grpc++ gRPC::grpc++_alts)

Windows:

cmake_minimum_required(VERSION 3.12.0)

project(otel_sample)

set(CMAKE_CXX_STANDARD 14)
set(OTEL_CPP_DIR "C:/otel-cppclient/opentelemetry-cpp_x64-windows")
set(OTEL_LIBS_PATH "${OTEL_CPP_DIR}/lib")
set(CMAKE_TOOLCHAIN_FILE "<path to vcpkg>/scripts/buildsystems/vcpkg.cmake" CACHE STRING "Vcpkg toolchain file")

include_directories("${OTEL_CPP_DIR}/include")

find_package(absl REQUIRED)
find_package(protobuf CONFIG REQUIRED)
find_package(CURL REQUIRED)
find_package(gRPC REQUIRED)

# HTTP
add_executable(otel_http_sample http_main.cc
    "foo_library/foo_library.cc" 
)

target_link_libraries(otel_http_sample 
    ${OTEL_LIBS_PATH}/opentelemetry_proto.lib
    ${OTEL_LIBS_PATH}/opentelemetry_http_client_curl.lib 
    ${OTEL_LIBS_PATH}/opentelemetry_exporter_otlp_http.lib
    ${OTEL_LIBS_PATH}/opentelemetry_exporter_otlp_http_client.lib
    ${OTEL_LIBS_PATH}/opentelemetry_logs.lib
    ${OTEL_LIBS_PATH}/opentelemetry_otlp_recordable.lib
    ${OTEL_LIBS_PATH}/opentelemetry_common.lib
    ${OTEL_LIBS_PATH}/opentelemetry_trace.lib
    ${OTEL_LIBS_PATH}/opentelemetry_resources.lib
    )
target_link_libraries(otel_http_sample absl::flat_hash_map absl::strings absl::str_format)
target_link_libraries(otel_http_sample CURL::libcurl)
target_link_libraries(otel_http_sample protobuf::libprotobuf)

# GRPC
add_executable(otel_grpc_sample grpc_main.cc
    "foo_library/foo_library.cc" 
)

target_link_libraries(otel_grpc_sample 
    ${OTEL_LIBS_PATH}/opentelemetry_proto.lib
    ${OTEL_LIBS_PATH}/opentelemetry_proto_grpc.lib
    ${OTEL_LIBS_PATH}/opentelemetry_exporter_otlp_grpc.lib
    ${OTEL_LIBS_PATH}/opentelemetry_exporter_otlp_grpc_client.lib
    ${OTEL_LIBS_PATH}/opentelemetry_logs.lib
    ${OTEL_LIBS_PATH}/opentelemetry_otlp_recordable.lib
    ${OTEL_LIBS_PATH}/opentelemetry_common.lib
    ${OTEL_LIBS_PATH}/opentelemetry_trace.lib
    ${OTEL_LIBS_PATH}/opentelemetry_resources.lib
)
target_link_libraries(otel_grpc_sample absl::flat_hash_map absl::strings absl::str_format)
target_link_libraries(otel_grpc_sample gRPC::gpr gRPC::grpc gRPC::grpc++ gRPC::grpc++_alts)

Build these OpenTelemetry examples that you downloaded in step 1 by running the following commands:

Linux:

cd otlp
mkdir build
cd ./build/
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_SYSTEM_NAME=Linux -DCMAKE_VERBOSE_MAKEFILE=ON -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=<path to vcpkg>/scripts/toolchains/linux.cmake -DCMAKE_TOOLCHAIN_FILE=<path to vcpkg>/scripts/buildsystems/vcpkg.cmake
cmake --build .

Windows:

cd otlp
mkdir build
cd .\build\
cmake .. -DCMAKE_TOOLCHAIN_FILE="<path to vcpkg>/scripts/buildsystems/vcpkg.cmake"
cmake --build .

Test these OpenTelemetry examples by completing the following steps:
1. Install the Instana host agent.
2. Configure the Instana agent to receive OTLP data.
3. On the same host machine, send the OTLP data to the host agent by running either of the following commands:
```
example_otlp_grpc localhost:4317
```
```
example_otlp_http localhost:4318/v1/traces
```
4. If you see any error message, check the host agent log.