stabilise spanNames (#12487)

Co-authored-by: Trask Stalnaker <[email protected]>

Author: AlchemyDing

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+### Migration notes
+
+- `io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames` has been deprecated,
+  replaced by the stable `io.opentelemetry.instrumentation.api.semconv.util.SpanNames`
+
 ## Version 2.12.0 (2025-01-17)
 
 ### Migration notes

docs/apidiffs/current_vs_latest/opentelemetry-instrumentation-api.txt

@@ -1,2 +1,6 @@
 Comparing source compatibility of opentelemetry-instrumentation-api-2.13.0-SNAPSHOT.jar against opentelemetry-instrumentation-api-2.12.0.jar
-No changes.
++++  NEW CLASS: PUBLIC(+) FINAL(+) io.opentelemetry.instrumentation.api.semconv.util.SpanNames  (not serializable)
+	+++  CLASS FILE FORMAT VERSION: 52.0 <- n.a.
+	+++  NEW SUPERCLASS: java.lang.Object
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) java.lang.String fromMethod(java.lang.reflect.Method)
+	+++  NEW METHOD: PUBLIC(+) STATIC(+) java.lang.String fromMethod(java.lang.Class<?>, java.lang.String)

instrumentation-api-incubator/src/main/java/io/opentelemetry/instrumentation/api/incubator/semconv/util/SpanNames.java

@@ -5,41 +5,30 @@
 
 package io.opentelemetry.instrumentation.api.incubator.semconv.util;
 
-import io.opentelemetry.instrumentation.api.internal.ClassNames;
-import io.opentelemetry.instrumentation.api.internal.cache.Cache;
 import java.lang.reflect.Method;
-import java.util.Map;
-import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * This class has been stabilized and moved to {@link
+ * io.opentelemetry.instrumentation.api.semconv.util.SpanNames}
+ */
+@Deprecated
 public final class SpanNames {
 
-  private static final Cache<Class<?>, Map<String, String>> spanNameCaches = Cache.weak();
-
   /**
    * This method is used to generate a span name based on a method. Anonymous classes are named
    * based on their parent.
    */
   public static String fromMethod(Method method) {
-    return fromMethod(method.getDeclaringClass(), method.getName());
+    return io.opentelemetry.instrumentation.api.semconv.util.SpanNames.fromMethod(method);
   }
 
   /**
    * This method is used to generate a span name based on a method. Anonymous classes are named
    * based on their parent.
    */
   public static String fromMethod(Class<?> clazz, String methodName) {
-    // the cache (ConcurrentHashMap) is naturally bounded by the number of methods in a class
-    Map<String, String> spanNameCache =
-        spanNameCaches.computeIfAbsent(clazz, c -> new ConcurrentHashMap<>());
-
-    // not using computeIfAbsent, because it would require a capturing (allocating) lambda
-    String spanName = spanNameCache.get(methodName);
-    if (spanName != null) {
-      return spanName;
-    }
-    spanName = ClassNames.simpleName(clazz) + "." + methodName;
-    spanNameCache.put(methodName, spanName);
-    return spanName;
+    return io.opentelemetry.instrumentation.api.semconv.util.SpanNames.fromMethod(
+        clazz, methodName);
   }
 
   private SpanNames() {}

instrumentation-api/src/main/java/io/opentelemetry/instrumentation/api/semconv/util/SpanNames.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.semconv.util;
+
+import io.opentelemetry.instrumentation.api.internal.ClassNames;
+import io.opentelemetry.instrumentation.api.internal.cache.Cache;
+import java.lang.reflect.Method;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+/** A utility class used to generate span names. */
+public final class SpanNames {
+
+  private static final Cache<Class<?>, Map<String, String>> spanNameCaches = Cache.weak();
+
+  /**
+   * This method is used to generate a span name based on a method. Anonymous classes are named
+   * based on their parent.
+   */
+  public static String fromMethod(Method method) {
+    return fromMethod(method.getDeclaringClass(), method.getName());
+  }
+
+  /**
+   * This method is used to generate a span name based on a method. Anonymous classes are named
+   * based on their parent.
+   */
+  public static String fromMethod(Class<?> clazz, String methodName) {
+    // the cache (ConcurrentHashMap) is naturally bounded by the number of methods in a class
+    Map<String, String> spanNameCache =
+        spanNameCaches.computeIfAbsent(clazz, c -> new ConcurrentHashMap<>());
+
+    // not using computeIfAbsent, because it would require a capturing (allocating) lambda
+    String spanName = spanNameCache.get(methodName);
+    if (spanName != null) {
+      return spanName;
+    }
+    spanName = ClassNames.simpleName(clazz) + "." + methodName;
+    spanNameCache.put(methodName, spanName);
+    return spanName;
+  }
+
+  private SpanNames() {}
+}

instrumentation-api/src/test/java/io/opentelemetry/instrumentation/api/semconv/util/SpanNamesTest.java

@@ -0,0 +1,25 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+package io.opentelemetry.instrumentation.api.semconv.util;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import java.lang.reflect.Method;
+import org.junit.jupiter.api.Test;
+
+class SpanNamesTest {
+  @Test
+  void testFromMethod() throws NoSuchMethodException {
+    Method method = TestClass.class.getMethod("test");
+    assertThat(SpanNames.fromMethod(method)).isEqualTo("TestClass.test");
+  }
+
+  static class TestClass {
+    private TestClass() {}
+
+    public void test() {}
+  }
+}

instrumentation/grails-3.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/grails/HandlerData.java

@@ -5,7 +5,7 @@
 
 package io.opentelemetry.javaagent.instrumentation.grails;
 
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 
 public class HandlerData {
 

instrumentation/kotlinx-coroutines/kotlinx-coroutines-1.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/kotlinxcoroutines/instrumentationannotations/AnnotationSingletons.java

@@ -7,8 +7,8 @@
 
 import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.instrumentation.api.incubator.semconv.code.CodeAttributesExtractor;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 
 public final class AnnotationSingletons {
 

instrumentation/opentelemetry-extension-annotations-1.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/extensionannotations/WithSpanSingletons.java

@@ -11,8 +11,8 @@
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.instrumentation.api.annotation.support.MethodSpanAttributesExtractor;
 import io.opentelemetry.instrumentation.api.incubator.semconv.code.CodeAttributesExtractor;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 import java.lang.reflect.Method;
 import java.util.logging.Logger;
 

instrumentation/opentelemetry-instrumentation-annotations-1.16/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/instrumentationannotations/AnnotationSingletons.java

@@ -13,8 +13,8 @@
 import io.opentelemetry.instrumentation.api.annotation.support.MethodSpanAttributesExtractor;
 import io.opentelemetry.instrumentation.api.annotation.support.SpanAttributesExtractor;
 import io.opentelemetry.instrumentation.api.incubator.semconv.code.CodeAttributesExtractor;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 import java.lang.reflect.Method;
 import java.util.logging.Logger;
 

instrumentation/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/internal/instrumentation/annotations/JoinPointRequest.java

@@ -7,7 +7,7 @@
 
 import io.opentelemetry.api.trace.SpanKind;
 import io.opentelemetry.instrumentation.annotations.WithSpan;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 import java.lang.reflect.Method;
 import org.aspectj.lang.JoinPoint;
 import org.aspectj.lang.reflect.MethodSignature;

instrumentation/spring/spring-webflux/spring-webflux-5.0/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/spring/webflux/v5_0/server/WebfluxSpanNameExtractor.java

@@ -6,8 +6,8 @@
 package io.opentelemetry.javaagent.instrumentation.spring.webflux.v5_0.server;
 
 import io.opentelemetry.instrumentation.api.incubator.semconv.code.CodeSpanNameExtractor;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
 import io.opentelemetry.instrumentation.api.instrumenter.SpanNameExtractor;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 import org.springframework.web.method.HandlerMethod;
 
 public class WebfluxSpanNameExtractor implements SpanNameExtractor<Object> {

instrumentation/twilio-6.6/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/twilio/TwilioSingletons.java

@@ -8,9 +8,9 @@
 import static io.opentelemetry.instrumentation.api.instrumenter.SpanKindExtractor.alwaysClient;
 
 import io.opentelemetry.api.GlobalOpenTelemetry;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
 import io.opentelemetry.instrumentation.api.instrumenter.InstrumenterBuilder;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 import io.opentelemetry.javaagent.bootstrap.internal.AgentInstrumentationConfig;
 
 public final class TwilioSingletons {

instrumentation/vaadin-14.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/vaadin/VaadinHandlerRequest.java

@@ -6,7 +6,7 @@
 package io.opentelemetry.javaagent.instrumentation.vaadin;
 
 import com.google.auto.value.AutoValue;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 
 @AutoValue
 public abstract class VaadinHandlerRequest {

instrumentation/vaadin-14.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/vaadin/VaadinServiceRequest.java

@@ -6,7 +6,7 @@
 package io.opentelemetry.javaagent.instrumentation.vaadin;
 
 import com.google.auto.value.AutoValue;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 
 @AutoValue
 public abstract class VaadinServiceRequest {

instrumentation/vaadin-14.2/javaagent/src/main/java/io/opentelemetry/javaagent/instrumentation/vaadin/VaadinSingletons.java

@@ -10,8 +10,8 @@
 import io.opentelemetry.context.ContextKey;
 import io.opentelemetry.instrumentation.api.incubator.semconv.code.CodeAttributesExtractor;
 import io.opentelemetry.instrumentation.api.incubator.semconv.code.CodeSpanNameExtractor;
-import io.opentelemetry.instrumentation.api.incubator.semconv.util.SpanNames;
 import io.opentelemetry.instrumentation.api.instrumenter.Instrumenter;
+import io.opentelemetry.instrumentation.api.semconv.util.SpanNames;
 import io.opentelemetry.javaagent.bootstrap.internal.ExperimentalConfig;
 
 public class VaadinSingletons {