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 <noreply@anthropic.com>

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

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) <noreply@anthropic.com>

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>

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>

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>

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>

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>

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

xlamorlette-datadog

Please review the singleton implementation.

include/datadog/tracer_signature.h

src/datadog/root_session_id.cpp

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

src/datadog/root_session_id.cpp

src/datadog/telemetry/telemetry_impl.cpp

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

test/telemetry/test_telemetry.cpp

- 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>

zacharycmontoya

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

test/telemetry/test_telemetry.cpp

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

clang-format requires the extra spaces for argument alignment. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

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>

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>

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.

src/datadog/tracer_config.cpp

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_,


test/telemetry/test_telemetry.cpp

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

khanayan123 · 2026-04-13T15:09:22Z

That's clang-format's alignment, CI's check-format step enforces it

#295 (comment)

xlamorlette-datadog · 2026-04-14T07:37:07Z

@khanayan123 You forgot to solve the following comments (that you agreed):

khanayan123 · 2026-04-14T13:23:10Z

@khanayan123 You forgot to solve the following comments (that you agreed):

https://github.com/DataDog/dd-trace-cpp/pull/295/changes#r3064713138

https://github.com/DataDog/dd-trace-cpp/pull/295/changes#r3046662390

Hmm, must've got lost in one of the commits. Opening up a follow up

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 <noreply@anthropic.com>

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

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) <noreply@anthropic.com>

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) <noreply@anthropic.com>

style: fix clang-format violations in test files

20467e1

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

chore: remove test_root_session_id.cpp

d808a0a

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

chore: remove unnecessary comments

dd3b4f8

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

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

test/telemetry/test_telemetry.cpp Outdated Show resolved Hide resolved

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) <noreply@anthropic.com>

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) <noreply@anthropic.com>

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) <noreply@anthropic.com>

khanayan123 mentioned this pull request Apr 7, 2026

feat: seed root session ID in master for stable telemetry headers DataDog/nginx-datadog#345

Open

khanayan123 mentioned this pull request Apr 8, 2026

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

Open

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) <noreply@anthropic.com>

khanayan123 mentioned this pull request Apr 14, 2026

fix: use parentheses for signature_ init to match existing style #307

Merged

	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!

zacharycmontoya Apr 6, 2026

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!

Uh oh!

xlamorlette-datadog Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

xlamorlette-datadog Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

xlamorlette-datadog Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

zacharycmontoya left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

xlamorlette-datadog left a comment

Choose a reason for hiding this comment

Uh oh!

xlamorlette-datadog Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

xlamorlette-datadog Apr 10, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

khanayan123 commented Apr 13, 2026

Uh oh!

xlamorlette-datadog commented Apr 14, 2026

Uh oh!

khanayan123 commented Apr 14, 2026

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