Route intercepted tags by id instead of by name (otlp - tag registry - phase 3)

.github/CODEOWNERS

@@ -13,6 +13,7 @@
 /SECURITY.md               @DataDog/apm-java
 /SUPPORT.md                @DataDog/apm-java
 /tag-conventions.yaml      @DataDog/apm-java @DataDog/apm-lang-platform-java @DataDog/apm-sdk-capabilities
+/tag-conventions-java.yaml @DataDog/apm-java @DataDog/apm-lang-platform-java @DataDog/apm-sdk-capabilities
 /dd-smoke-tests/README.md  @DataDog/apm-java
 /docs/                     @DataDog/apm-java
 
@@ -87,6 +88,7 @@
 /internal-api/src/*/*/datadog/trace/api/endpoint/      @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/env/           @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/function/      @DataDog/apm-java
+/internal-api/src/*/*/datadog/apicontract/             @DataDog/apm-java
 /internal-api/src/*/*/datadog/perfcontract/            @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/intake/        @DataDog/apm-java
 /internal-api/src/*/*/datadog/trace/api/logging/       @DataDog/apm-java

build-logic/tag-registry/src/main/kotlin/datadog/buildlogic/tagRegistry/GenerateKnownTagsTask.kt

@@ -5,6 +5,7 @@ import org.gradle.api.file.DirectoryProperty
 import org.gradle.api.file.RegularFileProperty
 import org.gradle.api.tasks.CacheableTask
 import org.gradle.api.tasks.InputFile
+import org.gradle.api.tasks.Optional
 import org.gradle.api.tasks.OutputDirectory
 import org.gradle.api.tasks.PathSensitive
 import org.gradle.api.tasks.PathSensitivity
@@ -20,12 +21,17 @@ abstract class GenerateKnownTagsTask : DefaultTask() {
   @get:PathSensitive(PathSensitivity.NONE)
   abstract val tagConventionsFile: RegularFileProperty
 
+  @get:InputFile
+  @get:Optional
+  @get:PathSensitive(PathSensitivity.NONE)
+  abstract val tracerOverlayFile: RegularFileProperty
+
   @get:OutputDirectory abstract val destinationDirectory: DirectoryProperty
 
   @TaskAction
   fun generate() {
     val outDir = destinationDirectory.get().asFile
-    TagRegistryGenerator.generate(tagConventionsFile.get().asFile, outDir)
+    TagRegistryGenerator.generate(tagConventionsFile.get().asFile, outDir, tracerOverlayFile.orNull?.asFile)
     logger.lifecycle("tag-registry: generated -> $outDir")
   }
 }

build-logic/tag-registry/src/main/kotlin/datadog/buildlogic/tagRegistry/KnownTagsEmitter.kt

@@ -6,8 +6,9 @@ import java.util.Locale
 /**
  * Emits the generated `KnownTags.java` from a [TagRegistry]. Public API first — per-tag
  * `<X>_NAME` (string) + `<X>_ID` (encoded long, literal) couplets with a trailing `// makeTagId(...)`
- * derivation comment — then the package-private `<X>_SERIAL_NUM` constants, the
- * `StringIndex.EmbeddingSupport` keyOf table and the resolver's name switches.
+ * derivation comment — then the `<X>_SERIAL_NUM` constants, the
+ * `StringIndex.EmbeddingSupport` keyOf table, the `NAMES_BY_SERIAL` array behind `nameOf`, and the
+ * resolver's `openTelemetryNameOf` switch.
  */
 object KnownTagsEmitter {
 
@@ -39,35 +40,25 @@ object KnownTagsEmitter {
       return u
     }
 
-    val nameOfConst = HashMap<TagConventions.TagIdentity, String>()
-    val idOfConst = HashMap<TagConventions.TagIdentity, String>()
-    val serialOfConst = HashMap<TagConventions.TagIdentity, String>()
-    val otelNameOfConst = HashMap<TagConventions.TagIdentity, String>()
+    val nameOfConst = HashMap<String, String>()
+    val idOfConst = HashMap<String, String>()
+    val serialOfConst = HashMap<String, String>()
+    val otelNameOfConst = HashMap<String, String>()
     for (t in reg.tags) {
       val base = sanitize(t.name)
-      // Shared Datadog names get no NAME constant because they identify several tags.
-      // Callers use a direction-specific ID (e.g. PEER_PORT_OUTBOUND_ID); nameOf emits the
-      // shared Datadog name as a literal.
-      if (t.sharedNameDirection == null) nameOfConst[t.identity] = unique(withSuffix(base, "_NAME"))
-      idOfConst[t.identity] = unique(withSuffix(base, "_ID"))
-      serialOfConst[t.identity] = unique(withSuffix(base, "_SERIAL_NUM"))
+      nameOfConst[t.ddName] = unique(withSuffix(base, "_NAME"))
+      idOfConst[t.ddName] = unique(withSuffix(base, "_ID"))
+      serialOfConst[t.ddName] = unique(withSuffix(base, "_SERIAL_NUM"))
       // Suffix the pre-suffix base (not nameC), same as the other three: suffixing an
       // already-suffixed identifier would produce a redundant compound like NAME_OTEL_NAME.
-      if (t.otelName != null) otelNameOfConst[t.identity] = unique(withSuffix(base, "_OTEL_NAME"))
+      if (t.otelName != null) otelNameOfConst[t.ddName] = unique(withSuffix(base, "_OTEL_NAME"))
     }
-    fun nameC(identity: TagConventions.TagIdentity) = nameOfConst.getValue(identity)
-
-    // The expression nameOf returns: the NAME constant, or the shared name's literal.
-    fun nameExpr(t: TagRegistry.Tag) = nameOfConst[t.identity] ?: "\"${escape(t.ddName)}\""
-    fun idC(identity: TagConventions.TagIdentity) = idOfConst.getValue(identity)
-    fun serialC(identity: TagConventions.TagIdentity) = serialOfConst.getValue(identity)
-    fun otelNameC(identity: TagConventions.TagIdentity) = otelNameOfConst.getValue(identity)
-
-    val order = reg.tags.map { it.identity } // stable emit order
-    // keyOf has no direction argument, so omit shared names and let them resolve to 0 (unknown).
-    val keyOfOrder = reg.tags.filter { it.sharedNameDirection == null }.map { it.identity }
-    // canonical name -> OpenTelemetry name, for the reverse (openTelemetryNameOf) switch.
-    val otelName = reg.tags.mapNotNull { t -> t.otelName?.let { t.identity to it } }.toMap()
+    fun nameC(ddName: String) = nameOfConst.getValue(ddName)
+    fun idC(ddName: String) = idOfConst.getValue(ddName)
+    fun serialC(ddName: String) = serialOfConst.getValue(ddName)
+    fun otelNameC(ddName: String) = otelNameOfConst.getValue(ddName)
+
+    val keyOfOrder = reg.tags.map { it.ddName } // stable emit order
     return buildString {
       // Public API first (name + encoded id couplets), so readers see the useful parts up top; the
       // serial ids and keyOf/resolver machinery follow below. Derivation is in the trailing comment.
@@ -86,37 +77,35 @@ object KnownTagsEmitter {
       )
 
       for (t in reg.tags) {
-        val direction = t.sharedNameDirection
-        if (direction == null) {
-          appendLine("  public static final String ${nameC(t.identity)} = \"${escape(t.ddName)}\";")
-        } else {
-          appendLine(
-            "  /** {@code ${escape(t.ddName)}} on ${direction.yamlKey} spans. This ID identifies the direction; " +
-              "the Datadog name is shared across directions. */"
-          )
-        }
-        appendLine("  public static final long ${idC(t.identity)} = ${hex(t.id)};")
+        appendLine("  public static final String ${nameC(t.ddName)} = \"${escape(t.ddName)}\";")
+        appendLine("  public static final long ${idC(t.ddName)} = ${hex(t.id)};")
         if (t.otelName != null) {
-          appendLine("  public static final String ${otelNameC(t.identity)} = \"${escape(t.otelName)}\";")
+          appendLine("  public static final String ${otelNameC(t.ddName)} = \"${escape(t.otelName)}\";")
         }
         append("// makeTagId(serial=${t.serial})")
         if (t.traceLevel) append(" + trace-level")
+        if (t.intercepted) append(" + intercepted")
         if (t.otelName != null) append(" -> ${escape(t.otelName)}")
+        for ((direction, otel) in t.scopedOtelNames) append(" -> ${escape(otel)} (${direction.yamlKey})")
         appendLine("  <${escape(t.required)}>")
         appendLine()
       }
 
-      // Serial numbers (globalSerial per tag) — package-private, consumed by the resolver switch.
+      // Serial numbers (globalSerial per tag) — public, so a switch on KnownTagCodec.serialNum outside
+      // this package (the resolver here, TagInterceptor in core) can name them as case labels.
       appendLine("  // ---- serial numbers ----")
       for (t in reg.tags) {
-        appendLine("  static final int ${serialC(t.identity)} = ${t.serial};")
+        appendLine("  public static final int ${serialC(t.ddName)} = ${t.serial};")
       }
+      // Every known tag's serial is below SERIAL_LIMIT; serial 0 is no tag.
+      val serialLimit = (reg.tags.maxOfOrNull { it.serial } ?: 0) + 1
+      appendLine("  public static final int SERIAL_LIMIT = $serialLimit;")
 
       // OpenTelemetry name -> canonical tag name. Validation ensures aliases are distinct from all
       // canonical names. Sort by OTel name to keep output deterministic.
       val otelByCanonical =
         reg.tags
-          .mapNotNull { t -> t.otelName?.let { it to t.identity } }
+          .mapNotNull { t -> t.otelName?.let { it to t.ddName } }
           .sortedBy { it.first }
 
       // keyOf table (open-addressed, via StringIndex.EmbeddingSupport). Canonical names first, then
@@ -163,6 +152,21 @@ object KnownTagsEmitter {
             KEYOF_IDS = ids;
           }
 
+          /**
+           * Each tag's Datadog name, indexed by serial; slot 0 (no tag) is null. An array rather than a
+           * switch keeps nameOf small enough to inline at every caller.
+           */
+          static final String[] NAMES_BY_SERIAL = {
+            null,
+        """.trimIndent()
+      )
+      for (t in reg.tags.sortedBy { it.serial }) {
+        appendLine("    ${nameC(t.ddName)},")
+      }
+      appendLine(
+        """
+          };
+
           /**
            * The registry's name&harr;id tables, as a {@link KnownTagCodec.Resolver}. {@code KnownTagCodec}
            * reads this field from its own holder, so the two classes complete each other: the codec owns
@@ -172,39 +176,33 @@ object KnownTagsEmitter {
               new KnownTagCodec.Resolver() {
                 @Override
                 public String nameOf(long tagId) {
-                  switch (KnownTagCodec.serialNum(tagId)) {
-        """.trimIndent()
-      )
-      for (t in reg.tags) {
-        appendLine(
-          """
-                      case ${serialC(t.identity)}:
-                        return ${nameExpr(t)};
-          """.trimIndent()
-        )
-      }
-      // openTelemetryNameOf: canonical id -> OTel-namespace name, null when the tag has none. The
-      // caller (a serializer) owns any fall-back-to-Datadog-name policy; this stays a pure lookup.
-      appendLine(
-        """
-                    default:
-                      return null;
-                  }
+                  int serial = KnownTagCodec.serialNum(tagId);
+                  return serial < NAMES_BY_SERIAL.length ? NAMES_BY_SERIAL[serial] : null;
                 }
 
+                // openTelemetryNameOf: id -> OTel-namespace name on spans of a direction, null when
+                // the tag has none there. The caller (a serializer) owns any fall-back-to-Datadog-name
+                // policy.
                 @Override
-                public String openTelemetryNameOf(long tagId) {
+                public String openTelemetryNameOf(long tagId, int direction) {
                   switch (KnownTagCodec.serialNum(tagId)) {
         """.trimIndent()
       )
-      for (identity in order) {
-        if (otelName[identity] == null) continue
-        appendLine(
-          """
-                      case ${serialC(identity)}:
-                        return ${otelNameC(identity)};
-          """.trimIndent()
-        )
+      for (t in reg.tags) {
+        val result =
+          if (t.otelName != null) {
+            otelNameC(t.ddName)
+          } else if (t.scopedOtelNames.isNotEmpty()) {
+            // Renamed only on spans of some directions: elsewhere, and while the direction is
+            // unknown, the tag keeps its Datadog name.
+            t.scopedOtelNames.entries.reversed().fold("null") { rest, (direction, otel) ->
+              "direction == KnownTagCodec.DIRECTION_${direction.name} ? \"${escape(otel)}\" : $rest"
+            }
+          } else {
+            continue
+          }
+        appendLine("case ${serialC(t.ddName)}:")
+        appendLine("  return $result;")
       }
       appendLine(
         """

build-logic/tag-registry/src/main/kotlin/datadog/buildlogic/tagRegistry/TagConventions.kt

@@ -9,6 +9,8 @@ class TagConventions private constructor(
   private val spanTypes: Map<String, SpanType>,
   private val mixins: Map<String, Mixin>,
   private val traceLevel: List<Tag>,
+  /** Datadog names the tracer intercepts on the set-path, from the tracer overlay. */
+  val interceptedNames: Set<String> = emptySet(),
 ) {
   /**
    * A tag's identity: its Datadog name, plus the direction when that name is declared once per
@@ -59,13 +61,9 @@ class TagConventions private constructor(
     val name: String
       get() = identity.label
 
-    /** The Datadog-namespace name, shared by the tags of a name declared per direction. */
+    /** The Datadog-namespace name, shared by the declarations of a name declared per direction. */
     val ddName: String
       get() = identity.ddName
-
-    /** The direction of a tag declared per direction, or null for every other tag. */
-    val sharedNameDirection: Direction?
-      get() = identity.direction
   }
 
   /**
@@ -241,6 +239,16 @@ class TagConventions private constructor(
     /** The type's own or nearest inherited `span-kind` direction, or null when none is declared. */
     private fun directionOf(spanTypes: Map<String, SpanType>, st: SpanType): Direction? = chainOf(spanTypes, st.name).firstNotNullOfOrNull { it.direction }
 
+    /** The tracer overlay's `tags`, as a mixin that applies to no span type; empty when none. */
+    private fun overlayMixin(overlay: Map<String, Any?>): Map<String, Mixin> {
+      val tags = tagList(overlay["tags"])
+      if (tags.isEmpty()) return emptyMap()
+      return mapOf(
+        OVERLAY_MIXIN to
+          Mixin(name = OVERLAY_MIXIN, appliesAll = false, appliesTo = emptySet(), tags = tags, refs = emptyList())
+      )
+    }
+
     /** Reads `span-kind` as the direction it sets, or null when absent. */
     private fun parseDirection(m: Map<String, Any?>, owner: String): Direction? {
       val spanKind = m["span-kind"]
@@ -250,11 +258,31 @@ class TagConventions private constructor(
       return (spanKind as String?)?.let { SPAN_KIND_DIRECTIONS.getValue(it) }
     }
 
+    /** The synthetic mixin holding the tracer overlay's tags; it applies to no span type. */
+    const val OVERLAY_MIXIN = "tracer overlay"
+
+    /**
+     * Parses [root], the language-agnostic conventions, plus [overlay], this tracer's own set-path
+     * routing: `tags` declares keys that exist only to be routed (e.g. `resource.name`), so each is
+     * intercepted, and `intercepted` adds the tags declared in [root] that the tracer also routes.
+     */
     @Suppress("UNCHECKED_CAST")
-    fun parse(root: Map<String, Any?>): TagConventions {
+    fun parse(root: Map<String, Any?>, overlay: Map<String, Any?> = emptyMap()): TagConventions {
       for (section in listOf("span_types", "mixins", "trace_level")) {
         require(root[section] == null || root[section] is Map<*, *>) { "$section must be a mapping" }
       }
+      require(overlay.keys.all { it == "tags" || it == "intercepted" }) {
+        "the tracer overlay may only declare `tags` and `intercepted`, not ${overlay.keys - setOf("tags", "intercepted")}"
+      }
+      require(refList(overlay["tags"]).isEmpty()) { "tracer overlay tags must be declarations, not refs" }
+      val interceptedRaw = overlay["intercepted"]
+      require(interceptedRaw == null || (interceptedRaw is List<*> && interceptedRaw.all { it is String })) {
+        "intercepted must be a list of Datadog tag names"
+      }
+      // An overlay tag exists only to be routed, so it is intercepted without being listed.
+      val intercepted =
+        ((interceptedRaw as? List<String>) ?: emptyList()).toSet() +
+          tagList(overlay["tags"]).map { it.ddName }
       val spanTypesRaw = (root["span_types"] as? Map<String, Any?>) ?: emptyMap()
       val parsedSpanTypes =
         spanTypesRaw.mapValues { (name, v) ->
@@ -298,7 +326,7 @@ class TagConventions private constructor(
             refs = refList(m["tags"]),
             direction = parseDirection(m, "mixin '$name'"),
           )
-        }
+        } + overlayMixin(overlay)
 
       for (spanType in parsedSpanTypes.values) {
         for (included in spanType.include) {
@@ -342,7 +370,12 @@ class TagConventions private constructor(
           )
         }
       validateOtelNameScope(spanTypes, mixins, traceLevel)
-      return TagConventions(spanTypes, mixins, traceLevel)
+      val conv = TagConventions(spanTypes, mixins, traceLevel, intercepted)
+      val declared = conv.allDeclaredTags().map { it.ddName }.toSet()
+      for (name in intercepted) {
+        require(name in declared) { "intercepted tag '$name' is not declared" }
+      }
+      return conv
     }
 
     /**