Tracing C++ Applications

Docs > APM > Application Instrumentation > Automatic Instrumentation > Add the Datadog Tracing Library > Tracing C++ Applications

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#1.0.0")

# 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 -DCMAKE_BUILD_TYPE=Release .
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        v1.0.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 -DCMAKE_BUILD_TYPE=Release .
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
LD_LIBRARY_PATH=/usr/local/lib/ ./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.