Always emit AdditionalMetricTags when the feature is configured

The Span-Derived Primary Tags RFC specifies the additional_metric_tags
field is present whenever the feature is configured -- as an empty array
for spans that matched no configured key -- not gated on whether a given
entry carried any tags.

SerializingMetricWriter previously omitted the field whenever the entry's
packed array was empty, which conflated "feature off" with "feature on,
no match". It now takes a configured flag (threaded from
AdditionalTagsSchema.size() > 0) and emits the field, empty array
included, whenever configured; when the feature is off the field is
omitted entirely so non-users pay zero payload overhead.

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

Author: dougqh

dd-trace-core/src/main/java/datadog/trace/common/metrics/ClientStatsAggregator.java

@@ -218,7 +218,7 @@ public ClientStatsAggregator(
         features,
         healthMetric,
         sink,
-        new SerializingMetricWriter(wellKnownTags, sink),
+        new SerializingMetricWriter(wellKnownTags, sink, additionalTagsSchema.size() > 0),
         maxAggregates,
         queueSize,
         reportingInterval,

dd-trace-core/src/main/java/datadog/trace/common/metrics/SerializingMetricWriter.java

@@ -63,6 +63,16 @@ public final class SerializingMetricWriter implements MetricWriter {
   private final WellKnownTags wellKnownTags;
   private final WritableFormatter writer;
   private final Sink sink;
+
+  /**
+   * Whether the span-derived additional-tags feature is configured (at least one key). When {@code
+   * true}, the {@code AdditionalMetricTags} field is always emitted -- as an empty array for
+   * entries that matched no configured key -- so the field is present whenever the feature is on,
+   * per the Span-Derived Primary Tags RFC. When {@code false} (the common case: feature off) the
+   * field is omitted entirely, so non-users pay zero payload overhead.
+   */
+  private final boolean additionalTagsConfigured;
+
   private final GrowableBuffer buffer;
   private final DDCache<GitInfo, UTF8BytesString> gitInfoCache =
       DDCaches.newFixedSizeWeakKeyCache(4);
@@ -76,7 +86,12 @@ public final class SerializingMetricWriter implements MetricWriter {
   private byte[] emptyHistogramBytesCache;
 
   public SerializingMetricWriter(WellKnownTags wellKnownTags, Sink sink) {
-    this(wellKnownTags, sink, 512 * 1024);
+    this(wellKnownTags, sink, false);
+  }
+
+  public SerializingMetricWriter(
+      WellKnownTags wellKnownTags, Sink sink, boolean additionalTagsConfigured) {
+    this(wellKnownTags, sink, 512 * 1024, GitInfoProvider.INSTANCE, additionalTagsConfigured);
   }
 
   public SerializingMetricWriter(WellKnownTags wellKnownTags, Sink sink, int initialCapacity) {
@@ -88,11 +103,21 @@ public SerializingMetricWriter(
       Sink sink,
       int initialCapacity,
       final GitInfoProvider gitInfoProvider) {
+    this(wellKnownTags, sink, initialCapacity, gitInfoProvider, false);
+  }
+
+  public SerializingMetricWriter(
+      WellKnownTags wellKnownTags,
+      Sink sink,
+      int initialCapacity,
+      final GitInfoProvider gitInfoProvider,
+      boolean additionalTagsConfigured) {
     this.wellKnownTags = wellKnownTags;
     this.buffer = new GrowableBuffer(initialCapacity);
     this.writer = new MsgPackWriter(buffer);
     this.sink = sink;
     this.gitInfoProvider = gitInfoProvider;
+    this.additionalTagsConfigured = additionalTagsConfigured;
   }
 
   @Override
@@ -159,14 +184,15 @@ public void add(AggregateEntry entry) {
     final boolean hasServiceSource = entry.hasServiceSource();
     final boolean hasGrpcStatusCode = entry.hasGrpcStatusCode();
     final UTF8BytesString[] additionalTags = entry.getAdditionalTags();
-    final boolean hasAdditionalTags = additionalTags.length > 0;
+    // When the feature is configured the field is always emitted (empty array for entries that
+    // matched no key); when it is off the field is omitted entirely so non-users pay nothing.
     final int mapSize =
         15
             + (hasServiceSource ? 1 : 0)
             + (hasHttpMethod ? 1 : 0)
             + (hasHttpEndpoint ? 1 : 0)
             + (hasGrpcStatusCode ? 1 : 0)
-            + (hasAdditionalTags ? 1 : 0);
+            + (additionalTagsConfigured ? 1 : 0);
 
     writer.startMap(mapSize);
 
@@ -203,9 +229,10 @@ public void add(AggregateEntry entry) {
     }
 
     // Emit AdditionalMetricTags as a packed array of pre-built "key:value" UTF8BytesStrings, in
-    // schema (alphabetical-by-key) order. The field is omitted entirely when the entry carries no
-    // additional tags, so spans that set none pay zero payload overhead.
-    if (hasAdditionalTags) {
+    // schema (alphabetical-by-key) order. Present whenever the feature is configured -- an empty
+    // array for entries that matched no key -- and omitted entirely when the feature is off, so
+    // spans in non-using deployments pay zero payload overhead.
+    if (additionalTagsConfigured) {
       writer.writeUTF8(ADDITIONAL_METRIC_TAGS);
       writer.startArray(additionalTags.length);
       for (UTF8BytesString slot : additionalTags) {

dd-trace-core/src/test/java/datadog/trace/common/metrics/SerializingMetricWriterTest.java

@@ -489,8 +489,9 @@ void additionalMetricTagsEmittedWhenSet() {
   }
 
   @Test
-  void additionalMetricTagsFieldOmittedWhenNoneSet() {
-    // Schema configured, but the span doesn't set any of the configured tags.
+  void additionalMetricTagsEmittedAsEmptyArrayWhenConfiguredButNoneSet() {
+    // Schema configured, but the span doesn't set any of the configured tags. Per the Span-Derived
+    // Primary Tags RFC the field is still present (as an empty array) whenever the feature is on.
     AdditionalTagsSchema schema =
         AdditionalTagsSchema.from(new LinkedHashSet<>(Arrays.asList("region")));
     AggregateTable table = newTable(schema);
@@ -499,12 +500,37 @@ void additionalMetricTagsFieldOmittedWhenNoneSet() {
 
     List<AggregateEntry> content = contentOf(table);
     assertEquals(1, content.size());
-    // No slots populated -> empty packed array -> AdditionalMetricTags omitted from the payload.
+    // No slots populated -> empty packed array, but the field is still emitted since configured.
     assertEquals(0, content.get(0).getAdditionalTags().length);
 
     serializeAndValidate(content);
   }
 
+  @Test
+  void additionalMetricTagsFieldOmittedWhenFeatureOff() {
+    // Feature off (no schema): the writer omits AdditionalMetricTags entirely so non-users pay no
+    // payload overhead.
+    long startTime = MILLISECONDS.toNanos(System.currentTimeMillis());
+    long duration = SECONDS.toNanos(10);
+    WellKnownTags wellKnownTags =
+        new WellKnownTags("runtimeid", "hostname", "env", "service", "version", "language");
+    AggregateTable table = newTable(AdditionalTagsSchema.EMPTY);
+    table.findOrInsert(snapshot(AdditionalTagsSchema.EMPTY)).recordOneDuration(1L);
+    List<AggregateEntry> content = contentOf(table);
+    assertEquals(1, content.size());
+    assertEquals(0, content.get(0).getAdditionalTags().length);
+
+    // Default (unconfigured) sink + writer: the field must be absent.
+    ValidatingSink sink = new ValidatingSink(wellKnownTags, startTime, duration, content);
+    SerializingMetricWriter writer = new SerializingMetricWriter(wellKnownTags, sink, 128);
+    writer.startBucket(content.size(), startTime, duration);
+    for (AggregateEntry entry : content) {
+      writer.add(entry);
+    }
+    writer.finishBucket();
+    assertTrue(sink.validatedInput());
+  }
+
   @Test
   void additionalMetricTagsSkipsNullSlots() {
     AdditionalTagsSchema schema =
@@ -579,8 +605,11 @@ private static void serializeAndValidate(List<AggregateEntry> content) {
     long duration = SECONDS.toNanos(10);
     WellKnownTags wellKnownTags =
         new WellKnownTags("runtimeid", "hostname", "env", "service", "version", "language");
-    ValidatingSink sink = new ValidatingSink(wellKnownTags, startTime, duration, content);
-    SerializingMetricWriter writer = new SerializingMetricWriter(wellKnownTags, sink, 128);
+    // These helpers exercise the configured-feature path, so the writer is built configured and the
+    // sink expects the AdditionalMetricTags field present (possibly empty) on every entry.
+    ValidatingSink sink =
+        new ValidatingSink(wellKnownTags, startTime, duration, content, null, true);
+    SerializingMetricWriter writer = new SerializingMetricWriter(wellKnownTags, sink, true);
 
     writer.startBucket(content.size(), startTime, duration);
     for (AggregateEntry entry : content) {
@@ -599,6 +628,7 @@ static final class ValidatingSink implements Sink {
     private boolean validated = false;
     private final List<AggregateEntry> content;
     private final String expectedGitCommitSha;
+    private final boolean additionalTagsConfigured;
 
     ValidatingSink(
         WellKnownTags wellKnownTags,
@@ -614,11 +644,22 @@ static final class ValidatingSink implements Sink {
         long duration,
         List<AggregateEntry> content,
         String expectedGitCommitSha) {
+      this(wellKnownTags, startTimeNanos, duration, content, expectedGitCommitSha, false);
+    }
+
+    ValidatingSink(
+        WellKnownTags wellKnownTags,
+        long startTimeNanos,
+        long duration,
+        List<AggregateEntry> content,
+        String expectedGitCommitSha,
+        boolean additionalTagsConfigured) {
       this.wellKnownTags = wellKnownTags;
       this.startTimeNanos = startTimeNanos;
       this.duration = duration;
       this.content = content;
       this.expectedGitCommitSha = expectedGitCommitSha;
+      this.additionalTagsConfigured = additionalTagsConfigured;
     }
 
     @Override
@@ -684,14 +725,13 @@ private void validate(ByteBuffer buffer) throws IOException {
         boolean hasServiceSource = entry.hasServiceSource();
         boolean hasGrpcStatusCode = entry.hasGrpcStatusCode();
         UTF8BytesString[] additionalTags = entry.getAdditionalTags();
-        boolean hasAdditionalTags = additionalTags.length > 0;
         int expectedMapSize =
             15
                 + (hasServiceSource ? 1 : 0)
                 + (hasHttpMethod ? 1 : 0)
                 + (hasHttpEndpoint ? 1 : 0)
                 + (hasGrpcStatusCode ? 1 : 0)
-                + (hasAdditionalTags ? 1 : 0);
+                + (additionalTagsConfigured ? 1 : 0);
         assertEquals(expectedMapSize, metricMapSize);
         int elementCount = 0;
         assertEquals("Name", unpacker.unpackString());
@@ -729,9 +769,10 @@ private void validate(ByteBuffer buffer) throws IOException {
         }
         ++elementCount;
         // AdditionalMetricTags is a packed array of pre-built "key:value" strings in schema
-        // (alphabetical-by-key) order. Emitted immediately after PeerTags and omitted entirely
-        // when the entry set none, mirroring the writer's optional-field handling above.
-        if (hasAdditionalTags) {
+        // (alphabetical-by-key) order. Emitted immediately after PeerTags whenever the feature is
+        // configured -- as an empty array for entries that matched no key -- and omitted entirely
+        // when the feature is off, mirroring the writer's field handling above.
+        if (additionalTagsConfigured) {
           assertEquals("AdditionalMetricTags", unpacker.unpackString());
           int additionalTagsLength = unpacker.unpackArrayHeader();
           assertEquals(additionalTags.length, additionalTagsLength);