For AI agents: A markdown version of this page is available at https://docs.datadoghq.com/real_user_monitoring/application_monitoring/cpp/setup.md. A documentation index is available at /llms.txt.

C / C++ Monitoring Setup

This product is not supported for your selected Datadog site. ().

Overview

This page describes how to instrument your applications for Real User Monitoring (RUM) with the C++ SDK.

Prerequisites

Before you begin, you need:

  • A Datadog account with RUM or Error Tracking enabled
  • A C++17-compatible compiler
  • If using CMake: a project defined using CMake 3.21 or later

Setup

Add the C++ SDK as a dependency

Add the SDK's public headers to your project's include paths, and add the SDK as a linker dependency.

    Using CMake's FetchContent module downloads and builds the SDK from source, guaranteeing binary compatibility and giving you full control over build configuration.

    In your project's CMakeLists.txt, use CMake's FetchContent module to download and build the SDK as part of your project:

    include(FetchContent)
FetchContent_Declare(
    Datadog
    GIT_REPOSITORY https://github.com/DataDog/dd-sdk-cpp.git
    GIT_TAG        <version>
)
FetchContent_MakeAvailable(Datadog)

    Replace <version> with a release tag from the SDK's GitHub Releases (for example, 0.3.0), or use the full commit SHA for your chosen release.

    To add the SDK as a dependency for your application, pass its CMake target to datadog_enable():

    datadog_enable(my-app)

    For more detailed information on CMake setup, see Advanced Build Configuration.

    If you use CMake to build your application, but you want to use precompiled SDK binaries, use CMake's find_package() command.

    1. Download the release archive for your platform from the SDK's GitHub Releases, then extract it to a directory in your project (for example, external/datadog-sdk/).

    2. In your CMakeLists.txt, add that directory to CMAKE_PREFIX_PATH and call find_package:

    list(APPEND CMAKE_PREFIX_PATH external/datadog-sdk)
find_package(Datadog REQUIRED)

    To add the SDK as a dependency for your application, pass its CMake target to datadog_enable():

    datadog_enable(my-app)

    For more detailed information on CMake setup, see Advanced Build Configuration.

    If you're not using CMake, download precompiled binaries or build the SDK from source with CMake. Then point your compiler and linker to the appropriate headers and libraries. For example, in a Makefile:

    INCLUDES = -Iexternal/datadog-sdk/include
LDFLAGS  = -Lexternal/datadog-sdk/lib
LDLIBS   = -lddsdkcpp -lcurl -luuid

    For more detailed information on build configuration, see Advanced Build Configuration.

    Create a RUM Application in the Datadog UI

    1. Navigate to Digital Experience > Add an Application.
    2. Select C++ as the application type and enter an application name to generate a unique RUM application ID and client token.
    3. Copy the application ID and client token. You need them to initialize the SDK.

    Initialize the SDK

    In your application code, include the appropriate SDK headers:

      #include "datadog.hpp"

      #include "datadog.h"

      Next, as early as possible in your application's startup sequence, initialize a Core using the configuration details that identify your RUM Application:

        // Configure the SDK with your client token and unified service tagging values
datadog::CoreConfig config("<client_token>", "<service>", "<env>");

// Provide the SDK with the path to a storage directory owned by your application
config.SetApplicationStoragePath("<app-storage-dir>");

// Create the core with your initial tracking consent value
auto core = datadog::Core::Create(config, datadog::TrackingConsent::Granted);

        /* Configure the SDK with your client token and unified service tagging values */
dd_core_config_t config;
dd_core_config_init(&config, "<client_token>", "<service>", "<env>");

/* Provide the SDK with the path to a storage directory owned by your application */
dd_core_config_set_application_storage_path(&config, "<app-storage-dir>");

/* Create the core with your initial tracking consent value */
dd_core_t* core = dd_core_create(&config, DD_TRACKING_CONSENT_GRANTED);

        Note: The C API requires explicit cleanup:

        /* Free all resources held by the core when finished */
dd_core_destroy(core);

        Configure Datadog site

        Use SetSite to configure the SDK with your Datadog site.

          config.SetSite(datadog::Site::us3);

          dd_core_config_set_site(&config, DD_SITE_US3);

          Configure Datadog site

          Use SetSite to configure the SDK with your Datadog site.

            config.SetSite(datadog::Site::us5);

            dd_core_config_set_site(&config, DD_SITE_US5);

            Configure Datadog site

            Use SetSite to configure the SDK with your Datadog site.

              config.SetSite(datadog::Site::eu1);

              dd_core_config_set_site(&config, DD_SITE_EU1);

              Configure Datadog site

              Use SetSite to configure the SDK with your Datadog site.

                config.SetSite(datadog::Site::ap1);

                dd_core_config_set_site(&config, DD_SITE_AP1);

                Configure Datadog site

                Use SetSite to configure the SDK with your Datadog site.

                  config.SetSite(datadog::Site::ap2);

                  dd_core_config_set_site(&config, DD_SITE_AP2);

                  Configure Datadog site

                  Use SetSite to configure the SDK with your Datadog site.

                    config.SetSite(datadog::Site::us1_fed);

                    dd_core_config_set_site(&config, DD_SITE_US1_FED);

                    Configure Datadog site

                    Use SetSite to configure the SDK with your Datadog site.

                      config.SetSite(datadog::Site::us2_fed);

                      dd_core_config_set_site(&config, DD_SITE_US2_FED);

                      Configure an application storage path

                      The SDK requires an application storage path, which must be an existing directory that's exclusively used by your application. The SDK creates a .datadog/ subdirectory within that directory and stores all transient files within it.

                      Set tracking consent (GDPR compliance)

                      For GDPR compliance, the SDK requires a tracking consent value at initialization. Your application can set this value to any of:

                      1. Pending: The SDK starts collecting data and storing it locally, but does not send it to Datadog.
                      2. Granted: The SDK sends all pending and future data to Datadog.
                      3. NotGranted: The SDK deletes all pending data and does not collect any further data.

                      The tracking consent value may be updated at any time, as long as the Core still exists:

                        core->SetTrackingConsent(datadog::TrackingConsent::Pending);

                        dd_core_set_tracking_consent(core, DD_TRACKING_CONSENT_PENDING);

                        Other options

                        For information on other SDK configuration options, see Advanced Configuration.

                        Register RUM and start the SDK

                        After the Core is configured, register the RUM feature and call Start().

                          // Configure and register RUM
datadog::RumConfig rum_config("<rum_application_id>");
auto rum = datadog::Rum::Register(core, rum_config);

// Start the core to begin collecting and uploading data
core->Start();

                          /* Configure and register RUM */
dd_rum_config_t rum_config;
dd_rum_config_init(&rum_config, "<rum_application_id>");
dd_rum_t* rum = dd_rum_init(core, &rum_config);

/* Start the core to begin collecting and uploading data */
dd_core_start(core);

                          Note: The C API requires explicit cleanup:

                          /* Free all resources when finished */
dd_rum_destroy(rum);
dd_core_destroy(core);

                          Configure RUM session sample rate

                          To control the percentage of RUM sessions sent to Datadog, you can set a session sample rate between 0.0 and 100.0. The default is 100.0, which keeps all sessions.

                            // In this example, only 75% of sessions will be sent to Datadog
rum_config.SetSessionSampleRate(75.0f);

                            /** In this example, only 75% of sessions will be sent to Datadog */
dd_rum_config_set_session_sample_rate(&rum_config, 75.0f);

                            Datadog recommends setting the sample rate to 100%, ensuring that all RUM sessions are ingested for full visibility and accurate metrics. To control which sessions are indexed and retained, configure retention filters. For more information, see RUM Without Limits.

                            Instrument view transitions

                            Call StartView whenever your application transitions to a new screen, scene, or meaningful state:

                              // Record that the user is now on the startup screen
rum->StartView("startup_screen", "Startup Screen");

                              /* Record that the user is now on the startup screen */
dd_rum_start_view(rum, "startup_screen", "Startup Screen", NULL);

                              For more information on RUM instrumentation, see Instrument your application.

                              Verify your setup

                              After instrumenting your application, verify that the SDK is correctly sending data to Datadog.

                              Check diagnostic output

                              By default, the SDK logs diagnostic warnings and errors to stderr. You can increase the verbosity of this output in your CoreConfig:

                                config.SetDiagnosticThreshold(datadog::DiagnosticLevel::Debug);

                                dd_core_config_set_diagnostic_threshold(&config, DD_DIAGNOSTIC_LEVEL_DEBUG);

                                After the SDK is correctly configured and tracking consent is granted, you should see periodic console output. Output like this indicates that the SDK is uploading data:

                                [DATADOG DEBUG] Initiating HTTP request
[DATADOG DEBUG] Batch upload OK; will delete and continue this upload cycle
[DATADOG STATUS] Upload cycle finished with all uploads successful
[DATADOG DEBUG] Scheduled next upload cycle for feature

                                Note: Revert the diagnostic threshold change before building for Release. For more information on diagnostic logging, see Advanced Configuration.

                                View your data in Datadog

                                After running your app, navigate to the RUM Explorer to see sessions from your application. You should see session data within a few minutes.

                                Further reading

                                Additional helpful documentation, links, and articles: