Document the design in package-info (client-side stats) by dougqh · Pull Request #12082 · DataDog/dd-trace-java

dougqh · 2026-07-27T16:36:31Z

What Does This Do

Adds a package-info.java for datadog.trace.common.metrics — a two-minute mental model of the re-architected client-side-stats (CSS) pipeline for newcomers to the package.

Documentation only; no production code changes.

Motivation

Document the new architecture of client-side stats -- including thread safety, config update model, and publishing cycle

Additional Notes

At-a-glance ASCII flow diagram — producer threads → MPSC inbox → single aggregator thread (canonicalize → fold → flush).
Threading model — the load-bearing single-writer invariant (aggregator thread owns all mutable state; cross-thread mutations funnel through the inbox).
The cycle — per-interval aggregate then flush via MetricWriter (msgpack / OTLP); buckets are deltas.
Cardinality invariant — bound distinct values per tag → collapse overflow into a sentinel → report collapses per cycle, so the bounding is observable without becoming unbounded itself.
The three handler families — CoreHandlers / PeerTagSchema / AdditionalTagsSchema.

The per-class javadocs already carry the mechanics; this is deliberately the top-level shape, not a reference — kept to a short prose read per reviewer feedback that an earlier exhaustive draft was too dense.

Stacking

Stacked on #11402 (the CSS re-architecture this documents). Rebase --onto master once #11402 squash-merges.

🤖 Generated with Claude Code

datadog-datadog-prod-us1-2 · 2026-07-27T16:52:25Z

🎯 Code Coverage (details)
• Patch Coverage: 100.00%
• Overall Coverage: 57.68% (-0.03%)

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

🔗 Commit SHA: f720209 | Docs | Datadog PR Page | Give us feedback!}

datadog-datadog-prod-us1-2

More details

The PR adds only package-level Javadoc; it introduces no runtime path or behavioral change. The documented CSS invariants match the surrounding aggregator, schema, and writer implementation, and deterministic diff/link checks passed; Gradle compile, test, and Javadoc tasks could not run because the sandbox lacks network access to the wrapper distribution and Java 25 toolchain.

Was this helpful? React 👍 or 👎

_{Open Bits AI session}

_{🤖 Datadog Autotest · Commit 50cecf3 · What is Autotest? · @DataDog review to ask questions · Any feedback? Reach out in #autotest}

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:50cecf306a

ℹ️ About Codex in GitHub

Codex has been enabled to automatically 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 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Add a package-info.java for datadog.trace.common.metrics giving a two-minute mental model of the re-architected client-side-stats (CSS) pipeline: an at-a-glance ASCII flow diagram plus prose on the single-writer threading model, the per-interval aggregate/flush cycle, the bound->sentinel->report-per-cycle cardinality invariant, and the three cardinality-handler families. The per-class javadocs carry the mechanics; this is the top-level shape for a newcomer. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

dd-octo-sts · 2026-07-28T13:48:03Z

🟢 Java Benchmark SLOs — All performance SLOs passed

Suite	Status
Startup	🟢 pass

SLO thresholds are defined here based on automatically generated metrics. A warning is raised when results are within 5% of the threshold.

PR vs. master results

Scenario	Candidate	master	Δ (95% CI of mean)
startup:insecure-bank:iast:Agent	14.02 s	13.99 s	[-0.7%; +1.1%] (no difference)
startup:insecure-bank:tracing:Agent	12.88 s	12.99 s	[-1.5%; -0.3%] (maybe better)
startup:petclinic:appsec:Agent	16.79 s	16.09 s	[-0.0%; +8.8%] (no difference)
startup:petclinic:iast:Agent	16.44 s	16.89 s	[-6.9%; +1.6%] (no difference)
startup:petclinic:profiling:Agent	16.69 s	16.80 s	[-1.9%; +0.6%] (no difference)
startup:petclinic:sca:Agent	16.84 s	16.33 s	[-1.4%; +7.6%] (no difference)
startup:petclinic:tracing:Agent	16.10 s	15.91 s	[+0.2%; +2.2%] (maybe worse)

Commit:f720209d · CI Pipeline · Benchmarking Platform UI

Load and DaCapo benchmarks can be triggered manually in the GitLab pipeline. Results will appear in the Benchmarking Platform UI after completion.

- report() resets entries (retained for reuse; stale expunged over cycles), it does not clear the whole table each interval - OTLP flushes to the OTLP endpoint, not the agent; only msgpack goes to the agent - core string fields use PropertyCardinalityHandler, peer/additional tags use TagCardinalityHandler; primitive key fields are copied directly Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Adopt bric3's suggested intro: drop the CSS acronym and the span-label tuple in favor of a plainer sentence, and state the MetricWriter destinations (msgpack to the Datadog Agent, OTLP to the configured OTLP endpoint) up front. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Replace the single-producer/aggregator sketch with bric3's suggested diagram: show the MPSC inbox as the boundary -- app/producer threads enqueue SpanSnapshots, control threads enqueue SignalItems -- and the aggregator thread as the sole owner handling both, enumerating the Report/Clear/Stop signals. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

dd-octo-sts · 2026-07-29T14:17:18Z

/merge

gh-worker-devflow-routing-ef8351 · 2026-07-29T14:17:21Z

View all feedbacks in Devflow UI.

2026-07-29 14:17:21 UTC ℹ️ Start processing command /merge

2026-07-29 14:17:26 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 1h (p90).

2026-07-29 16:18:13 UTC ❌ MergeQueue: The build pipeline has timeout

The merge request has been interrupted because the build 7998100235238140818 took longer than expected. The current limit for the base branch 'master' is 120 minutes.

dd-octo-sts · 2026-08-17T18:34:20Z

/merge

gh-worker-devflow-routing-ef8351 · 2026-08-17T18:34:24Z

View all feedbacks in Devflow UI.

2026-08-17 18:34:24 UTC ℹ️ Start processing command /merge

2026-08-17 18:34:28 UTC ℹ️ MergeQueue: pull request added to the queue

The expected merge time in master is approximately 2h (p90).

2026-08-17 19:22:34 UTC ℹ️ MergeQueue: This merge request was merged

dougqh added comp: metrics Metrics tag: ai generated Largely based on code generated by an AI or LLM tag: no release notes Changes to exclude from release notes type: documentation labels Jul 27, 2026

dougqh requested a review from bric3 July 27, 2026 16:49

dougqh marked this pull request as ready for review July 27, 2026 16:53

dougqh requested a review from a team as a code owner July 27, 2026 16:53

dougqh requested a review from ygree July 27, 2026 16:53

datadog-datadog-prod-us1-2Bot reviewed Jul 27, 2026
View reviewed changes

chatgpt-codex-connectorBot reviewed Jul 27, 2026
View reviewed changes

Comment threaddd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated
Comment threaddd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated
Comment threaddd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

Base automatically changed from dougqh/metrics-arbitrary-tags to masterJuly 27, 2026 21:06

gh-worker-dd-mergequeue-cf854dBot requested a review from a team as a code owner July 27, 2026 21:06

dougqh force-pushed the dougqh/css-package-doc branch from 50cecf3 to 1f7848cCompare July 28, 2026 13:13

bric3 reviewed Jul 28, 2026
View reviewed changes

Comment threaddd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated
Comment threaddd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated
Comment threaddd-trace-core/src/main/java/datadog/trace/common/metrics/package-info.java Outdated

dougqhand others added 2 commits July 28, 2026 13:33

dougqh changed the title ~~Document the client-side-stats package design (package-info)~~Document the design in package-info (client-side stats)Jul 28, 2026

bric3 approved these changes Jul 29, 2026
View reviewed changes

dougqh added this pull request to the merge queue Jul 29, 2026

github-merge-queueBot removed this pull request from the merge queue due to failed status checks Jul 29, 2026

dougqh added this pull request to the merge queue Aug 17, 2026

github-merge-queueBot removed this pull request from the merge queue due to failed status checks Aug 17, 2026

gh-worker-dd-mergequeue-cf854dBot merged commit c4a9614 into masterAug 17, 2026
785 of 788 checks passed

gh-worker-dd-mergequeue-cf854dBot deleted the dougqh/css-package-doc branch August 17, 2026 19:22

github-actionsBot added this to the 1.66.0 milestone Aug 17, 2026

Navigation Menu

Uh oh!

Document the design in package-info (client-side stats) - #12082

Document the design in package-info (client-side stats)#12082
gh-worker-dd-mergequeue-cf854d[bot] merged 4 commits into
masterfrom
dougqh/css-package-doc

dougqh commented Jul 27, 2026•
edited
Loading

Uh oh!

datadog-datadog-prod-us1-2Bot commented Jul 27, 2026•
edited by datadog-official Bot
Loading

Uh oh!

datadog-datadog-prod-us1-2Bot left a comment

Uh oh!

chatgpt-codex-connectorBot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dd-octo-stsBot commented Jul 28, 2026•
edited
Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dd-octo-stsBot commented Jul 29, 2026

Uh oh!

gh-worker-devflow-routing-ef8351Bot commented Jul 29, 2026•
edited
Loading

Uh oh!

Uh oh!

dd-octo-stsBot commented Aug 17, 2026

Uh oh!

Uh oh!

gh-worker-devflow-routing-ef8351Bot commented Aug 17, 2026•
edited
Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

dougqh commented Jul 27, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Does This Do

Motivation

Additional Notes

Contents

Stacking

Uh oh!

datadog-datadog-prod-us1-2Bot commented Jul 27, 2026• edited by datadog-official BotLoading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

datadog-datadog-prod-us1-2Bot left a comment

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connectorBot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dd-octo-stsBot commented Jul 28, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🟢 Java Benchmark SLOs — All performance SLOs passed

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dd-octo-stsBot commented Jul 29, 2026

Uh oh!

gh-worker-devflow-routing-ef8351Bot commented Jul 29, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

dd-octo-stsBot commented Aug 17, 2026

Uh oh!

Uh oh!

gh-worker-devflow-routing-ef8351Bot commented Aug 17, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

dougqh commented Jul 27, 2026•
edited
Loading

datadog-datadog-prod-us1-2Bot commented Jul 27, 2026•
edited by datadog-official Bot
Loading

dd-octo-stsBot commented Jul 28, 2026•
edited
Loading

gh-worker-devflow-routing-ef8351Bot commented Jul 29, 2026•
edited
Loading

gh-worker-devflow-routing-ef8351Bot commented Aug 17, 2026•
edited
Loading