Memory-efficiency pass on ClientStatsAggregator + adversarial benchmark

[dougqh]

Summary

Sits on top of #11387. Reduces the per-entry footprint of the metrics aggregator, replaces HashMap-backed cardinality state with flat open-addressed tables, and adds three new JMH benchmarks (miss-path, full-pipeline, adversarial). All consumer-side changes; producer-thread hot path is unchanged or marginally faster.

Memory + design changes

• Fold AggregateMetric into AggregateEntry — drops one object header + reference field per entry (~16-24 bytes) and one indirection on the consumer's hot recording path.
• Peer tags as UTF8BytesString[] instead of List — saves the ArrayList wrapper allocation per miss; eliminates one iterator allocation per entry per report cycle.
• Cardinality handlers backed by flat open-addressed tables — no HashMap$Node allocations. At full cardinality saves ~7 KB on the 9 property handlers and ~16 KB per TagCardinalityHandler (cap 512). reset() is two Arrays.fill calls.
• Lazy error histogram — AggregateEntry.errorLatencies starts null; allocated on first error. Entries that never error save ~80 B of empty-histogram wrapper. At full table cap with sparse errors: ~150 KB reclaimed. The serializer writes a cached empty-histogram byte payload for entries that never errored, keeping the wire format unchanged.
• Raise per-field cardinality limits to match real workloads — RESOURCE 32→512, HTTP_ENDPOINT 32→256, OPERATION 64→128, SERVICE 32→128, TYPE 8→32, HTTP_METHOD 8→16, GRPC_STATUS_CODE 32→24. The old limits collapsed even a single-service web app to blocked_by_tracer on day one.

Benchmarks

• ClientStatsAggregatorMissPathBenchmark — pool of 4096 single-span traces with unique labels per op. Producer measures 57 ns/op + 96 B/op vs master's 305 ns/op + 399 B/op (5.3× faster, 4.2× less allocation per metrics-eligible span).
• TracePipelineBenchmark — end-to-end 3-span HTTP-style trace through CoreTracer with metrics aggregator wired in. Multi-threaded (8 producers, throughput mode). Shows the metrics subsystem improvements at the full-pipeline level: under varied labels, branch is +1.8% throughput and -734 B/op vs master (real signal; stable mode is identical, since the metrics-aggregator improvements only manifest on miss).
• AdversarialMetricsBenchmark — 8 threads × unique labels per op × random durations across 1ns-1s × random error/top-level flags. Bounded-design verification + drop counters at teardown.

Under adversarial load (this is the headline):

	master	this branch
Iteration 1 / 2 / 3 throughput	1.5M / 1.25M / 0.41M ops/s	~5.85M sustained
Iteration 3 GC time in a 15s window	18.6 s (multi-thread GC saturation)	~150 ms
Producer allocation	1,108 B/op	823 B/op
Aggregate-table drops	n/a	0
Inbox-full drops	(no counter)	~139M (76% backpressure)

Master enters a GC death spiral because it allocates MetricKey + DDCache lookups + LRUCache entries synchronously on every producer thread; this branch's producer/consumer split converts overflow into counted drops via onStatsInboxFull instead.

Docs

Updated docs/client_metrics_design.md with a new "Behavior under adversarial load" section, the AggregateMetric→AggregateEntry fold, and a benchmark summary that lists all four producer-side JMH benchmarks.

Test plan

• :dd-trace-core:test --tests "datadog.trace.common.metrics.*" — all pass (existing + updated cardinality test for the new 128-cap service handler).
• ClientStatsAggregatorMissPathBenchmark numbers reproduce locally (57 ns/op ± 8, 96 B/op).
• AdversarialMetricsBenchmark sustains throughput across iterations (no GC death spiral).
• Hit-path benchmarks within noise of pre-change numbers (no producer-thread regression).
• Wire format unchanged — SerializingMetricWriterTest and MetricsIntegrationTest pass with the lazy-error-histogram empty payload.

🤖 Generated with Claude Code