Implement stable session identifier headers for telemetry

Add DD-Session-ID and DD-Root-Session-ID headers to all telemetry
requests per the Stable Service Instance Identifier RFC.

- DD-Session-ID (= runtime_id) sent on every telemetry request
- DD-Root-Session-ID sent only when root != current runtime_id
- Root session ID inherited from _DD_ROOT_CPP_SESSION_ID env var
  (for exec-based child processes) or defaults to first runtime_id
- setenv propagates root session ID to exec'd children automatically
- Fork propagation is automatic (memory survives fork)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: khanayan123

include/datadog/tracer_signature.h

@@ -33,15 +33,18 @@ namespace tracing {
 
 struct TracerSignature {
   RuntimeID runtime_id;
+  std::string root_session_id;
   std::string default_service;
   std::string default_environment;
   std::string library_version;
   StringView library_language;
   StringView library_language_version;
 
   TracerSignature() = delete;
-  TracerSignature(RuntimeID id, std::string service, std::string environment)
+  TracerSignature(RuntimeID id, std::string root_session,
+                  std::string service, std::string environment)
       : runtime_id(id),
+        root_session_id(std::move(root_session)),
         default_service(std::move(service)),
         default_environment(std::move(environment)),
         library_version(tracer_version),

src/datadog/telemetry/telemetry.cpp

@@ -53,10 +53,13 @@ void init(FinalizedConfiguration configuration,
           std::shared_ptr<tracing::HTTPClient> client,
           std::shared_ptr<tracing::EventScheduler> event_scheduler,
           tracing::HTTPClient::URL agent_url, tracing::Clock clock) {
-  instance(Ctor_param{configuration,
-                      tracing::TracerSignature(tracing::RuntimeID::generate(),
-                                               tracing::get_process_name(), ""),
-                      logger, client, event_scheduler, agent_url, clock});
+  auto runtime_id = tracing::RuntimeID::generate();
+  auto root_session_id = runtime_id.string();
+  instance(Ctor_param{
+      configuration,
+      tracing::TracerSignature(runtime_id, std::move(root_session_id),
+                               tracing::get_process_name(), ""),
+      logger, client, event_scheduler, agent_url, clock});
 }
 
 void init(FinalizedConfiguration configuration,

src/datadog/telemetry/telemetry_impl.cpp

@@ -302,13 +302,18 @@ void Telemetry::app_started() {
   auto payload = app_started_payload();
 
   auto on_headers = [payload_size = payload.size(),
-                     debug_enabled = config_.debug](DictWriter& headers) {
+                     debug_enabled = config_.debug,
+                     &sig = tracer_signature_](DictWriter& headers) {
     headers.set("Content-Type", "application/json");
     headers.set("Content-Length", std::to_string(payload_size));
     headers.set("DD-Telemetry-API-Version", "v2");
     headers.set("DD-Client-Library-Language", "cpp");
     headers.set("DD-Client-Library-Version", tracer_version);
     headers.set("DD-Telemetry-Request-Type", "app-started");
+    headers.set("DD-Session-ID", sig.runtime_id.string());
+    if (sig.root_session_id != sig.runtime_id.string()) {
+      headers.set("DD-Root-Session-ID", sig.root_session_id);
+    }
     if (debug_enabled) {
       headers.set("DD-Telemetry-Debug-Enabled", "true");
     }
@@ -356,14 +361,18 @@ void Telemetry::app_closing() {
 
 void Telemetry::send_payload(StringView request_type, std::string payload) {
   auto set_telemetry_headers = [request_type, payload_size = payload.size(),
-                                debug_enabled =
-                                    config_.debug](DictWriter& headers) {
+                                debug_enabled = config_.debug,
+                                &sig = tracer_signature_](DictWriter& headers) {
     headers.set("Content-Type", "application/json");
     headers.set("Content-Length", std::to_string(payload_size));
     headers.set("DD-Telemetry-API-Version", "v2");
     headers.set("DD-Client-Library-Language", "cpp");
     headers.set("DD-Client-Library-Version", tracer_version);
     headers.set("DD-Telemetry-Request-Type", request_type);
+    headers.set("DD-Session-ID", sig.runtime_id.string());
+    if (sig.root_session_id != sig.runtime_id.string()) {
+      headers.set("DD-Root-Session-ID", sig.root_session_id);
+    }
     if (debug_enabled) {
       headers.set("DD-Telemetry-Debug-Enabled", "true");
     }

src/datadog/tracer.cpp

@@ -13,6 +13,7 @@
 
 #include <algorithm>
 #include <cassert>
+#include <cstdlib>
 #include <filesystem>
 
 #include "config_manager.h"
@@ -36,6 +37,17 @@ namespace fs = std::filesystem;
 namespace datadog {
 namespace tracing {
 
+namespace {
+
+std::string get_root_session_id(const std::string& runtime_id) {
+  if (const char* env = std::getenv("_DD_ROOT_CPP_SESSION_ID")) {
+    return std::string(env);
+  }
+  return runtime_id;
+}
+
+}  // namespace
+
 void to_json(nlohmann::json& j, const PropagationStyle& style) {
   j = to_string_view(style);
 }
@@ -48,7 +60,9 @@ Tracer::Tracer(const FinalizedTracerConfig& config,
     : logger_(config.logger),
       runtime_id_(config.runtime_id ? *config.runtime_id
                                     : RuntimeID::generate()),
-      signature_{runtime_id_, config.defaults.service,
+      signature_{runtime_id_,
+                 get_root_session_id(runtime_id_.string()),
+                 config.defaults.service,
                  config.defaults.environment},
       config_manager_(std::make_shared<ConfigManager>(config)),
       collector_(/* see constructor body */),
@@ -64,6 +78,8 @@ Tracer::Tracer(const FinalizedTracerConfig& config,
       baggage_extraction_enabled_(false),
       tracing_enabled_(config.tracing_enabled),
       resource_renaming_mode_(config.resource_renaming_mode) {
+  setenv("_DD_ROOT_CPP_SESSION_ID", signature_.root_session_id.c_str(), 1);
+
   telemetry::init(config.telemetry, signature_, logger_, config.http_client,
                   config.event_scheduler, config.agent_url);
   if (config.report_hostname) {

test/remote_config/test_remote_config.cpp

@@ -47,8 +47,10 @@ auto logger = std::make_shared<NullLogger>();
 
 REMOTE_CONFIG_TEST("initial state payload") {
   // Verify the initial payload structure for a remote configuration instance.
+  auto runtime_id = RuntimeID::generate();
   const TracerSignature tracer_signature{
-      /* runtime_id = */ RuntimeID::generate(),
+      /* runtime_id = */ runtime_id,
+      /* root_session_id = */ runtime_id.string(),
       /* service = */ "testsvc",
       /* environment = */ "test"};
 
@@ -92,8 +94,10 @@ REMOTE_CONFIG_TEST("initial state payload") {
 // TODO: test all combination of product and capabilities generation
 
 REMOTE_CONFIG_TEST("response processing") {
+  auto runtime_id = RuntimeID::generate();
   const TracerSignature tracer_signature{
-      /* runtime_id = */ RuntimeID::generate(),
+      /* runtime_id = */ runtime_id,
+      /* root_session_id = */ runtime_id.string(),
       /* service = */ "testsvc",
       /* environment = */ "test"};
 

test/telemetry/test_telemetry.cpp

@@ -89,8 +89,10 @@ TELEMETRY_IMPLEMENTATION_TEST("Tracer telemetry lifecycle") {
   auto client = std::make_shared<MockHTTPClient>();
   auto scheduler = std::make_shared<FakeEventScheduler>();
 
+  auto runtime_id = RuntimeID::generate();
   const TracerSignature tracer_signature{
-      /* runtime_id = */ RuntimeID::generate(),
+      /* runtime_id = */ runtime_id,
+      /* root_session_id = */ runtime_id.string(),
       /* service = */ "testsvc",
       /* environment = */ "test"};
 
@@ -353,6 +355,65 @@ TELEMETRY_IMPLEMENTATION_TEST("Tracer telemetry lifecycle") {
   }
 }
 
+TELEMETRY_IMPLEMENTATION_TEST("session ID headers") {
+  auto logger = std::make_shared<MockLogger>();
+  auto client = std::make_shared<MockHTTPClient>();
+  auto scheduler = std::make_shared<FakeEventScheduler>();
+  auto url = HTTPClient::URL::parse("http://localhost:8000");
+
+  SECTION("root process: DD-Session-ID present, DD-Root-Session-ID absent") {
+    auto rid = RuntimeID::generate();
+    const TracerSignature sig{rid, rid.string(), "testsvc", "test"};
+
+    Telemetry telemetry{*finalize_config(), sig, logger, client, scheduler,
+                        *url};
+
+    auto it = client->request_headers.items.find("DD-Session-ID");
+    REQUIRE(it != client->request_headers.items.end());
+    CHECK(it->second == rid.string());
+
+    CHECK(client->request_headers.items.find("DD-Root-Session-ID") ==
+          client->request_headers.items.end());
+  }
+
+  SECTION("child process: DD-Root-Session-ID present when different") {
+    auto rid = RuntimeID::generate();
+    auto root_rid = RuntimeID::generate();
+    const TracerSignature sig{rid, root_rid.string(), "testsvc", "test"};
+
+    Telemetry telemetry{*finalize_config(), sig, logger, client, scheduler,
+                        *url};
+
+    auto session_it = client->request_headers.items.find("DD-Session-ID");
+    REQUIRE(session_it != client->request_headers.items.end());
+    CHECK(session_it->second == rid.string());
+
+    auto root_it = client->request_headers.items.find("DD-Root-Session-ID");
+    REQUIRE(root_it != client->request_headers.items.end());
+    CHECK(root_it->second == root_rid.string());
+  }
+
+  SECTION("heartbeat includes session headers") {
+    auto rid = RuntimeID::generate();
+    auto root_rid = RuntimeID::generate();
+    const TracerSignature sig{rid, root_rid.string(), "testsvc", "test"};
+
+    Telemetry telemetry{*finalize_config(), sig, logger, client, scheduler,
+                        *url};
+
+    client->request_headers.items.clear();
+    scheduler->trigger_heartbeat();
+
+    auto session_it = client->request_headers.items.find("DD-Session-ID");
+    REQUIRE(session_it != client->request_headers.items.end());
+    CHECK(session_it->second == rid.string());
+
+    auto root_it = client->request_headers.items.find("DD-Root-Session-ID");
+    REQUIRE(root_it != client->request_headers.items.end());
+    CHECK(root_it->second == root_rid.string());
+  }
+}
+
 TELEMETRY_IMPLEMENTATION_TEST("Tracer telemetry API") {
   const Clock clock = [] {
     TimePoint result;
@@ -364,8 +425,10 @@ TELEMETRY_IMPLEMENTATION_TEST("Tracer telemetry API") {
   auto client = std::make_shared<MockHTTPClient>();
   auto scheduler = std::make_shared<FakeEventScheduler>();
 
+  auto runtime_id = RuntimeID::generate();
   const TracerSignature tracer_signature{
-      /* runtime_id = */ RuntimeID::generate(),
+      /* runtime_id = */ runtime_id,
+      /* root_session_id = */ runtime_id.string(),
       /* service = */ "testsvc",
       /* environment = */ "test"};
 
@@ -869,8 +932,10 @@ TELEMETRY_IMPLEMENTATION_TEST("Tracer telemetry configuration") {
   auto client = std::make_shared<MockHTTPClient>();
   auto scheduler = std::make_shared<FakeEventScheduler>();
 
+  auto runtime_id = RuntimeID::generate();
   const TracerSignature tracer_signature{
-      /* runtime_id = */ RuntimeID::generate(),
+      /* runtime_id = */ runtime_id,
+      /* root_session_id = */ runtime_id.string(),
       /* service = */ "testsvc",
       /* environment = */ "test"};
 

test/test_datadog_agent.cpp

@@ -199,7 +199,8 @@ DATADOG_AGENT_TEST("Remote Configuration") {
   auto finalized = finalize_config(config);
   REQUIRE(finalized);
 
-  const TracerSignature signature(RuntimeID::generate(), "testsvc", "test");
+  auto rid = RuntimeID::generate();
+  const TracerSignature signature(rid, rid.string(), "testsvc", "test");
 
   // TODO: set telemetry mock
   auto config_manager = std::make_shared<ConfigManager>(*finalized);