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>

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 team June 24, 2026 17:03

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

chatgpt-codex-connector Bot 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 b23f870 Compare 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 2418d84 Compare July 1, 2026 02:31

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

dougqh and 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 5b550dd Compare July 1, 2026 12:48

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

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

dougqh and others added 5 commits July 7, 2026 15:09

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

f7a3104

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

		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-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

dougqh Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

mhlidd Jun 24, 2026

Choose a reason for hiding this comment

Uh oh!

AlexeyKuznetsov-DD Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

dougqh Jul 1, 2026

Choose a reason for hiding this comment

Uh oh!

AlexeyKuznetsov-DD Jul 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-sts Bot 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-DD Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

dougqh Jun 29, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

dd-octo-sts Bot commented Jul 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dougqh commented Jun 24, 2026 •

edited

Loading

AlexeyKuznetsov-DD Jul 1, 2026 •

edited

Loading

dd-octo-sts Bot commented Jun 24, 2026 •

edited

Loading