DataDog · dougqh · Aug 26, 2026 · Jul 29, 2026 · Jul 29, 2026 · Jul 29, 2026
@@ -32,9 +32,10 @@ final class CardinalityLimitReporter {
 
   // Distinct blocked tag names in a window: 9 property fields + the configured peer tags + up to
   // AdditionalTagsSchema.MAX_ADDITIONAL_TAG_KEYS + base.service, with headroom for the brief
-  // overlap
-  // of old and new peer names across a schema rebuild. Fixed capacity; the table chains on overflow
-  // rather than dropping, so an underestimate only adds chain depth on this cold path.
+  // overlap of old and new peer names across a schema rebuild. Fixed, strict-cap capacity: if this
+  // is ever underestimated, excess distinct tags are silently dropped from the summary rather than
+  // recorded (see the null-check in record()) -- this is a cold, best-effort logging path, not a
+  // correctness-sensitive one.
-  // overlap of old and new peer names across a schema rebuild. Fixed, strict-cap capacity: if this
-  // is ever underestimated, excess distinct tags are silently dropped from the summary rather than
-  // recorded (see the null-check in record()) -- this is a cold, best-effort logging path, not a
-  // correctness-sensitive one.
+  // overlap during schema rebuilds. Extra distinct tags are omitted from this best-effort summary
+  // once the fixed bound is reached.
-  // overlap of old and new peer names across a schema rebuild. Fixed, strict-cap capacity: if this
-  // is ever underestimated, excess distinct tags are silently dropped from the summary rather than
-  // recorded (see the null-check in record()) -- this is a cold, best-effort logging path, not a
-  // correctness-sensitive one.
+  // overlap during schema rebuilds. Extra distinct tags are omitted from this best-effort summary
+  // once the fixed bound is reached.
   private static final int TAG_CAPACITY = 64;
 
   // Rough width of one "<tag>=<count>, " entry, used to pre-size the summary builder. Cold path, so
@@ -43,7 +44,8 @@ final class CardinalityLimitReporter {
 
   private final RatelimitedLogger rlLog;
   // Tag name -> blocked count accumulated since the last emitted summary.
-  private final Hashtable.D1<String, TagBlockEntry> blockedByTag = new Hashtable.D1<>(TAG_CAPACITY);
+  private final Hashtable.D1<String, TagBlockEntry> blockedByTag =
+      Hashtable.D1.createBounded(TagBlockEntry.class, TAG_CAPACITY);
 
   CardinalityLimitReporter() {
     this(new RatelimitedLogger(log, 5, MINUTES));
@@ -56,7 +58,10 @@ final class CardinalityLimitReporter {
   /** Records {@code count} values blocked for {@code tag} in the current reporting cycle. */
   void record(String tag, long count) {
     if (count > 0) {
-      blockedByTag.getOrCreate(tag, TagBlockEntry::new).count += count;
+      TagBlockEntry entry = blockedByTag.tryGetOrCreateOrNull(tag, TagBlockEntry::new);
+      if (entry != null) {
+        entry.count += count;
+      }
     }
   }
 

@@ -278,17 +278,19 @@ static CIEntry[] _create_flat(float loadFactor) {
       }
     }
     // Mirror the HashMap/TreeMap builds' second loop (UPPER_PREFIXES, suffix 0 & 2): 8 case-
-    // insensitive collisions. getOrCreate finds the already-present lower-case entry (a hit -> the
-    // create never fires, nothing allocates) and then the value is overwritten explicitly -- getOr-
-    // Create itself never updates an existing entry, so without this the FlatHashtable arm would do
+    // insensitive collisions. tryGetOrCreate finds the already-present lower-case entry (a hit, so
+    // the create never fires and nothing allocates) and then the value is overwritten explicitly --
+    // tryGetOrCreate itself never updates an existing entry, so without this the FlatHashtable arm
+    // would do
     // less work (and end up with different final values) than the maps' overwriting put(), a false
     // performance advantage. With the overwrite, all three create arms perform the same 24
     // operations and end up with the same final values.
     for (int suffix = 0; suffix < NUM_SUFFIXES; suffix += 2) {
       for (String prefix : UPPER_PREFIXES) {
         String key = prefix + "-" + suffix;
         CIEntry entry =
-            FlatHashtable.getOrCreate(table, key, CaseInsensitiveKeyStrategy.INSTANCE, CI_CREATE);
+            FlatHashtable.tryGetOrCreate(
+                table, key, CaseInsensitiveKeyStrategy.INSTANCE, CI_CREATE);
         entry.value = suffix + 1;
       }
     }

@@ -96,6 +96,34 @@
  * substitute for {@code HashMap} particularly for simple counter/tally use cases with a primitive
  * value, where avoiding the per-update boxing allocation pays off even on a JVM with much better
  * allocation handling than JDK 8 had.
+ *
+ * <p>Rerun on the capped/{@code State}-backed table (5 forks, 15 datapoints/method, Zulu 17.0.7
+ * AArch64, 8 threads). <b>Not comparable to the table above:</b> JMH auto-detected the {@code full
+ * + dont-inline} Blackhole here rather than the cheap {@code compiler} one, on the same JVM build
+ * and JMH 1.37 -- the mode is auto-detected per run and is not stable across runs, so every
+ * absolute number in this file is conditional on a mode that JMH does not record beside it. Compare
+ * within a table, never across. M ops/us:
+ *
+ * <pre>{@code
+ * add_hashMap        1204.8   add_hashtable       974.4
+ * update_hashMap      577.2   update_hashtable   1862.6
+ * iterate_hashMap      15.9   iterate_hashtable    21.5
+ * }</pre>
+ *
+ * <p>Within this run: {@code update_hashtable} wins by ~3.2x and {@code iterate_hashtable} by
+ * ~1.35x, while {@code add_hashtable} now <em>loses</em> by ~19% -- no longer the "roughly
+ * comparable" of the JDK 8 table, and a wider gap than the slight edge HashMap held in the previous
+ * Java 17 run. {@code add} is where the capped table's bookkeeping is least amortized: both sides
+ * allocate one entry per insert, so there is no boxing win to offset it, and the loop does nothing
+ * else. The counter/tally path -- the case {@code Hashtable} exists for -- is unaffected.
+ *
+ * <p>That is the right side of the trade for this family. {@code Hashtable} and {@link
+ * ConcurrentHashtable} are designed for workloads where <b>updates dominate</b>: the table is
+ * populated once and then hit repeatedly, so per-insert cost amortizes away and in-place mutation
+ * of a primitive field is the operation that runs hot. Paying on {@code add} to make {@code update}
+ * faster is the trade those workloads want. {@code FlatHashtable} and {@code TagMap} sit at the
+ * other end -- built up and read, not updated in a loop -- so this result does not transfer to
+ * them, and neither does the reasoning that justifies it.
  */
 @Fork(2)
 @Warmup(iterations = 2)
@@ -143,11 +171,14 @@ public static class D1State {
     int cursor;
     final BhD1Consumer consumer = new BhD1Consumer();
 
+    // Level.Iteration, not Trial: this rebuilds the table and the HashMap, so each iteration must
+    // start from a fresh, identically-sized state rather than inheriting mutated counters. The
+    // pollution call rides along -- it is idempotent and untimed, so repeating it costs nothing.
     @Setup(Level.Iteration)
     public void setUp() {
       BenchmarkUtils.polluteHashDispatch();
 
-      table = new Hashtable.D1<>(CAPACITY);
+      table = Hashtable.D1.createBounded(D1Counter.class, CAPACITY);
       hashMap = new HashMap<>(CAPACITY);
       keys = SOURCE_KEYS;
       for (int i = 0; i < N_KEYS; ++i) {

@@ -179,11 +179,14 @@ public static class D2State {
     int cursor;
     final BhD2Consumer consumer = new BhD2Consumer();
 
+    // Level.Iteration, not Trial: this rebuilds the table and the HashMap, so each iteration must
+    // start from a fresh, identically-sized state rather than inheriting mutated counters. The
+    // pollution call rides along -- it is idempotent and untimed, so repeating it costs nothing.
     @Setup(Level.Iteration)
     public void setUp() {
       BenchmarkUtils.polluteHashDispatch();
 
-      table = new Hashtable.D2<>(CAPACITY);
+      table = Hashtable.D2.createBounded(D2Counter.class, CAPACITY);
       hashMap = new HashMap<>(CAPACITY);
       k1s = SOURCE_K1;
       k2s = SOURCE_K2;

@@ -242,6 +242,8 @@ public void pollute() {
 
   @Setup(Level.Trial)
   public void setUp() {
+    BenchmarkUtils.polluteHashDispatch();
+
     hashMap = new HashMap<>();
     fill(hashMap);
     synchronizedHashMap = Collections.synchronizedMap(new HashMap<>(hashMap));

@@ -126,6 +126,8 @@ public void pollute() {
 
   @Setup(Level.Trial)
   public void setUp() {
+    BenchmarkUtils.polluteHashDispatch();
+
     hashSet = new HashSet<>(Arrays.asList(ELEMENTS));
     synchronizedSet = Collections.synchronizedSet(new HashSet<>(hashSet));
     treeSet = new TreeSet<>(Arrays.asList(ELEMENTS));