Installing the OTel C++ client SDK package

The OTel C++ client SDK package is an OpenTelemetry OTLP exporter for C++. This package helps you to 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

Ensure that the following prerequisites are met:

Linux:

gcc 9.4.0 or later is installed.
Git, Python3, 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 need to select workloads, which are a set of tools and components for specific development scenarios. If you install the msvc compiler, make sure to 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
```

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

To verify whether the OTel C++ client SDK package works in your host machine, follow the steps:

Download the OTel 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 OTel 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 OTel examples by completing the following steps:
1. Install the Instana host agent.
2. Configure the Instana agent to receive OTLP data.
3. Send the OTLP data to the host agent on the same host machine 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.