Note: C++ does not provide integrations for automatic instrumentation, but it's used by Proxy tracing such as
Envoy and
Nginx.
Compatibility requirements
The C++ tracing library requires C++17 toolchain to build. For a full list of Datadog’s tracing library compatiblity requirements and processor architecture support, visit the Compatibility Requirements page.
Getting started
Before you begin, make sure you have already installed and configured the Agent.
Instrument your application
Here is an example application that can be used for testing dd-trace-cpp.
This application creates a tracer instance with the default settings and generates a trace with two spans, which is reported under the service name my-service.
// tracer_example.cpp
#include <datadog/span_config.h>
#include <datadog/tracer.h>
#include <datadog/tracer_config.h>
#include <iostream>
#include <string>
namespace dd = datadog::tracing;
int main() {
dd::TracerConfig config;
config.service = "my-service";
const auto validated_config = dd::finalize_config(config);
if (!validated_config) {
std::cerr << validated_config.error() << '\n';
return 1;
}
dd::Tracer tracer{*validated_config};
// Create some spans.
{
auto span_a = tracer.create_span();
span_a.set_name("A");
span_a.set_tag("tag", "123");
auto span_b = span_a.create_child();
span_b.set_name("B");
span_b.set_tag("tag", "value");
}
return 0;
}
CPM.cmake is a cross-platform CMake script that adds dependency management capabilities to CMake.
# In a CMakeLists.txt
CPMAddPackage("gh:DataDog/dd-trace-cpp#0.2.1")
# Add `tracer_example` target
add_executable(tracer_example tracer_example.cpp)
# Statically link against `dd-trace-cpp`
# NOTE: To dynamically link against `dd-trace-cpp` use the `dd_trace::shared` target
target_link_libraries(tracer_example dd_trace::static)
Build the example using the following commands:
cmake -B build .
cmake --build build --target tracer_example -j
./build/tracer_example
DATADOG TRACER CONFIGURATION - {"collector":{"config":{"event_scheduler":{"type":"datadog::tracing::ThreadedEventScheduler" ... }}}
To integrate the dd-trace-cpp library into your C++ project using CMake, follow these steps:
include(FetchContent)
FetchContent_Declare(
dd-trace-cpp
GIT_REPOSITORY https://github.com/DataDog/dd-trace-cpp
GIT_TAG v0.2.0
GIT_SHALLOW ON
GIT_PROGRESS ON
)
FetchContent_MakeAvailable(dd-trace-cpp)
# Add `tracer_example` target
add_executable(tracer_example tracer_example.cpp)
# Statically link against `dd-trace-cpp`
# NOTE: To dynamically link against `dd-trace-cpp` use the `dd_trace_cpp_shared` target
target_link_libraries(tracer_example dd_trace::static)
Build the example using the following commands:
cmake -B build .
cmake --build build --target tracer_example -j
./build/tracer_example
DATADOG TRACER CONFIGURATION - {"collector":{"config":{"event_scheduler":{"type":"datadog::tracing::ThreadedEventScheduler" ... }}}
To manually download and install the dd-trace-cpp library, run the following bash script:
# Requires the "jq" command, which can be installed via
# the package manager:
# - APT: `apt install jq`
# - APK: `apk add jq`
# - YUM: `yum install jq`
if ! command -v jq >/dev/null 2>&1; then
>&2 echo "jq command not found. Install using the local package manager."
exit 1
fi
# Gets the latest release version number from GitHub.
get_latest_release() {
curl --silent "https://api.github.com/repos/$1/releases/latest" | jq --raw-output .tag_name
}
DD_TRACE_CPP_VERSION="$(get_latest_release DataDog/dd-trace-cpp)"
# Download and install dd-trace-cpp library.
wget https://github.com/DataDog/dd-trace-cpp/archive/${DD_TRACE_CPP_VERSION}.tar.gz -O dd-trace-cpp.tar.gz
mkdir dd-trace-cpp && tar zxvf dd-trace-cpp.tar.gz -C ./dd-trace-cpp/ --strip-components=1
cd dd-trace-cpp
# Download and install the correct version of dd-trace-cpp.
# Configure the project, build it, and install it.
cmake -B build .
cmake --build build -j
cmake --install build
By default, cmake --install places the shared library and public headers into the appropriate system directories (for example, /usr/local/[...]).
To install them in a specific location, use cmake --install build --prefix <INSTALL_DIR> instead.
Dynamic Linking
Link against libdd_trace_cpp.so, making sure the shared library is in LD_LIBRARY_PATH.
clang -std=c++17 -o tracer_example tracer_example.cpp -ldd_trace_cpp
./tracer_example
DATADOG TRACER CONFIGURATION - {"collector":{"config":{"event_scheduler":{"type":"datadog::tracing::ThreadedEventScheduler" ... }}}
Configuration
If needed, configure the tracing library to send application performance telemetry data as you require, including setting up Unified Service Tagging. Read Library Configuration for details.
Further Reading
Additional helpful documentation, links, and articles:
