Skip to content

Commit

Permalink
Update to semconv 1.22 (#29)
Browse files Browse the repository at this point in the history
* Update to semconv 1.22.0

* Restore and deprecated removed attributes

* Add note about checing compatibility

* Apply suggestions from code review

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

* Fix grammar

---------

Co-authored-by: Trask Stalnaker <[email protected]>
  • Loading branch information
jack-berg and trask authored Oct 26, 2023
1 parent fdbb52c commit abe4171
Show file tree
Hide file tree
Showing 7 changed files with 2,123 additions and 1,203 deletions.
17 changes: 16 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand All @@ -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
Expand Down
5 changes: 3 additions & 2 deletions build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -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")

Expand All @@ -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
Expand Down Expand Up @@ -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"

Expand Down
9 changes: 6 additions & 3 deletions buildSrc/build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -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")
}
126 changes: 126 additions & 0 deletions buildSrc/src/main/kotlin/otel.japicmp-conventions.gradle.kts
Original file line number Diff line number Diff line change
@@ -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)
}
}
}
}
144 changes: 144 additions & 0 deletions buildscripts/templates/SemanticAttributes.java.j2
Original file line number Diff line number Diff line change
Expand Up @@ -667,6 +667,134 @@ public final class {{class}} {
private NetHostConnectionSubtypeValues() {}
}

/**
* Immediate client peer port number.
*
* @deprecated This item has been renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_PEER_PORT} on server telemetry and {@link SemanticAttributes#NETWORK_LOCAL_PORT} on client telemetry 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 been 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 been removed 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 been renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_LOCAL_ADDRESS} on server telemetry and {@link SemanticAttributes#NETWORK_PEER_ADDRESS} on client telemetry 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 been 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 been removed 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 been removed 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 been removed 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 been 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 been renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_LOCAL_PORT} on server telemetry and {@link SemanticAttributes#NETWORK_PEER_PORT} on client telemetry 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 been renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#NETWORK_PEER_ADDRESS} on server telemetry and {@link SemanticAttributes#NETWORK_LOCAL_ADDRESS} on client telemetry instead.
*/
@Deprecated
public static final AttributeKey<String> CLIENT_SOCKET_ADDRESS =
stringKey("client.socket.address");

/**
* @deprecated This item has been renamed 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" %}
Expand Down Expand Up @@ -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 been 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 been 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}}() {}
Expand Down
Loading

0 comments on commit abe4171

Please sign in to comment.