Implement stable session identifier headers for telemetry (#295)

* Implement stable session identifier headers for telemetry

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

- DD-Session-ID is always set to the tracer's runtime_id
- DD-Root-Session-ID is only set when it differs from the session ID
  (i.e. when running as a child process)
- Root session ID is propagated to exec'd children via
  _DD_ROOT_CPP_SESSION_ID env var, read in finalize_config()
- _DD_ROOT_CPP_SESSION_ID registered in the environment variable
  registry and supported-configurations.json

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

* Resync supported-configurations.json via config-inversion tool

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

* Fix config-inversion: output null default for _DD_ROOT_CPP_SESSION_ID

The central registry expects null as the default value. Change the
macro default from "" to nullptr and teach the config-inversion tool
to emit JSON null for nullptr defaults.

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

* Match registry: _DD_ROOT_CPP_SESSION_ID implementation B, default ""

The central registry has this config as implementation B with an empty
string default. Update environment.h to use "" and teach config-inversion
to emit "B" for this var via an override map.

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

* Revert to implementation A with null default for _DD_ROOT_CPP_SESSION_ID

Registry entry had trailing space in name (now fixed by registry team).
Use implementation A and null default to match registry.

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

* Update include/datadog/environment.h

Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com>

* fix: address PR review — use empty string default, move env lookup

- Change _DD_ROOT_CPP_SESSION_ID default from nullptr to "" in
  environment.h
- Move _DD_ROOT_CPP_SESSION_ID lookup into load_tracer_env_config()
  so it follows the same pattern as other env var loading
- Add root_session_id field to TracerConfig struct
- Update supported-configurations.json to implementation B with
  default ""
- No changes to config-inversion tool

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: revert config-inversion changes, no longer needed with "" default

Since _DD_ROOT_CPP_SESSION_ID now defaults to "" (not nullptr), the
config-inversion tool doesn't need the nullptr specialization. Revert
to original to_string_any and fix implementation marker to "A".

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: revert unrelated formatting, deduplicate session headers, fix Windows setenv

- Revert whitespace-only changes (const char * style) in environment.cpp
  and environment.h to keep the diff focused on the feature.
- Extract set_session_headers() helper in telemetry_impl.cpp to avoid
  duplicating session header logic in app_started() and send_payload().
- Fix Windows _putenv_s path to check getenv() first, matching the
  POSIX setenv(..., 0) "don't overwrite" semantics.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Update test/telemetry/test_telemetry.cpp

Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com>

* fix: include request_headers in MockHTTPClient::clear()

The suggestion to use client->clear() instead of
client->request_headers.items.clear() exposed that clear() only
reset request_body. Update it to also clear request_headers so the
heartbeat session-header test validates fresh headers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address review feedback from xlamorlette

- Rename environment::set to set_if_not_set for clarity
- Add config registry link and comment for _DD_ROOT_CPP_SESSION_ID
- Add backward-compatible 3-param TracerSignature constructor

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: move config registry link to top of file, remove inline link

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: remove inline comment on _DD_ROOT_CPP_SESSION_ID

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: simplify telemetry init() using 3-param TracerSignature constructor

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: fix clang-format violation in telemetry.cpp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address review feedback from xlamorlette

- Rename constructor params to match member names
- Rename rid to session_rid in session header tests
- Use 3-param TracerSignature constructor where root_session == runtime_id

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: replace env var with singleton for root session ID

Replace _DD_ROOT_CPP_SESSION_ID environment variable propagation with a
thread-safe singleton (std::call_once). The singleton is immutable after
first init, making it safe across forks.

- Add set_root_session_id/get_root_session_id in tracer_config
- Remove _DD_ROOT_CPP_SESSION_ID from environment registry
- Remove environment::set_if_not_set (no longer needed)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: store session_id in local var, simplify app_started() via send_payload()

Address reviewer nits:
- Cache sig.runtime_id.string() in set_session_headers to avoid double call
- Replace app_started() body with send_payload("app-started", ...) since
  send_payload is a superset with additional response metrics

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: move root session ID singleton to internal header

Move set/get into datadog::tracing::root_session_id namespace in
src/datadog/root_session_id.h (internal header), matching the codebase
pattern of keeping implementation details out of public headers.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add root_session_id.h to Bazel BUILD file

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: move root session ID singleton internals to .cpp file

Hide instance() and flag() in an anonymous namespace in
root_session_id.cpp, matching the telemetry Meyer's singleton pattern.
Only set() and get() are exposed in the header.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: revert formatting-only changes in environment.cpp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: revert formatting-only changes in tracer_config.cpp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: revert unnecessary changes in test_remote_config.cpp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* Revert "chore: revert unnecessary changes in test_remote_config.cpp"

This reverts commit 212fc67.

* chore: revert test_remote_config.cpp to main (no functional changes needed)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: restore original TracerSignature style in test_telemetry.cpp

Keep inline comment style matching main for unchanged test sections.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: revert unnecessary changes in test_datadog_agent.cpp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: replace std::call_once with mutex+bool guard in root session singleton

std::call_once can throw std::system_error on some glibc versions due
to pthread_once issues. Use a simple mutex+bool guard instead.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* simplify: use static local singleton pattern for root session ID

Match the codebase's existing singleton pattern (static local variable).
No mutex or call_once needed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: add mutex to root session ID singleton for thread safety

Protect concurrent set() calls with std::mutex, matching the codebase's
standard pattern for shared state protection.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: use std::atomic for root session ID singleton guard

Replace std::mutex with std::atomic<bool> compare_exchange_strong to
avoid potential pthread issues in Docker/CI environments.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* revert: restore original app_started() implementation

Revert the app_started() → send_payload() simplification as it was out
of scope for this PR. Keep only the session headers addition.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: simplify root session ID to single get_or_init() singleton

Replace separate set()/get() with a single get_or_init(runtime_id) that
initializes on first call and returns the stored value on subsequent
calls. Remove root_session_id from TracerConfig/FinalizedTracerConfig
— the singleton is now the sole source of truth, read directly in
Tracer construction.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* test: add root_session_id singleton test

Verify get_or_init returns the first runtime ID on subsequent calls
with different values (first-writer-wins semantics).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* refactor: move get_or_init into TracerSignature 3-param constructor

The 3-param constructor now calls root_session_id::get_or_init internally,
so every TracerSignature construction via the short form goes through the
singleton. Tracer no longer needs to call get_or_init directly.

Session header tests use the 4-param constructor to control values
directly without depending on singleton state.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: fix fork test to compare against actual singleton value

The singleton may already be set from a prior test case. Compare
the child's result against what get_or_init actually returned,
not the runtime ID passed in this test.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: acquire root_session_id from singleton in session header tests

Use root_session_id::get_or_init to acquire the root session ID and
use it throughout the session header test cases.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* revert: move get_or_init back to tracer.cpp, remove tracer_signature.cpp

Keep the 3-param TracerSignature constructor as a simple inline
delegating constructor. The get_or_init call stays in tracer.cpp
where the Tracer is constructed.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: fix clang-format violations in test files

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: remove test_root_session_id.cpp

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: remove unnecessary comments

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: address review feedback

- Simplify singleton to static const Meyer's pattern, remove .cpp file
- Use C++17 compound namespaces in root_session_id.h
- Rename sig -> signature in telemetry_impl.cpp
- Remove singleton usage from tests, use 3-param constructor for match
- Add blank lines between constructors in tracer_signature.h
- Fix extra spaces in test Telemetry init alignment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: remove extra spaces in test Telemetry init alignment

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: restore clang-format alignment in test_telemetry.cpp

clang-format requires the extra spaces for argument alignment.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* style: rename sig to tracer_signature to fix clang-format alignment

Using the longer variable name avoids clang-format's column alignment
padding while matching the naming convention in the rest of the file.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* feat: re-add root_session_id to TracerConfig for integration seeding

Integrations (nginx, httpd, kong) need to set root_session_id in the
master process before workers fork. The Tracer passes it to get_or_init,
falling back to runtime_id if not provided.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: match field order in TracerConfig/FinalizedTracerConfig, remove redundant if checks

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Zach Montoya <zach.montoya@datadoghq.com>

Author: 3 people

BUILD.bazel

@@ -45,6 +45,7 @@ cc_library(
         "src/datadog/propagation_style.cpp",
         "src/datadog/random.cpp",
         "src/datadog/random.h",
+        "src/datadog/root_session_id.h",
         "src/datadog/rate.cpp",
         "src/datadog/remote_config/product.cpp",
         "src/datadog/remote_config/remote_config.cpp",

include/datadog/environment.h

@@ -20,6 +20,8 @@ namespace environment {
 
 // Central registry for supported environment variables.
 // All configurations must be registered here.
+// See also:
+// https://feature-parity.us1.prod.dog/configurations?viewType=configurations
 //
 // This registry is the single source of truth for:
 //   - env variable name allowlist (`include/datadog/environment.h`)

include/datadog/tracer_config.h

@@ -189,6 +189,11 @@ struct TracerConfig {
   // This option is ignored if `resource_renaming_enabled` is not `true`.
   Optional<bool> resource_renaming_always_simplified_endpoint;
 
+  // Root session ID for stable telemetry correlation across forked workers.
+  // Integrations (nginx, httpd, kong) should set this in the master process
+  // before workers fork so all Tracers share the same root.
+  Optional<std::string> root_session_id;
+
   /// A mapping of process-specific tags used to uniquely identify processes.
   ///
   /// The `process_tags` map allows associating arbitrary string-based keys and
@@ -225,6 +230,7 @@ class FinalizedTracerConfig final {
   bool log_on_startup;
   bool generate_128bit_trace_ids;
   Optional<RuntimeID> runtime_id;
+  Optional<std::string> root_session_id;
   Clock clock;
   std::string integration_name;
   std::string integration_version;

include/datadog/tracer_signature.h

@@ -33,17 +33,27 @@ 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)
-      : runtime_id(id),
-        default_service(std::move(service)),
-        default_environment(std::move(environment)),
+
+  TracerSignature(RuntimeID runtime_id, std::string default_service,
+                  std::string default_environment)
+      : TracerSignature(runtime_id, runtime_id.string(),
+                        std::move(default_service),
+                        std::move(default_environment)) {}
+
+  TracerSignature(RuntimeID runtime_id, std::string root_session_id,
+                  std::string default_service, std::string default_environment)
+      : runtime_id(runtime_id),
+        root_session_id(std::move(root_session_id)),
+        default_service(std::move(default_service)),
+        default_environment(std::move(default_environment)),
         library_version(tracer_version),
         library_language("cpp"),
         library_language_version(DD_TRACE_STRINGIFY(__cplusplus), 6) {}

src/datadog/root_session_id.h

@@ -0,0 +1,12 @@
+#pragma once
+
+#include <string>
+
+namespace datadog::tracing::root_session_id {
+
+inline const std::string& get_or_init(const std::string& runtime_id) {
+  static const std::string id = runtime_id;
+  return id;
+}
+
+}  // namespace datadog::tracing::root_session_id

src/datadog/telemetry/telemetry_impl.cpp

@@ -60,6 +60,15 @@ HTTPClient::URL make_telemetry_endpoint(HTTPClient::URL url) {
   return url;
 }
 
+void set_session_headers(DictWriter& headers,
+                         const tracing::TracerSignature& signature) {
+  const auto& session_id = signature.runtime_id.string();
+  headers.set("DD-Session-ID", session_id);
+  if (signature.root_session_id != session_id) {
+    headers.set("DD-Root-Session-ID", signature.root_session_id);
+  }
+}
+
 void cancel_tasks(std::vector<tracing::EventScheduler::Cancel>& tasks) {
   for (auto& cancel_task : tasks) {
     cancel_task();
@@ -309,13 +318,15 @@ 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,
+                     &signature = 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");
+    set_session_headers(headers, signature);
     if (debug_enabled) {
       headers.set("DD-Telemetry-Debug-Enabled", "true");
     }
@@ -363,14 +374,16 @@ 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,
+                                &signature =
+                                    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);
+    set_session_headers(headers, signature);
     if (debug_enabled) {
       headers.set("DD-Telemetry-Debug-Enabled", "true");
     }

src/datadog/tracer.cpp

@@ -24,6 +24,7 @@
 #include "msgpack.h"
 #include "platform_util.h"
 #include "random.h"
+#include "root_session_id.h"
 #include "span_data.h"
 #include "span_sampler.h"
 #include "tags.h"
@@ -48,8 +49,10 @@ Tracer::Tracer(const FinalizedTracerConfig& config,
     : logger_(config.logger),
       runtime_id_(config.runtime_id ? *config.runtime_id
                                     : RuntimeID::generate()),
-      signature_{runtime_id_, config.defaults.service,
-                 config.defaults.environment},
+      signature_{runtime_id_,
+                 root_session_id::get_or_init(
+                     config.root_session_id.value_or(runtime_id_.string())),
+                 config.defaults.service, config.defaults.environment},
       config_manager_(std::make_shared<ConfigManager>(config)),
       collector_(/* see constructor body */),
       span_sampler_(

src/datadog/tracer_config.cpp

@@ -403,10 +403,8 @@ Expected<FinalizedTracerConfig> finalize_config(const TracerConfig &user_config,
     final_config.injection_styles.erase(it);
   }
 
-  if (user_config.runtime_id) {
-    final_config.runtime_id = user_config.runtime_id;
-  }
-
+  final_config.runtime_id = user_config.runtime_id;
+  final_config.root_session_id = user_config.root_session_id;
   final_config.process_tags = user_config.process_tags;
 
   auto agent_finalized =

test/mocks/http_clients.h

@@ -41,7 +41,10 @@ struct MockHTTPClient : public HTTPClient {
   ErrorHandler on_error_;
   std::string request_body;
 
-  void clear() { request_body = ""; }
+  void clear() {
+    request_body = "";
+    request_headers.items.clear();
+  }
 
   Expected<void> post(
       const URL&, HeadersSetter set_headers, std::string body,

test/telemetry/test_telemetry.cpp

@@ -366,6 +366,67 @@ 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 session_rid = RuntimeID::generate();
+    const TracerSignature tracer_signature(session_rid, "testsvc", "test");
+
+    Telemetry telemetry{
+        *finalize_config(), tracer_signature, logger, client, scheduler, *url};
+
+    auto it = client->request_headers.items.find("DD-Session-ID");
+    REQUIRE(it != client->request_headers.items.end());
+    CHECK(it->second == session_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 session_rid = RuntimeID::generate();
+    auto root_rid = RuntimeID::generate();
+    const TracerSignature tracer_signature(session_rid, root_rid.string(),
+                                           "testsvc", "test");
+
+    Telemetry telemetry{
+        *finalize_config(), tracer_signature, 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 == session_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 session_rid = RuntimeID::generate();
+    auto root_rid = RuntimeID::generate();
+    const TracerSignature tracer_signature(session_rid, root_rid.string(),
+                                           "testsvc", "test");
+
+    Telemetry telemetry{
+        *finalize_config(), tracer_signature, logger, client, scheduler, *url};
+
+    client->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 == session_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;