Update to semconv 1.22

README.md

@@ -44,7 +44,7 @@ Requires docker.
 In a shell, execute the following gradle tasks:
 
 ```shell
-./gradlew generateSemanticConventions --console=plain
+./gradlew clean generateSemanticConventions --console=plain
 ./gradlew spotlessApply
 ```
 
@@ -53,6 +53,21 @@ of [open-telemetry/semantic-conventions](https://github.com/open-telemetry/seman
 defined in the `semanticConventionsVersion` variable of [build.gradle.kts](./build.gradle.kts) and
 generate semantic conventions classes from the release contents.
 
+This repository publishes `-alpha` artifacts and as discussed
+in [opentelemetry-java/VERSIONING.md](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md),
+we make no compatibility guarantees. However, by convention we've been keeping attribute constants
+around with `@Deprecated` annotation while we work towards formalizing the strategy (
+see [#6](https://github.com/open-telemetry/semantic-conventions-java/issues/6)). The process for
+retaining removed attributes is to carefully add entries to
+the [SemanticAttributes.java.j2](./buildscripts/templates/SemanticAttributes.java.j2) template. This
+is meticulous and error prone, hence the desire to fix it. To ensure we don't accidentally delete
+any constants while we work our a permanent
+strategy, [japicmp](./buildSrc/src/main/kotlin/otel.japicmp-conventions.gradle.kts) has been added
+as a build check. It will ensure that only binary / source compatible changes are made. **NOTE: this
+checking of binary / source compatibility is not required and will change in the future.**
+
+To check compatibility, run `./gradlew build` after updating the template and running the generation task as documented above.
+
 ## Contributing
 
 Before you start - see OpenTelemetry

build.gradle.kts

@@ -4,6 +4,7 @@ import java.time.Duration
 plugins {
   id("otel.java-conventions")
   id("otel.publish-conventions")
+  id("otel.japicmp-conventions")
 
   id("otel.animalsniffer-conventions")
 
@@ -16,7 +17,7 @@ val snapshot = true
 // end
 
 // The release version of https://github.com/open-telemetry/semantic-conventions used to generate classes
-var semanticConventionsVersion = "1.21.0"
+var semanticConventionsVersion = "1.22.0"
 
 // Compute the artifact version, which includes the "-alpha" suffix and includes "-SNAPSHOT" suffix if not releasing
 // Release example: version=1.21.0-alpha
@@ -66,7 +67,7 @@ dependencies {
 }
 
 // start - define tasks to download, unzip, and generate from opentelemetry/semantic-conventions
-var generatorVersion = "0.18.0"
+var generatorVersion = "0.22.0"
 val semanticConventionsRepoZip = "https://github.com/open-telemetry/semantic-conventions/archive/v$semanticConventionsVersion.zip"
 val schemaUrl = "https://opentelemetry.io/schemas/$semanticConventionsVersion"
 

buildSrc/build.gradle.kts

@@ -9,6 +9,9 @@ repositories {
 }
 
 dependencies {
-    implementation("com.diffplug.spotless:spotless-plugin-gradle:6.20.0")
-    implementation("ru.vyarus:gradle-animalsniffer-plugin:1.7.1")
-}
+  implementation("com.diffplug.spotless:spotless-plugin-gradle:6.20.0")
+  implementation("ru.vyarus:gradle-animalsniffer-plugin:1.7.1")
+  implementation("me.champeau.gradle:japicmp-gradle-plugin:0.4.2")
+  // Needed for japicmp but not automatically brought in for some reason.
+  implementation("com.google.guava:guava:32.1.3-jre")
+}

buildSrc/src/main/kotlin/otel.japicmp-conventions.gradle.kts

@@ -0,0 +1,126 @@
+import japicmp.model.JApiChangeStatus
+import japicmp.model.JApiClass
+import japicmp.model.JApiCompatibility
+import japicmp.model.JApiCompatibilityChange
+import japicmp.model.JApiMethod
+import me.champeau.gradle.japicmp.JapicmpTask
+import me.champeau.gradle.japicmp.report.Violation
+import me.champeau.gradle.japicmp.report.stdrules.AbstractRecordingSeenMembers
+import me.champeau.gradle.japicmp.report.stdrules.BinaryIncompatibleRule
+import me.champeau.gradle.japicmp.report.stdrules.RecordSeenMembersSetup
+import me.champeau.gradle.japicmp.report.stdrules.SourceCompatibleRule
+import me.champeau.gradle.japicmp.report.stdrules.UnchangedMemberRule
+
+
+plugins {
+  base
+
+  id("me.champeau.gradle.japicmp")
+}
+
+/**
+ * The latest *released* version of the project. Evaluated lazily so the work is only done if necessary.
+ */
+val latestReleasedVersion: String by lazy {
+  // hack to find the current released version of the project
+  val temp: Configuration = configurations.create("tempConfig")
+  dependencies.add(temp.name, "io.opentelemetry.semconv:opentelemetry-semconv:latest.release")
+  val moduleVersion = configurations["tempConfig"].resolvedConfiguration.firstLevelModuleDependencies.elementAt(0).moduleVersion
+  configurations.remove(temp)
+  logger.debug("Discovered latest release version: " + moduleVersion)
+  moduleVersion
+}
+
+class SourceIncompatibleRule : AbstractRecordingSeenMembers() {
+  override fun maybeAddViolation(member: JApiCompatibility): Violation? {
+    if (!member.isSourceCompatible()) {
+      return Violation.error(member, "Not source compatible")
+    }
+    return null
+  }
+}
+
+/**
+ * Locate the project's artifact of a particular version.
+ */
+fun findArtifact(version: String): File {
+  val existingGroup = group
+  try {
+    // Temporarily change the group name because we want to fetch an artifact with the same
+    // Maven coordinates as the project, which Gradle would not allow otherwise.
+    group = "virtual_group"
+    val depModule = "io.opentelemetry.semconv:${base.archivesName.get()}:$version@jar"
+    val depJar = "${base.archivesName.get()}-$version.jar"
+    val configuration: Configuration = configurations.detachedConfiguration(
+      dependencies.create(depModule),
+    )
+    return files(configuration.files).filter {
+      it.name.equals(depJar)
+    }.singleFile
+  } finally {
+    group = existingGroup
+  }
+}
+
+// generate the api diff report for any module that is stable and publishes a jar.
+if (!project.hasProperty("otel.release")) {
+  afterEvaluate {
+    tasks {
+      val jApiCmp by registering(JapicmpTask::class) {
+        dependsOn("jar")
+
+        // the japicmp "new" version is either the user-specified one, or the locally built jar.
+        val apiNewVersion: String? by project
+        val newArtifact = apiNewVersion?.let { findArtifact(it) }
+          ?: file(getByName<Jar>("jar").archiveFile)
+        newClasspath.from(files(newArtifact))
+
+        // only output changes, not everything
+        onlyModified.set(true)
+
+        // the japicmp "old" version is either the user-specified one, or the latest release.
+        val apiBaseVersion: String? by project
+        val baselineVersion = apiBaseVersion ?: latestReleasedVersion
+        oldClasspath.from(
+          try {
+            files(findArtifact(baselineVersion))
+          } catch (e: Exception) {
+            // if we can't find the baseline artifact, this is probably one that's never been published before,
+            // so publish the whole API. We do that by flipping this flag, and comparing the current against nothing.
+            onlyModified.set(false)
+            files()
+          },
+        )
+
+        // Reproduce defaults from https://github.com/melix/japicmp-gradle-plugin/blob/09f52739ef1fccda6b4310cf3f4b19dc97377024/src/main/java/me/champeau/gradle/japicmp/report/ViolationsGenerator.java#L130
+        // with some changes.
+        val exclusions = mutableListOf<String>()
+        // Allow new default methods on interfaces
+        exclusions.add("METHOD_NEW_DEFAULT")
+        // Allow adding default implementations for default methods
+        exclusions.add("METHOD_ABSTRACT_NOW_DEFAULT")
+        // Bug prevents recognizing default methods of superinterface.
+        // Fixed in https://github.com/siom79/japicmp/pull/343 but not yet available in me.champeau.gradle.japicmp
+        exclusions.add("METHOD_ABSTRACT_ADDED_IN_IMPLEMENTED_INTERFACE")
+        compatibilityChangeExcludes.set(exclusions)
+        richReport {
+          addSetupRule(RecordSeenMembersSetup::class.java)
+          addRule(JApiChangeStatus.NEW, SourceCompatibleRule::class.java)
+          addRule(JApiChangeStatus.MODIFIED, SourceCompatibleRule::class.java)
+          addRule(JApiChangeStatus.UNCHANGED, UnchangedMemberRule::class.java)
+          addRule(BinaryIncompatibleRule::class.java)
+          // Disallow source incompatible changes, which are allowed by default for some reason
+          addRule(SourceIncompatibleRule::class.java)
+        }
+
+        // this is needed so that we only consider the current artifact, and not dependencies
+        ignoreMissingClasses.set(true)
+        packageExcludes.addAll("*.internal", "*.internal.*")
+      }
+      // have the check task depend on the api comparison task, to make it more likely it will get used.
+      named("check") {
+        dependsOn(jApiCmp)
+      }
+    }
+  }
+}

buildscripts/templates/SemanticAttributes.java.j2

@@ -667,6 +667,134 @@ public final class {{class}} {
     private NetHostConnectionSubtypeValues() {}
   }
 
+  /**
+   * Immediate client peer port number.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_PEER_PORT} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<Long> CLIENT_SOCKET_PORT = longKey("client.socket.port");
+
+  /**
+   * Name of the memory pool.
+   *
+   * <p>Notes:
+   *
+   * <ul>
+   *   <li>Pool names are generally obtained via <a
+   *       href="https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()">MemoryPoolMXBean#getName()</a>.
+   * </ul>
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#JVM_MEMORY_POOL_NAME} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<String> POOL = stringKey("pool");
+
+  /**
+   * The domain name of the source system.
+   *
+   * <p>Notes:
+   *
+   * <ul>
+   *   <li>This value may be a host name, a fully qualified domain name, or another host naming
+   *       format.
+   * </ul>
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions.
+   */
+  @Deprecated
+  public static final AttributeKey<String> SOURCE_DOMAIN = stringKey("source.domain");
+
+  /**
+   * Physical server IP address or Unix socket address. If set from the client, should simply use
+   * the socket's peer address, and not attempt to find any actual server IP (i.e., if set from
+   * client, this may represent some proxy server instead of the logical server).
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_LOCAL_ADDRESS} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<String> SERVER_SOCKET_ADDRESS =
+      stringKey("server.socket.address");
+
+  /**
+   * The (uncompressed) size of the message payload in bytes. Also use this attribute if it is
+   * unknown whether the compressed or uncompressed payload size is reported.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#MESSAGING_MESSAGE_BODY_SIZE} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<Long> MESSAGING_MESSAGE_PAYLOAD_SIZE_BYTES =
+      longKey("messaging.message.payload_size_bytes");
+
+  /**
+   * The domain name of the destination system.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions.
+   */
+  @Deprecated
+  public static final AttributeKey<String> DESTINATION_DOMAIN = stringKey("destination.domain");
+
+  /**
+   * The compressed size of the message payload in bytes.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions.
+   */
+  @Deprecated
+  public static final AttributeKey<Long> MESSAGING_MESSAGE_PAYLOAD_COMPRESSED_SIZE_BYTES =
+      longKey("messaging.message.payload_compressed_size_bytes");
+
+  /**
+   * The domain name of an immediate peer.
+   *
+   * <p>Notes:
+   *
+   * <ul>
+   *   <li>Typically observed from the client side, and represents a proxy or other intermediary
+   *       domain name.
+   * </ul>
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions.
+   */
+  @Deprecated
+  public static final AttributeKey<String> SERVER_SOCKET_DOMAIN = stringKey("server.socket.domain");
+
+  /**
+   * The type of memory.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#JVM_MEMORY_TYPE} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<String> TYPE = stringKey("type");
+
+  /**
+   * Physical server port.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_LOCAL_PORT} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<Long> SERVER_SOCKET_PORT = longKey("server.socket.port");
+
+  /**
+   * Immediate client peer address - unix domain socket name, IPv4 or IPv6 address.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_PEER_ADDRESS} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<String> CLIENT_SOCKET_ADDRESS =
+      stringKey("client.socket.address");
+
+  /**
+   * @deprecated This item has been removed as of 1.21.0 of the semantic conventions. Use {@link JvmMemoryTypeValues} instead.
+   */
+  @Deprecated
+  public static final class TypeValues {
+    /** Heap memory. */
+    public static final String HEAP = "heap";
+
+    /** Non-heap memory. */
+    public static final String NON_HEAP = "non_heap";
+
+    private TypeValues() {}
+  }
+
   {% endif %}
 
   {%- if class == "ResourceAttributes" %}
@@ -723,6 +851,22 @@ public final class {{class}} {
   @Deprecated
   public static final AttributeKey<String> FAAS_ID = stringKey("faas.id");
 
+  /**
+   * The version string of the auto instrumentation agent, if used.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link ResourceAttributes#TELEMETRY_DISTRO_VERSION} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<String> TELEMETRY_AUTO_VERSION = stringKey("telemetry.auto.version");
+
+  /**
+   * Container image tag.
+   *
+   * @deprecated This item has renamed in 1.22.0 of the semantic conventions. Use {@link ResourceAttributes#CONTAINER_IMAGE_TAGS} instead.
+   */
+  @Deprecated
+  public static final AttributeKey<String> CONTAINER_IMAGE_TAG = stringKey("container.image.tag");
+
   {% endif %}
 
   private {{class}}() {}