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
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_cpp-static)
Here’s an example of how to use the dd-trace-cpp library in your C++ code to create spans and traces:
// 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;
}
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
After installing the dd-trace-cpp library, you can use it in your C++ code to create spans and traces. Here’s an example:
// 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.
{
dd::SpanConfig options;
options.name = "A";
options.tags.emplace("tag", "123");
auto span_a = tracer.create_span(options);
auto span_b = span_a.create_child();
span_b.set_name("B");
span_b.set_tag("tag", "value");
}
return 0;
}
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:
