Wire per-component cardinality limits from Config by dougqh · Pull Request #11732 · DataDog/dd-trace-java

dougqh · 2026-06-24T17:03:50Z

What Does This Do

Wires per-component cardinality limits from Config into the client-side stats handlers, aligning with the Cardinality Limits RFC and the .NET implementation.

Motivation

Follows #11387, which shipped the handler infrastructure. This PR connects the config layer so operators can tune limits and the sentinel substitution is active by default.

Limit surface

Configurable limits (env var exposed)

Field	Env var	Default
Aggregate table (total distinct rows)	`DD_TRACE_STATS_CARDINALITY_LIMIT`	2048
`resource.name`	`DD_TRACE_STATS_RESOURCE_CARDINALITY_LIMIT`	1024
`http.endpoint`	`DD_TRACE_STATS_HTTP_ENDPOINT_CARDINALITY_LIMIT`	512
Per peer-tag value	`DD_TRACE_STATS_PEER_TAGS_CARDINALITY_LIMIT`	512

DD_TRACE_STATS_CARDINALITY_LIMIT is the new canonical name for the table cap; DD_TRACE_TRACER_METRICS_MAX_AGGREGATES is preserved as a backwards-compatible alias.

Fixed limits (hardcoded, no env var)

Fields with inherently low natural cardinality are enforced at their MetricCardinalityLimits defaults but are not user-configurable. The table cap above is the backstop for any unexpected growth.

Field	Default
`service`	32
`operation.name`	64
`span.type`	16
`span.kind`	8
`http.method`	16
`grpc.status_code`	24
`_dd.base_service`	16

Implementation notes

Single parameterized Config.getTraceStatsCardinalityLimit(tagName, defaultLimit) method; configurable fields also have explicit string constants in GeneralConfig for the config registry validator
All PropertyCardinalityHandler instances use useBlockedSentinel=true (the default 2-arg constructor); sentinel substitution is active
Configurable limit defaults and .NET defaults are aligned

Stacked on #11387 (merged).

Test plan

Existing CardinalityHandlerTest and AggregateEntryTest cover sentinel substitution behavior
Verify default limits match MetricCardinalityLimits constants
Confirm DD_TRACE_STATS_RESOURCE_CARDINALITY_LIMIT etc. are picked up at startup via Config

tag: no release note
tag: ai generated

🤖 Generated with Claude Code

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:75f72165fd

ℹ️ 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".

chatgpt-codex-connector · 2026-06-24T17:08:07Z

+ return configProvider.getInteger(
+ "trace.stats." + tagName + ".cardinality.limit", defaultLimit);


Validate stats cardinality limits before returning them
When any of the new DD_TRACE_STATS_*_CARDINALITY_LIMIT values is set to 0, a negative number, or a value above 2^29, this method returns it unchanged; the callers added in AggregateEntry and PeerTagSchema pass it directly into PropertyCardinalityHandler/TagCardinalityHandler, whose constructors throw for those ranges. In that misconfigured environment the stats classes fail initialization instead of falling back to the default/logging, so the accessor should reject invalid limits before handing them to the handlers.
Useful? React with 👍 / 👎.

In my ideal world, config would probably handle this and report a warning immediately at start-up.
Unfortunately, there's no precedence for that in config today.
I'm in full agreement with the sentiment, but I think that's better left to another PR.

chatgpt-codex-connector · 2026-06-24T17:08:07Z

+ "DD_TRACE_STATS_RESOURCE_CARDINALITY_LIMIT": [
+ {
+ "version": "A",
+ "type": "integer",


Use int for the new config metadata type
The supported-configurations metadata uses type: "int" for the existing integral settings (including the tracer metrics limits), while these ten new cardinality entries are the only ones using "integer". The local supported-configurations validation/publishing jobs consume this file, so the new configs can be rejected or omitted by downstream metadata consumers even though the agent code reads integers; please use int consistently for these entries.
Useful? React with 👍 / 👎.

Yup, int is used instead of integer in the file.

@mhlidd WDYT to add a test that will check types and failed if there someone made a typo?
OR probably we can support some sort of aliases like int, integer should be treated as the same type...
But I like the test better.

No need for aliasing, I'll just fix it. I'm curious why Claude decided to use the wrong value though.

Yep, Just thinking how to prevent issues in future.
Fir example if there will be a test - Claude with high probability will run it, test will fail, Claude will fix it.
I'm curious why Claude decided to use the wrong value though.
I think it is a nature of LLMs, somehow integer has a bigger weight in model that int and LLM produced wrong output.

dd-octo-sts · 2026-06-24T17:46:38Z

🟢 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	13.94 s	13.98 s	[-1.1%; +0.5%] (no difference)
startup:insecure-bank:tracing:Agent	12.86 s	13.00 s	[-1.7%; -0.4%] (maybe better)
startup:petclinic:appsec:Agent	17.39 s	17.19 s	[+0.1%; +2.2%] (maybe worse)
startup:petclinic:iast:Agent	17.26 s	17.00 s	[-2.8%; +5.8%] (no difference)
startup:petclinic:profiling:Agent	17.04 s	17.36 s	[-3.1%; -0.5%] (maybe better)
startup:petclinic:sca:Agent	17.42 s	16.67 s	[+0.2%; +8.8%] (maybe worse)
startup:petclinic:tracing:Agent	16.53 s	16.74 s	[-2.3%; -0.3%] (maybe better)

Commit:238144a8 · 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.

AlexeyKuznetsov-DD

LGTM, but:

Code like:

Config.get()
.getTraceStatsCardinalityLimit(
"peer_tag", MetricCardinalityLimits.PEER_TAG_VALUE))

looks a bit noisy, probably can be improved if refactored to enum?
2. JSON descriptor should be fixed integer -> int.

AlexeyKuznetsov-DD · 2026-06-29T19:41:49Z

+ "resource",
+ Config.get().getTraceStatsCardinalityLimit("resource", MetricCardinalityLimits.RESOURCE));


QQ: just curious if this MetricCardinalityLimits can be an enum and no need to pass string and int const. Just enum and get the rest from it where needed.

Yeah, we might be able to do that. The only complication is that we might have to move the enum next to Config.

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

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

dd-octo-sts · 2026-07-01T12:48:22Z

Hi! 👋 Thanks for your pull request! 🎉

To help us review it, please make sure to:

Add at least one type, and one component or instrumentation label to the pull request

If you need help, please check our contributing guidelines.

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

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

…oint, add table alias - Rename DD_TRACE_STATS_PEER_TAG_CARDINALITY_LIMIT -> DD_TRACE_STATS_PEER_TAGS_CARDINALITY_LIMIT to match .NET naming (plural) - Raise DD_TRACE_STATS_HTTP_ENDPOINT_CARDINALITY_LIMIT default 64 -> 512 to match .NET - Add DD_TRACE_STATS_CARDINALITY_LIMIT as the canonical name for the aggregate table cap, aliasing the older DD_TRACE_TRACER_METRICS_MAX_AGGREGATES - Add explicit string constants for all 10 per-field cardinality limit keys in GeneralConfig so the config registry validator can find them Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

SERVICE, OPERATION, SERVICE_SOURCE, TYPE, SPAN_KIND, HTTP_METHOD, and GRPC_STATUS_CODE have naturally low cardinality -- the aggregate table cap (DD_TRACE_STATS_CARDINALITY_LIMIT) is sufficient backstop. Aligns the public config surface with .NET (resource, http_endpoint, peer_tags, table cap). Hardcoded defaults in MetricCardinalityLimits remain; config knobs can be added later if a customer needs to tune them. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…config key detection Fields with hardcoded limits (service, operation, type, span_kind, http_method, grpc_status_code, service_source) now pass their MetricCardinalityLimits constant directly to PropertyCardinalityHandler instead of going through Config.getTraceStatsCardinalityLimit. This prevents the test harness from flagging DD_TRACE_STATS_SERVICE_CARDINALITY_LIMIT etc. as unsupported config keys. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The central registry has no alias for this key; the local entry must match. The code-level alias (Config.java reads DD_TRACE_TRACER_METRICS_MAX_AGGREGATES as a fallback) is unaffected. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Version A must match the central registry exactly (no aliases). The DD_TRACE_TRACER_METRICS_MAX_AGGREGATES alias is Java-specific, so it belongs in version B — matching the same pattern as DD_TRACE_STATS_COMPUTATION_ENABLED aliasing DD_TRACE_TRACER_METRICS_ENABLED. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dd-octo-sts · 2026-07-14T11:51:41Z

/merge

gh-worker-devflow-routing-ef8351 · 2026-07-14T11:51:44Z

View all feedbacks in Devflow UI.

2026-07-14 11:51:44 UTC ℹ️ Start processing command /merge

2026-07-14 11:51:48 UTC ℹ️ MergeQueue: pull request added to the queue

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

2026-07-14 12:56:09 UTC ℹ️ MergeQueue: This merge request was merged

Resolved conflicts from #11732 merging while this branch was in flight: - MetricCardinalityLimits: take HTTP_ENDPOINT=512 from master, keep ADDITIONAL_TAG_VALUE=512 - PropertyHandlers: apply configurable/fixed handler split (resource, http_endpoint configurable; service, operation, type, span_kind, http_method, grpc_status_code, service_source hardcoded) - PeerTagSchema: take configurable peer_tags limit from master; keep resetHandlers with HealthMetrics - PropertyCardinalityHandler / TagCardinalityHandler: take "collapsed:" StatsD prefix and tracerBlockedValue() naming from master; keep warnedThisCycle field from #11402 - supported-configurations.json: take master's clean int-typed entries, keep ADDITIONAL_TAGS key - Config.java: import both TRACE_STATS_ADDITIONAL_TAGS and TRACE_STATS_CARDINALITY_LIMIT Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dougqh requested review from a team as code owners June 24, 2026 17:03

dougqh requested review from AlexeyKuznetsov-DD and ygree and removed request for a teamJune 24, 2026 17:03

dd-octo-stsBot added the tag: ai generated Largely based on code generated by an AI or LLM label Jun 24, 2026

chatgpt-codex-connectorBot reviewed Jun 24, 2026
View reviewed changes

dougqh mentioned this pull request Jun 25, 2026
Per-component / tag cardinality limits in client-side stats #11387
Merged
3 tasks

AlexeyKuznetsov-DD approved these changes Jun 29, 2026
View reviewed changes

dougqh force-pushed the dougqh/cardinality-limits-config branch 2 times, most recently from 1741d4f to b23f870Compare July 1, 2026 01:58

This comment has been minimized.
Sign in to view

dougqh force-pushed the dougqh/cardinality-limits-config branch from b23f870 to 2418d84Compare July 1, 2026 02:31

Base automatically changed from dougqh/control-tag-cardinality to masterJuly 1, 2026 05:12

dougqhand others added 3 commits July 1, 2026 08:46

Wire per-component cardinality limits from Config per Cardinality Lim…
280e058
…its RFC Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Raise RESOURCE cardinality limit to 1024 to avoid premature collapse
78a7f0d
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Apply spotless formatting
5b550dd
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dougqh force-pushed the dougqh/cardinality-limits-config branch from 2418d84 to 5b550ddCompare July 1, 2026 12:48

dougqh added comp: core Tracer core type: feature Enhancements and improvements labels Jul 1, 2026

dougqhand others added 2 commits July 1, 2026 13:08

Apply spotless formatting to Config.java
c50dd1d
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Fix supported-configurations.json: use int not integer for cardinalit…
e558d99
…y limits Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

bric3 approved these changes Jul 3, 2026
View reviewed changes

dougqhand others added 5 commits July 7, 2026 15:09

Merge branch 'master' into dougqh/cardinality-limits-config
f7a3104

dougqhand others added 3 commits July 13, 2026 14:27

Merge branch 'master' into dougqh/cardinality-limits-config
bac5cc3

Merge branch 'master' into dougqh/cardinality-limits-config
238144a

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

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

gh-worker-dd-mergequeue-cf854dBot merged commit 41fffe8 into masterJul 14, 2026
586 checks passed

gh-worker-dd-mergequeue-cf854dBot deleted the dougqh/cardinality-limits-config branch July 14, 2026 12:56

github-actionsBot added this to the 1.65.0 milestone Jul 14, 2026

		return configProvider.getInteger(
		"trace.stats." + tagName + ".cardinality.limit", defaultLimit);

		"resource",
		Config.get().getTraceStatsCardinalityLimit("resource", MetricCardinalityLimits.RESOURCE));

Uh oh!

Conversation

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

Uh oh!

What Does This Do

Motivation

Limit surface

Configurable limits (env var exposed)

Fixed limits (hardcoded, no env var)

Implementation notes

Test plan

Uh oh!

chatgpt-codex-connectorBot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connectorBotJun 24, 2026

Choose a reason for hiding this comment

Uh oh!

dougqhJul 1, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connectorBotJun 24, 2026

Choose a reason for hiding this comment

Uh oh!

mhliddJun 24, 2026

Choose a reason for hiding this comment

Uh oh!

AlexeyKuznetsov-DDJul 1, 2026

Choose a reason for hiding this comment

Uh oh!

dougqhJul 1, 2026

Choose a reason for hiding this comment

Uh oh!

AlexeyKuznetsov-DDJul 1, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dd-octo-stsBot commented Jun 24, 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!

AlexeyKuznetsov-DD left a comment

Choose a reason for hiding this comment

Uh oh!

AlexeyKuznetsov-DDJun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dougqhJun 29, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

dd-octo-stsBot commented Jul 1, 2026

Uh oh!

dd-octo-stsBot commented Jul 14, 2026

Uh oh!

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

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dougqh commented Jun 24, 2026•
edited
Loading

AlexeyKuznetsov-DDJul 1, 2026•
edited
Loading

dd-octo-stsBot commented Jun 24, 2026•
edited
Loading

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