feat(datastreams): add span tagging and custom timestamp to TrackDataStreamsTransaction

[ericfirth]

Why

The first implementation of TrackDataStreamsTransaction recorded transaction checkpoints in the DSM processor but did nothing to tie them back to the active trace. Both dd-trace-js and dd-trace-java tag the active span with dsm.transaction.id and dsm.transaction.checkpoint whenever a transaction is tracked — this correlation is what allows the Datadog UI to link a specific transaction to the trace that processed it.

Additionally, callers sometimes know the relevant timestamp in advance (e.g. they are gathering data from an external source and want to checkpoint their pipeline with when the data came from). The processor already supports arbitrary timestamps internally, but there was no way to supply one from the public API, so every observation was silently stamped with time.Now().

What

• Span tagging — TrackDataStreamsTransaction now accepts ctx context.Context as its first argument. If the context carries an active span, it is tagged with dsm.transaction.id and dsm.transaction.checkpoint, matching the tag names used by dd-trace-java exactly. Passing context.Background() skips tagging with no overhead.

• Custom timestamp — New TrackDataStreamsTransactionAt(ctx, transactionID, checkpointName, t) lets callers supply the observation time. The processor buckets it into the correct 10-second window just like any other point. Useful when replaying or processing messages that carry their own timestamps.

• ext constants — ext.DSMTransactionID and ext.DSMTransactionCheckpoint are exported so integrations can reference the tag names without hardcoding strings.

Breaking change

TrackDataStreamsTransaction gains a leading context.Context parameter. The only known caller is on a branch; the update is straightforward — pass the context that was already in scope, or context.Background().

Test plan

• TestTrackDataStreamsTransactionTagsSpan — span in context receives both DSM tags
• TestTrackDataStreamsTransactionNoSpanInContextNoops — context with no span does not panic
• TestTrackDataStreamsTransactionAtDelegatesToProcessor — ...At variant reaches the processor
• TestTrackDataStreamsTransactionAtTagsSpan — ...At variant also tags the span
• TestTrackTransactionAtUsesProvidedTime — processor stores caller-supplied timestamp, not time.Now()
• go build ./... — clean build

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 89.47368% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 59.94%. Comparing base (89047df) to head (1462c6a).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
ddtrace/tracer/data_streams.go	84.61%	1 Missing and 1 partial ⚠️

Additional details and impacted files

Files with missing lines	Coverage Δ
internal/datastreams/processor.go	60.28% <100.00%> (-4.11%)	⬇️
ddtrace/tracer/data_streams.go	37.14% <84.61%> (+14.06%)	⬆️

... and 264 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pr-commenter]

Benchmarks

Benchmark execution time: 2026-03-09 17:18:37

Comparing candidate commit 4b37c67 in PR branch eric.firth/transaction-tracking-second-part with baseline commit cf61946 in branch main.

Found 0 performance improvements and 0 performance regressions! Performance is the same for 156 metrics, 8 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 ----------------------------------'

[kakkoyun]

Shall we keep the existing function to be backwards compatible here?

[ericfirth]

its currently used by 1 design partner and this is a feature they had asked for, so i think its okay that its not backwards compatible

[kakkoyun]

Ack.

[datadog-datadog-prod-us1]

✅ Tests

🎉 All green!

❄️ No new flaky tests detected
🧪 All tests passed

🎯 Code Coverage (details)
• Patch Coverage: 84.62%
• Overall Coverage: 59.21% (+3.47%)

_{This comment will be updated automatically if new data arrives.
🔗 Commit SHA: 4b37c67 | Docs | Datadog PR Page | Was this helpful? React with 👍/👎 or give us feedback!}

[darccio]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5cb113c495

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[mtoffl01]

Marking this as "request changes" until a clear decision has been made on whether to always add this metadata on spans or to do so only when DSM is enabled.