Add tag-id keyed removal to TagMap and TagMap.Ledger

- Move the lazy tagId->name resolution into the base EntryChange.tag() (final)
  and drop Entry's override, so EntryRemoval resolves its name from a tagId too.
- EntryChange.newRemoval(long) / EntryRemoval(long) carry a tag id.
- TagMap.remove(long)/getAndRemove(long): OptimizedTagMap clears the slot by id
  (knownRemove) then falls back to the resolved-name bucket lookup; LegacyTagMap
  resolves the name and delegates.
- Ledger.remove(long) records an id-keyed removal; fill() replays id removals via
  map.remove(long) (slot-aware, no name round-trip), string removals by name.

Tests: unit coverage for remove/getAndRemove by id (slot clear, prior value,
string-set-then-remove-by-id, ledger remove-by-id) plus a fuzz removeById action
woven into the random mix (exercises slot-clear + collided-slot reclaim);
~48k seeded sequences clean.

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

Author: dougqh

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

@@ -253,6 +253,12 @@ static Ledger ledger(int size) {
    */
   Entry getAndRemove(String tag);
 
+  /** Tag-id keyed removal (no prior value). See {@link #remove(String)}. */
+  boolean remove(long tagId);
+
+  /** Tag-id keyed removal returning the prior Entry. See {@link #getAndRemove(String)}. */
+  Entry getAndRemove(long tagId);
+
   /** Returns a mutable copy of this TagMap */
   TagMap copy();
 
@@ -310,6 +316,10 @@ public static final EntryRemoval newRemoval(String tag) {
       return new EntryRemoval(tag);
     }
 
+    public static final EntryRemoval newRemoval(long tagId) {
+      return new EntryRemoval(tagId);
+    }
+
     // tagId encoding: bits 63-48 = globalSerial (0 for unknown tags), bits 47-32 = fieldPos,
     // bits 31-0 = nameHash (_hash(tagName)). String-constructed entries have upper 32 bits zero
     // with the hash lazily populated on first hash(). tagId-constructed entries have all bits set
@@ -331,8 +341,15 @@ public static final EntryRemoval newRemoval(String tag) {
       this.tag = null; // resolved lazily via tag()
     }
 
-    public String tag() {
-      return this.tag;
+    // For tagId-constructed changes (entries and removals) the name is resolved lazily from the
+    // tagId via KnownTags and cached. Benign race: KnownTags.nameOf returns the same interned
+    // constant, so re-resolution is harmless.
+    public final String tag() {
+      String name = this.tag;
+      if (name != null) return name;
+      name = KnownTags.nameOf(this.tagId);
+      if (name != null) this.tag = name;
+      return name;
     }
 
     public final boolean matches(String tag) {
@@ -354,6 +371,10 @@ final class EntryRemoval extends EntryChange {
       super(tag);
     }
 
+    EntryRemoval(long tagId) {
+      super(tagId);
+    }
+
     @Override
     public boolean isRemoval() {
       return true;
@@ -583,15 +604,6 @@ int hash() {
       return hash;
     }
 
-    @Override
-    public String tag() {
-      String name = this.tag;
-      if (name != null) return name;
-      name = KnownTags.nameOf(this.tagId);
-      if (name != null) this.tag = name;
-      return name;
-    }
-
     @Override
     public Entry entry() {
       return this;
@@ -1160,6 +1172,10 @@ public Ledger remove(String tag) {
       return this.recordRemoval(EntryChange.newRemoval(tag));
     }
 
+    public Ledger remove(long tagId) {
+      return this.recordRemoval(EntryChange.newRemoval(tagId));
+    }
+
     private Ledger recordEntry(Entry entry) {
       this.recordChange(entry);
       return this;
@@ -1243,7 +1259,12 @@ void fill(TagMap map) {
         EntryChange change = entryChanges[i];
 
         if (change.isRemoval()) {
-          map.remove(change.tag());
+          // route tag-id removals by id (slot-aware, no name round-trip); string removals by name
+          if (KnownTags.globalSerial(change.tagId) != 0) {
+            map.remove(change.tagId);
+          } else {
+            map.remove(change.tag());
+          }
         } else {
           map.set((Entry) change);
         }
@@ -2133,6 +2154,24 @@ public boolean remove(String tag) {
     return (this.getAndRemove(tag) != null);
   }
 
+  @Override
+  public boolean remove(long tagId) {
+    return (this.getAndRemove(tagId) != null);
+  }
+
+  @Override
+  public Entry getAndRemove(long tagId) {
+    this.checkWriteAccess();
+
+    // known tags live in their slot - clear there first (by id, no name needed)
+    Entry slotEntry = this.knownRemove(tagId);
+    if (slotEntry != null) return slotEntry;
+
+    // otherwise it may have collided into the buckets - look up by resolved name
+    String name = KnownTags.nameOf(tagId);
+    return name == null ? null : this.removeFromBuckets(name, KnownTags.nameHash(tagId));
+  }
+
   @Override
   public Entry getAndRemove(String tag) {
     this.checkWriteAccess();
@@ -3426,6 +3465,19 @@ public TagMap.Entry getAndRemove(String tag) {
     return prior == null ? null : TagMap.Entry.newAnyEntry(tag, prior);
   }
 
+  // Tag-id keyed removals: LegacyTagMap is name-keyed, so resolve the name and delegate.
+  @Override
+  public boolean remove(long tagId) {
+    String name = KnownTags.nameOf(tagId);
+    return name != null && this.remove(name);
+  }
+
+  @Override
+  public TagMap.Entry getAndRemove(long tagId) {
+    String name = KnownTags.nameOf(tagId);
+    return name == null ? null : this.getAndRemove(name);
+  }
+
   @Override
   public Object getObject(String tag) {
     return this.get(tag);

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

@@ -1062,6 +1062,7 @@ public static final MapAction randomAction() {
         return randomChoice(
             () -> remove(randomKey()),
             () -> removeLight(randomKey()),
+            () -> removeById(randomKey()),
             () -> getAndRemove(randomKey()));
 
       default:
@@ -1117,6 +1118,10 @@ public static final MapAction removeLight(String key) {
     return new RemoveLight(key);
   }
 
+  public static final MapAction removeById(String key) {
+    return new RemoveById(key);
+  }
+
   public static final MapAction getAndRemove(String key) {
     return new GetAndRemove(key);
   }
@@ -1679,6 +1684,39 @@ public String toString() {
     }
   }
 
+  static final class RemoveById extends ReturningAction<Object, Boolean> {
+    final String key;
+
+    RemoveById(String key) {
+      this.key = key;
+    }
+
+    @Override
+    protected Boolean _applyToTestMap(TagMap testMap) {
+      return testMap.remove(tagIdOf(this.key));
+    }
+
+    @Override
+    protected Object _applyToExpectedMap(Map<String, Object> expectedMap) {
+      return expectedMap.remove(this.key);
+    }
+
+    @Override
+    protected void _verifyResults(Object expected, Boolean actual) {
+      assertEquals((expected != null), actual);
+    }
+
+    @Override
+    public void verifyTestMap(TagMap testMap) {
+      assertFalse(testMap.containsKey(this.key));
+    }
+
+    @Override
+    public String toString() {
+      return String.format("removeById(%s)", literal(this.key));
+    }
+  }
+
   static final class GetAndRemove extends ReturningAction<Object, TagMap.Entry> {
     final String key;
 

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

@@ -1,6 +1,7 @@
 package datadog.trace.api;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertSame;
@@ -172,4 +173,52 @@ public void ledger_mixedIdAndName() {
     assertEquals("redis", map.get(DB_SYSTEM));
     assertEquals(2, map.size());
   }
+
+  @Test
+  public void removeById_clearsAndReportsSize() {
+    TagMap map = TagMap.create();
+    map.set(HTTP_METHOD_ID, "GET");
+    assertEquals(1, map.size());
+
+    assertTrue(map.remove(HTTP_METHOD_ID));
+    assertNull(map.getEntry(HTTP_METHOD_ID));
+    assertNull(map.getEntry(HTTP_METHOD));
+    assertEquals(0, map.size());
+    assertFalse(map.remove(HTTP_METHOD_ID)); // already gone
+  }
+
+  @Test
+  public void getAndRemoveById_returnsPrior() {
+    TagMap map = TagMap.create();
+    map.set(HTTP_STATUS_ID, 404);
+
+    Entry prior = map.getAndRemove(HTTP_STATUS_ID);
+    assertNotNull(prior);
+    assertEquals(404, prior.intValue());
+    assertNull(map.getEntry(HTTP_STATUS_ID));
+  }
+
+  @Test
+  public void removeById_removesStringSetTag() {
+    // set by name, removed by id (id resolves to the same tag, slot or bucket)
+    TagMap map = TagMap.create();
+    map.set(DB_SYSTEM, "postgresql");
+
+    assertTrue(map.remove(DB_SYSTEM_ID));
+    assertNull(map.get(DB_SYSTEM));
+  }
+
+  @Test
+  public void ledger_removeById() {
+    TagMap map =
+        TagMap.ledger()
+            .set(HTTP_METHOD_ID, "GET")
+            .set(DB_SYSTEM_ID, "mysql")
+            .remove(DB_SYSTEM_ID)
+            .build();
+
+    assertEquals("GET", map.get(HTTP_METHOD));
+    assertNull(map.get(DB_SYSTEM));
+    assertEquals(1, map.size());
+  }
 }