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

[dougqh]

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

Contents

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

🎯 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".

[dd-octo-sts]

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