Implement stable session identifier headers for telemetry by khanayan123 · Pull Request #295 · DataDog/dd-trace-cpp

khanayan123 · 2026-03-20T18:50:46Z

Summary

Implements the Stable Service Instance Identifier RFC for the C++ SDK.

Adds DD-Session-ID (= runtime_id) and conditional DD-Root-Session-ID headers to all telemetry requests (app-started, heartbeats, app-closing, etc.)
DD-Root-Session-ID is only sent when it differs from DD-Session-ID (i.e., in child processes)
Root session ID is stored in a Meyer's singleton (static const local), set once by the first Tracer to initialize. Immutable after init, so fork-safe.
Fork propagation is automatic — the singleton value persists in child process memory

Integration testing note

System-tests for cpp_nginx and cpp_httpd cannot validate session headers until the downstream modules (nginx-datadog, httpd-datadog) release a version that includes these dd-trace-cpp changes. The system-tests manifest entries remain missing_feature until then. Unit tests in this PR validate the implementation directly.

Companion system-tests PR: DataDog/system-tests#6510

pr-commenter · 2026-03-20T19:06:46Z

Benchmarks

Benchmark execution time: 2026-04-10 17:51:36

Comparing candidate commit e61e812 in PR branch ayan.khan/stable-session-id-headers with baseline commit 967246f in branch main.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 1 metrics, 0 unstable metrics.

Explanation

This is an A/B test comparing a candidate commit's performance against that of a baseline commit. Performance changes are noted in the tables below as:

🟩 = significantly better candidate vs. baseline
🟥 = significantly worse candidate vs. baseline

We compute a confidence interval (CI) over the relative difference of means between metrics from the candidate and baseline commits, considering the baseline as the reference.

If the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD), the change is considered significant.

Feel free to reach out to #apm-benchmarking-platform on Slack if you have any questions.

More details about the CI and significant changes

You can imagine this CI as a range of values that is likely to contain the true difference of means between the candidate and baseline commits.

CIs of the difference of means are often centered around 0%, because often changes are not that big:

---------------------------------(------|---^--------)-------------------------------->
                              -0.6%    0%  0.3%     +1.2%
                                 |          |        |
         lower bound of the CI --'          |        |
sample mean (center of the CI) -------------'        |
         upper bound of the CI ----------------------'

As described above, a change is considered significant if the CI is entirely outside the configured SIGNIFICANT_IMPACT_THRESHOLD (or the deprecated UNCONFIDENCE_THRESHOLD).

For instance, for an execution time metric, this confidence interval indicates a significantly worse performance:

----------------------------------------|---------|---(---------^---------)---------->
                                       0%        1%  1.3%      2.2%      3.1%
                                                  |   |         |         |
       significant impact threshold --------------'   |         |         |
                      lower bound of CI --------------'         |         |
       sample mean (center of the CI) --------------------------'         |
                      upper bound of CI ----------------------------------'

datadog-prod-us1-6 · 2026-03-23T18:41:31Z

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 90.94%

_{This comment will be updated automatically if new data arrives.

🔗 Commit SHA: e61e812 | Docs | Datadog PR Page | Was this helpful? React with 👍/👎 or give us feedback!}

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 <[email protected]>

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

src/datadog/root_session_id.h

src/datadog/tracer_config.cpp

include/datadog/tracer_config.h

zacharycmontoya · 2026-04-06T23:08:08Z

src/datadog/tracer.cpp

-      signature_{runtime_id_, config.defaults.service,
-                 config.defaults.environment},
+      signature_{runtime_id_,
+                 config.root_session_id.value_or(runtime_id_.string()),


This is going to sound really weird, but I have a suggestion for updating this line of code. I think Method 1 Meyers Singleton from this Google AI response would be the best way to initialize the root session ID singleton. If we change the singleton implementation to align with that, then what we will be doing is:

We are guaranteed to have a valid runtime_id_ from the previous line

Right after we've set the runtime_id_ field, we try to initialize the Singleton root session ID with the runtime_id_ value, but the returned value will always be the singleton from the first runtime_id_ that was set

Once we get the singleton instance back, then we get the string value so we can assign it to the root_session_id field

Suggested change

config.root_session_id.value_or(runtime_id_.string()),

Singleton::getInstance(runtime_id_.string()).getValue(),

include/datadog/tracer_signature.h

test/telemetry/test_telemetry.cpp

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

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) <[email protected]>

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

xlamorlette-datadog

Please review the singleton implementation.

include/datadog/tracer_signature.h

xlamorlette-datadog · 2026-04-07T16:51:07Z

src/datadog/root_session_id.cpp

+
+#include <atomic>
+
+namespace datadog {


nit: rather use C++17 compound namespaces:

namespace datadog::tracing::root_session_id {

xlamorlette-datadog · 2026-04-07T16:51:50Z

src/datadog/root_session_id.cpp

+  return instance();
+}
+
+}  // namespace root_session_id


nit, pedantic, personal preference: I think such comments are noise

xlamorlette-datadog · 2026-04-07T16:56:50Z

src/datadog/root_session_id.cpp

+
+const std::string& get_or_init(const std::string& runtime_id) {
+  bool expected = false;
+  if (initialized().compare_exchange_strong(expected, true)) {


What do you need this, rather than implementing the singleton directly:

const std::string& get_or_init(const std::string& runtime_id) { static const std::string id = runtime_id; return id; }

By using inline in the header file, you can avoid the whole .cpp file:

inline const std::string& get_or_init(const std::string& runtime_id) { static const std::string id = runtime_id; return id; }

xlamorlette-datadog · 2026-04-07T17:02:15Z

src/datadog/telemetry/telemetry_impl.cpp

 }

+void set_session_headers(DictWriter& headers,
+                         const tracing::TracerSignature& sig) {


nit, clean code: use explicit names rather than uncommon abbreviation: signature
same line 322 and 378

xlamorlette-datadog · 2026-04-07T17:06:31Z

src/datadog/tracer.cpp

                                    : RuntimeID::generate()),
-      signature_{runtime_id_, config.defaults.service,
-                 config.defaults.environment},
+      signature_{runtime_id_,


nit: I agree one should generalize the usage of braces initialization calls, but here I think we should favor consistency with existing code

xlamorlette-datadog · 2026-04-07T17:08:53Z

test/telemetry/test_telemetry.cpp

+                              "test"};
+
+    Telemetry telemetry{*finalize_config(), sig, logger, client,
+                        scheduler,          *url};


nit: extra spaces; same below

xlamorlette-datadog · 2026-04-07T17:11:02Z

test/telemetry/test_telemetry.cpp

+
+  SECTION("root process: DD-Session-ID present, DD-Root-Session-ID absent") {
+    auto session_rid = RuntimeID::generate();
+    const TracerSignature sig{session_rid, session_rid.string(), "testsvc",


Use the 3 parameters constructor.

xlamorlette-datadog · 2026-04-07T17:14:03Z

test/telemetry/test_telemetry.cpp

+  auto url = HTTPClient::URL::parse("http://localhost:8000");
+
+  auto init_rid = RuntimeID::generate();
+  const auto& root_id = root_session_id::get_or_init(init_rid.string());


I think we should avoid calling the singleton in the unit tests.

- 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) <[email protected]>

zacharycmontoya

LGTM. Thanks for incorporating all our feedback, this is a much more simplified implementation now! Please also get approval @xlamorlette-datadog before merging.

xlamorlette-datadog · 2026-04-07T17:43:57Z

test/telemetry/test_telemetry.cpp

+                              "test"};
+
+    Telemetry telemetry{*finalize_config(), sig, logger, client,
+                        scheduler,          *url};


Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

clang-format requires the extra spaces for argument alignment. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

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) <[email protected]>

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) <[email protected]>

xlamorlette-datadog

lgtm

xlamorlette-datadog · 2026-04-10T13:56:56Z

include/datadog/tracer_config.h

+  // 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;


nit: we should have the same order for the fields in TracerConfig and FinalizedTracerConfig.

xlamorlette-datadog · 2026-04-10T14:00:55Z

src/datadog/tracer_config.cpp

    final_config.runtime_id = user_config.runtime_id;
  }

+  if (user_config.root_session_id) {


The test if (user_config.root_session_id) is useless since both fields are Optional and since final_config has just been instantiated with default values.
Same above for if (user_config.runtime_id).

xlamorlette-datadog · 2026-04-10T14:11:14Z

src/datadog/tracer.cpp

                                    : RuntimeID::generate()),
-      signature_{runtime_id_, config.defaults.service,
-                 config.defaults.environment},
+      signature_{runtime_id_,


xlamorlette-datadog · 2026-04-10T14:20:36Z

test/telemetry/test_telemetry.cpp

+    CHECK(root_it->second == root_rid.string());
+  }
+
+  SECTION("heartbeat includes session headers") {


I'm a bit puzzled: is is expected that the only difference with the child process: DD-Root-Session-ID present when different test is the following two calls:

client->clear(); scheduler->trigger_heartbeat();

But, after that, there is no difference in what is checked.

The test verifies headers persist on heartbeat requests (after client->clear() + trigger_heartbeat()), not just app-started. The assertions are intentionally identical same headers should appear on every telemetry event

…redundant if checks Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

khanayan123 had a problem deploying to dev March 23, 2026 18:35 — with GitHub Actions Failure

khanayan123 temporarily deployed to dev March 23, 2026 18:35 — with GitHub Actions Inactive

khanayan123 temporarily deployed to dev March 23, 2026 18:38 — with GitHub Actions Inactive

khanayan123 had a problem deploying to dev March 23, 2026 18:50 — with GitHub Actions Failure

khanayan123 temporarily deployed to dev March 23, 2026 18:50 — with GitHub Actions Inactive

khanayan123 temporarily deployed to dev March 23, 2026 18:53 — with GitHub Actions Inactive

khanayan123 temporarily deployed to dev March 23, 2026 18:58 — with GitHub Actions Inactive

khanayan123 temporarily deployed to dev March 23, 2026 19:02 — with GitHub Actions Inactive

khanayan123 force-pushed the ayan.khan/stable-session-id-headers branch from a3b7684 to 0e65a27 Compare March 25, 2026 13:33

khanayan123 force-pushed the ayan.khan/stable-session-id-headers branch from 85d241a to e40dd5d Compare March 25, 2026 14:35

Resync supported-configurations.json via config-inversion tool

3fab2f5

Co-Authored-By: Claude Sonnet 4.6 <[email protected]>

khanayan123 temporarily deployed to dev March 25, 2026 14:42 — with GitHub Actions Inactive

khanayan123 and others added 3 commits April 6, 2026 10:43

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

2ecd828

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) <[email protected]>

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

a8ed9b8

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) <[email protected]>

revert: restore original app_started() implementation

675ee33

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) <[email protected]>

zacharycmontoya reviewed Apr 6, 2026

View reviewed changes

src/datadog/root_session_id.h Outdated Show resolved Hide resolved

zacharycmontoya reviewed Apr 6, 2026

View reviewed changes

src/datadog/tracer_config.cpp Outdated Show resolved Hide resolved

zacharycmontoya reviewed Apr 6, 2026

View reviewed changes

include/datadog/tracer_config.h Outdated Show resolved Hide resolved

zacharycmontoya reviewed Apr 6, 2026

View reviewed changes

include/datadog/tracer_signature.h Show resolved Hide resolved

zacharycmontoya reviewed Apr 6, 2026

View reviewed changes

test/telemetry/test_telemetry.cpp Show resolved Hide resolved

khanayan123 and others added 9 commits April 6, 2026 21:09

test: add root_session_id singleton test

58602f5

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) <[email protected]>

fix: acquire root_session_id from singleton in session header tests

6664e2a

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) <[email protected]>

style: fix clang-format violations in test files

20467e1

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

chore: remove test_root_session_id.cpp

d808a0a

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

chore: remove unnecessary comments

dd3b4f8

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

xlamorlette-datadog reviewed Apr 7, 2026

View reviewed changes

zacharycmontoya approved these changes Apr 7, 2026

View reviewed changes

xlamorlette-datadog approved these changes Apr 7, 2026

View reviewed changes

khanayan123 and others added 3 commits April 7, 2026 13:50

fix: remove extra spaces in test Telemetry init alignment

1abb0ce

Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

style: restore clang-format alignment in test_telemetry.cpp

96a40da

clang-format requires the extra spaces for argument alignment. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

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

2ba87be

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) <[email protected]>

khanayan123 mentioned this pull request Apr 7, 2026

chore: validate stable session ID headers from dd-trace-cpp DataDog/nginx-datadog#345

Draft

khanayan123 mentioned this pull request Apr 8, 2026

feat: seed root session ID for stable telemetry headers DataDog/httpd-datadog#54

Draft

xlamorlette-datadog reviewed Apr 10, 2026

View reviewed changes

fix: match field order in TracerConfig/FinalizedTracerConfig, remove …

e61e812

…redundant if checks Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>

	config.root_session_id.value_or(runtime_id_.string()),
	Singleton::getInstance(runtime_id_.string()).getValue(),

Conversation

khanayan123 commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Integration testing note

Uh oh!

pr-commenter bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Benchmarks

Explanation

More details about the CI and significant changes

Uh oh!

datadog-prod-us1-6 bot commented Mar 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

xlamorlette-datadog left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zacharycmontoya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xlamorlette-datadog left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

khanayan123 commented Mar 20, 2026 •

edited

Loading

pr-commenter bot commented Mar 20, 2026 •

edited

Loading

datadog-prod-us1-6 bot commented Mar 23, 2026 •

edited

Loading