Add KnownTags.tagId(serial, fieldPos, name) encoder; dedupe callers

The tagId bit-packing was duplicated in four places (fuzz/unit/Entry tests and
the insertion benchmark, which even hand-rolled the name hash). Add a single
KnownTags.tagId(globalSerial, fieldPos, name) factory — the inverse of the
existing globalSerial/fieldPos/nameHash extractors — that computes nameHash via
the runtime's TagMap.Entry._hash so the low 32 bits always match Entry.hash().
Intended for the code generator and tests. Route all callers through it and add
an encoder/decoder round-trip test.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: dougqh

internal-api/src/jmh/java/datadog/trace/api/TagMapInsertionBenchmark.java

@@ -1,6 +1,5 @@
 package datadog.trace.api;
 
-import datadog.trace.api.TagMap.Entry;
 import java.util.concurrent.TimeUnit;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
@@ -21,9 +20,8 @@
  * Compares tag insertion / lookup by generated tag id vs by string name, with a {@link
  * KnownTags.Resolver} registered (the production configuration once code generation is live).
  *
- * <p>Placed in {@code datadog.trace.api} so it can build tag ids with the same {@code nameHash} the
- * runtime uses ({@link TagMap.Entry#_hash}); a mismatch would only matter on the bucket-fallback
- * path, but keeping it exact makes the comparison faithful.
+ * <p>Tag ids are built via {@link KnownTags#tagId} (which uses the runtime's own name hash), so the
+ * comparison is faithful even on the bucket-fallback path.
  *
  * <p>The tags use distinct {@code fieldPos} values (no collisions), so every known tag lands in its
  * positional slot. byId skips string hashing and the keyOf round-trip entirely; byString pays
@@ -65,16 +63,11 @@ public class TagMapInsertionBenchmark {
   // a pre-populated (slotted) map for the read benchmarks; built in setup once IDS exist
   TagMap readMap;
 
-  static int nameHash(String tag) {
-    int hash = tag.hashCode();
-    return hash == 0 ? 0xDD06 : hash ^ (hash >>> 16);
-  }
-
   @Setup(Level.Trial)
   public void setup() {
     for (int i = 0; i < NAMES.length; ++i) {
       // globalSerial = i + 1 (unique, non-zero); fieldPos = i (distinct - no collisions)
-      IDS[i] = ((long) (i + 1) << 48) | ((long) i << 32) | (nameHash(NAMES[i]) & 0xFFFFFFFFL);
+      IDS[i] = KnownTags.tagId(i + 1, i, NAMES[i]);
       VALUES[i] = "value-" + i;
     }
     // Representative resolver: nameOf is a dense array index by globalSerial; keyOf is a hash-table
@@ -100,11 +93,6 @@ public long keyOf(String name) {
             return id == null ? 0L : id;
           }
         });
-    // sanity: assert _hash matches our nameHash so string lookups hit the same bucket if they ever
-    // fall through (they shouldn't here, but keep the comparison honest)
-    if (Entry._hash(NAMES[0]) != nameHash(NAMES[0])) {
-      throw new IllegalStateException("nameHash mismatch with TagMap.Entry._hash");
-    }
 
     // pre-populate the read map by id (entries land in their slots)
     this.readMap = TagMap.create();

internal-api/src/main/java/datadog/trace/api/KnownTags.java

@@ -39,6 +39,18 @@ public static int nameHash(long tagId) {
     return (int) tagId;
   }
 
+  /**
+   * Builds a tagId from its parts: {@code globalSerial} (globally unique per known tag), {@code
+   * fieldPos} (the tag's slot within its span type's positional table), and the tag {@code name}
+   * (whose hash is computed via the same function the runtime uses, so the low 32 bits match {@link
+   * TagMap.Entry#hash()}). Inverse of {@link #globalSerial}/{@link #fieldPos}/{@link #nameHash}.
+   * Intended for the code generator and tests.
+   */
+  public static long tagId(int globalSerial, int fieldPos, String name) {
+    long nameHash = TagMap.Entry._hash(name) & 0xFFFFFFFFL;
+    return ((long) globalSerial << 48) | ((long) (fieldPos & 0xFFFF) << 32) | nameHash;
+  }
+
   public interface Resolver {
     String nameOf(long tagId);
 

internal-api/src/test/java/datadog/trace/api/TagMapEntryTest.java

@@ -562,8 +562,7 @@ public void removalChange() {
   static final String[] TAG_NAMES = {"tag.alpha", "tag.beta", "tag.gamma"};
 
   static long tagId(int serial, int fieldPos, String name) {
-    long nameHash = TagMap.Entry._hash(name) & 0xFFFFFFFFL;
-    return ((long) serial << 48) | ((long) fieldPos << 32) | nameHash;
+    return KnownTags.tagId(serial, fieldPos, name);
   }
 
   @BeforeAll

internal-api/src/test/java/datadog/trace/api/TagMapFuzzTest.java

@@ -102,12 +102,10 @@ static boolean isFuzzKey(String name) {
 
   static long tagIdOf(String key) {
     int n = Integer.parseInt(key.substring("key-".length()));
-    long nameHash = TagMap.Entry._hash(key) & 0xFFFFFFFFL;
     // globalSerial = n + 1 (non-zero, unique per key); fieldPos spreads keys across the slot array
     // (n % CAPACITY), so distinct keys occupy distinct slots AND keys that share a fieldPos collide
     // (first-writer-wins -> the rest fall to buckets), exercising both paths.
-    int fieldPos = n % OptimizedTagMap.KNOWN_ENTRIES_CAPACITY;
-    return ((long) (n + 1) << 48) | ((long) fieldPos << 32) | nameHash;
+    return KnownTags.tagId(n + 1, n % OptimizedTagMap.KNOWN_ENTRIES_CAPACITY, key);
   }
 
   // Number of random sequences per @Test run. Default 1 (fast CI); crank via

internal-api/src/test/java/datadog/trace/api/TagMapTagIdTest.java

@@ -34,8 +34,15 @@ public class TagMapTagIdTest {
   static final long DB_SYSTEM_ID = tagId(3, 0, DB_SYSTEM);
 
   static long tagId(int globalSerial, int fieldPos, String name) {
-    long nameHash = Entry._hash(name) & 0xFFFFFFFFL;
-    return ((long) globalSerial << 48) | ((long) fieldPos << 32) | nameHash;
+    return KnownTags.tagId(globalSerial, fieldPos, name);
+  }
+
+  @Test
+  public void tagId_roundTripsThroughExtractors() {
+    long id = KnownTags.tagId(7, 13, "some.tag.name");
+    assertEquals(7, KnownTags.globalSerial(id));
+    assertEquals(13, KnownTags.fieldPos(id));
+    assertEquals(Entry._hash("some.tag.name"), KnownTags.nameHash(id));
   }
 
   @BeforeEach