Skip to content

Commit abe4171

Browse files
jack-bergtrask
jack-berg
and
trask
authored
Update to semconv 1.22 (#29)
* 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]>
1 parent fdbb52c commit abe4171

File tree

7 files changed

+2123
-1203
lines changed

7 files changed

+2123
-1203
lines changed

‎README.md

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,7 @@ Requires docker.
4444
In a shell, execute the following gradle tasks:
4545

4646
```shell
47-
./gradlew generateSemanticConventions --console=plain
47+
./gradlew clean generateSemanticConventions --console=plain
4848
./gradlew spotlessApply
4949
```
5050

@@ -53,6 +53,21 @@ of [open-telemetry/semantic-conventions](https://github.com/open-telemetry/seman
5353
defined in the `semanticConventionsVersion` variable of [build.gradle.kts](./build.gradle.kts) and
5454
generate semantic conventions classes from the release contents.
5555

56+
This repository publishes `-alpha` artifacts and as discussed
57+
in [opentelemetry-java/VERSIONING.md](https://github.com/open-telemetry/opentelemetry-java/blob/main/VERSIONING.md),
58+
we make no compatibility guarantees. However, by convention we've been keeping attribute constants
59+
around with `@Deprecated` annotation while we work towards formalizing the strategy (
60+
see [#6](https://github.com/open-telemetry/semantic-conventions-java/issues/6)). The process for
61+
retaining removed attributes is to carefully add entries to
62+
the [SemanticAttributes.java.j2](./buildscripts/templates/SemanticAttributes.java.j2) template. This
63+
is meticulous and error prone, hence the desire to fix it. To ensure we don't accidentally delete
64+
any constants while we work our a permanent
65+
strategy, [japicmp](./buildSrc/src/main/kotlin/otel.japicmp-conventions.gradle.kts) has been added
66+
as a build check. It will ensure that only binary / source compatible changes are made. **NOTE: this
67+
checking of binary / source compatibility is not required and will change in the future.**
68+
69+
To check compatibility, run `./gradlew build` after updating the template and running the generation task as documented above.
70+
5671
## Contributing
5772

5873
Before you start - see OpenTelemetry

‎build.gradle.kts

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ import java.time.Duration
44
plugins {
55
id("otel.java-conventions")
66
id("otel.publish-conventions")
7+
id("otel.japicmp-conventions")
78

89
id("otel.animalsniffer-conventions")
910

@@ -16,7 +17,7 @@ val snapshot = true
1617
// end
1718

1819
// The release version of https://github.com/open-telemetry/semantic-conventions used to generate classes
19-
var semanticConventionsVersion = "1.21.0"
20+
var semanticConventionsVersion = "1.22.0"
2021

2122
// Compute the artifact version, which includes the "-alpha" suffix and includes "-SNAPSHOT" suffix if not releasing
2223
// Release example: version=1.21.0-alpha
@@ -66,7 +67,7 @@ dependencies {
6667
}
6768

6869
// start - define tasks to download, unzip, and generate from opentelemetry/semantic-conventions
69-
var generatorVersion = "0.18.0"
70+
var generatorVersion = "0.22.0"
7071
val semanticConventionsRepoZip = "https://github.com/open-telemetry/semantic-conventions/archive/v$semanticConventionsVersion.zip"
7172
val schemaUrl = "https://opentelemetry.io/schemas/$semanticConventionsVersion"
7273

‎buildSrc/build.gradle.kts

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,9 @@ repositories {
99
}
1010

1111
dependencies {
12-
implementation("com.diffplug.spotless:spotless-plugin-gradle:6.20.0")
13-
implementation("ru.vyarus:gradle-animalsniffer-plugin:1.7.1")
14-
}
12+
implementation("com.diffplug.spotless:spotless-plugin-gradle:6.20.0")
13+
implementation("ru.vyarus:gradle-animalsniffer-plugin:1.7.1")
14+
implementation("me.champeau.gradle:japicmp-gradle-plugin:0.4.2")
15+
// Needed for japicmp but not automatically brought in for some reason.
16+
implementation("com.google.guava:guava:32.1.3-jre")
17+
}

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

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
import japicmp.model.JApiChangeStatus
2+
import japicmp.model.JApiClass
3+
import japicmp.model.JApiCompatibility
4+
import japicmp.model.JApiCompatibilityChange
5+
import japicmp.model.JApiMethod
6+
import me.champeau.gradle.japicmp.JapicmpTask
7+
import me.champeau.gradle.japicmp.report.Violation
8+
import me.champeau.gradle.japicmp.report.stdrules.AbstractRecordingSeenMembers
9+
import me.champeau.gradle.japicmp.report.stdrules.BinaryIncompatibleRule
10+
import me.champeau.gradle.japicmp.report.stdrules.RecordSeenMembersSetup
11+
import me.champeau.gradle.japicmp.report.stdrules.SourceCompatibleRule
12+
import me.champeau.gradle.japicmp.report.stdrules.UnchangedMemberRule
13+
14+
15+
plugins {
16+
base
17+
18+
id("me.champeau.gradle.japicmp")
19+
}
20+
21+
/**
22+
* The latest *released* version of the project. Evaluated lazily so the work is only done if necessary.
23+
*/
24+
val latestReleasedVersion: String by lazy {
25+
// hack to find the current released version of the project
26+
val temp: Configuration = configurations.create("tempConfig")
27+
dependencies.add(temp.name, "io.opentelemetry.semconv:opentelemetry-semconv:latest.release")
28+
val moduleVersion = configurations["tempConfig"].resolvedConfiguration.firstLevelModuleDependencies.elementAt(0).moduleVersion
29+
configurations.remove(temp)
30+
logger.debug("Discovered latest release version: " + moduleVersion)
31+
moduleVersion
32+
}
33+
34+
class SourceIncompatibleRule : AbstractRecordingSeenMembers() {
35+
override fun maybeAddViolation(member: JApiCompatibility): Violation? {
36+
if (!member.isSourceCompatible()) {
37+
return Violation.error(member, "Not source compatible")
38+
}
39+
return null
40+
}
41+
}
42+
43+
/**
44+
* Locate the project's artifact of a particular version.
45+
*/
46+
fun findArtifact(version: String): File {
47+
val existingGroup = group
48+
try {
49+
// Temporarily change the group name because we want to fetch an artifact with the same
50+
// Maven coordinates as the project, which Gradle would not allow otherwise.
51+
group = "virtual_group"
52+
val depModule = "io.opentelemetry.semconv:${base.archivesName.get()}:$version@jar"
53+
val depJar = "${base.archivesName.get()}-$version.jar"
54+
val configuration: Configuration = configurations.detachedConfiguration(
55+
dependencies.create(depModule),
56+
)
57+
return files(configuration.files).filter {
58+
it.name.equals(depJar)
59+
}.singleFile
60+
} finally {
61+
group = existingGroup
62+
}
63+
}
64+
65+
// generate the api diff report for any module that is stable and publishes a jar.
66+
if (!project.hasProperty("otel.release")) {
67+
afterEvaluate {
68+
tasks {
69+
val jApiCmp by registering(JapicmpTask::class) {
70+
dependsOn("jar")
71+
72+
// the japicmp "new" version is either the user-specified one, or the locally built jar.
73+
val apiNewVersion: String? by project
74+
val newArtifact = apiNewVersion?.let { findArtifact(it) }
75+
?: file(getByName<Jar>("jar").archiveFile)
76+
newClasspath.from(files(newArtifact))
77+
78+
// only output changes, not everything
79+
onlyModified.set(true)
80+
81+
// the japicmp "old" version is either the user-specified one, or the latest release.
82+
val apiBaseVersion: String? by project
83+
val baselineVersion = apiBaseVersion ?: latestReleasedVersion
84+
oldClasspath.from(
85+
try {
86+
files(findArtifact(baselineVersion))
87+
} catch (e: Exception) {
88+
// if we can't find the baseline artifact, this is probably one that's never been published before,
89+
// so publish the whole API. We do that by flipping this flag, and comparing the current against nothing.
90+
onlyModified.set(false)
91+
files()
92+
},
93+
)
94+
95+
// Reproduce defaults from https://github.com/melix/japicmp-gradle-plugin/blob/09f52739ef1fccda6b4310cf3f4b19dc97377024/src/main/java/me/champeau/gradle/japicmp/report/ViolationsGenerator.java#L130
96+
// with some changes.
97+
val exclusions = mutableListOf<String>()
98+
// Allow new default methods on interfaces
99+
exclusions.add("METHOD_NEW_DEFAULT")
100+
// Allow adding default implementations for default methods
101+
exclusions.add("METHOD_ABSTRACT_NOW_DEFAULT")
102+
// Bug prevents recognizing default methods of superinterface.
103+
// Fixed in https://github.com/siom79/japicmp/pull/343 but not yet available in me.champeau.gradle.japicmp
104+
exclusions.add("METHOD_ABSTRACT_ADDED_IN_IMPLEMENTED_INTERFACE")
105+
compatibilityChangeExcludes.set(exclusions)
106+
richReport {
107+
addSetupRule(RecordSeenMembersSetup::class.java)
108+
addRule(JApiChangeStatus.NEW, SourceCompatibleRule::class.java)
109+
addRule(JApiChangeStatus.MODIFIED, SourceCompatibleRule::class.java)
110+
addRule(JApiChangeStatus.UNCHANGED, UnchangedMemberRule::class.java)
111+
addRule(BinaryIncompatibleRule::class.java)
112+
// Disallow source incompatible changes, which are allowed by default for some reason
113+
addRule(SourceIncompatibleRule::class.java)
114+
}
115+
116+
// this is needed so that we only consider the current artifact, and not dependencies
117+
ignoreMissingClasses.set(true)
118+
packageExcludes.addAll("*.internal", "*.internal.*")
119+
}
120+
// have the check task depend on the api comparison task, to make it more likely it will get used.
121+
named("check") {
122+
dependsOn(jApiCmp)
123+
}
124+
}
125+
}
126+
}

‎buildscripts/templates/SemanticAttributes.java.j2

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -667,6 +667,134 @@ public final class {{class}} {
667667
private NetHostConnectionSubtypeValues() {}
668668
}
669669

670+
/**
671+
* Immediate client peer port number.
672+
*
673+
* @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.
674+
*/
675+
@Deprecated
676+
public static final AttributeKey<Long> CLIENT_SOCKET_PORT = longKey("client.socket.port");
677+
678+
/**
679+
* Name of the memory pool.
680+
*
681+
* <p>Notes:
682+
*
683+
* <ul>
684+
* <li>Pool names are generally obtained via <a
685+
* href="https://docs.oracle.com/en/java/javase/11/docs/api/java.management/java/lang/management/MemoryPoolMXBean.html#getName()">MemoryPoolMXBean#getName()</a>.
686+
* </ul>
687+
* @deprecated This item has been renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#JVM_MEMORY_POOL_NAME} instead.
688+
*/
689+
@Deprecated
690+
public static final AttributeKey<String> POOL = stringKey("pool");
691+
692+
/**
693+
* The domain name of the source system.
694+
*
695+
* <p>Notes:
696+
*
697+
* <ul>
698+
* <li>This value may be a host name, a fully qualified domain name, or another host naming
699+
* format.
700+
* </ul>
701+
* @deprecated This item has been removed in 1.22.0 of the semantic conventions.
702+
*/
703+
@Deprecated
704+
public static final AttributeKey<String> SOURCE_DOMAIN = stringKey("source.domain");
705+
706+
/**
707+
* Physical server IP address or Unix socket address. If set from the client, should simply use
708+
* the socket's peer address, and not attempt to find any actual server IP (i.e., if set from
709+
* client, this may represent some proxy server instead of the logical server).
710+
*
711+
* @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.
712+
*/
713+
@Deprecated
714+
public static final AttributeKey<String> SERVER_SOCKET_ADDRESS =
715+
stringKey("server.socket.address");
716+
717+
/**
718+
* The (uncompressed) size of the message payload in bytes. Also use this attribute if it is
719+
* unknown whether the compressed or uncompressed payload size is reported.
720+
*
721+
* @deprecated This item has been renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#MESSAGING_MESSAGE_BODY_SIZE} instead.
722+
*/
723+
@Deprecated
724+
public static final AttributeKey<Long> MESSAGING_MESSAGE_PAYLOAD_SIZE_BYTES =
725+
longKey("messaging.message.payload_size_bytes");
726+
727+
/**
728+
* The domain name of the destination system.
729+
*
730+
* @deprecated This item has been removed in 1.22.0 of the semantic conventions.
731+
*/
732+
@Deprecated
733+
public static final AttributeKey<String> DESTINATION_DOMAIN = stringKey("destination.domain");
734+
735+
/**
736+
* The compressed size of the message payload in bytes.
737+
*
738+
* @deprecated This item has been removed in 1.22.0 of the semantic conventions.
739+
*/
740+
@Deprecated
741+
public static final AttributeKey<Long> MESSAGING_MESSAGE_PAYLOAD_COMPRESSED_SIZE_BYTES =
742+
longKey("messaging.message.payload_compressed_size_bytes");
743+
744+
/**
745+
* The domain name of an immediate peer.
746+
*
747+
* <p>Notes:
748+
*
749+
* <ul>
750+
* <li>Typically observed from the client side, and represents a proxy or other intermediary
751+
* domain name.
752+
* </ul>
753+
*
754+
* @deprecated This item has been removed in 1.22.0 of the semantic conventions.
755+
*/
756+
@Deprecated
757+
public static final AttributeKey<String> SERVER_SOCKET_DOMAIN = stringKey("server.socket.domain");
758+
759+
/**
760+
* The type of memory.
761+
*
762+
* @deprecated This item has been renamed in 1.22.0 of the semantic conventions. Use {@link SemanticAttributes#JVM_MEMORY_TYPE} instead.
763+
*/
764+
@Deprecated
765+
public static final AttributeKey<String> TYPE = stringKey("type");
766+
767+
/**
768+
* Physical server port.
769+
*
770+
* @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.
771+
*/
772+
@Deprecated
773+
public static final AttributeKey<Long> SERVER_SOCKET_PORT = longKey("server.socket.port");
774+
775+
/**
776+
* Immediate client peer address - unix domain socket name, IPv4 or IPv6 address.
777+
*
778+
* @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.
779+
*/
780+
@Deprecated
781+
public static final AttributeKey<String> CLIENT_SOCKET_ADDRESS =
782+
stringKey("client.socket.address");
783+
784+
/**
785+
* @deprecated This item has been renamed as of 1.21.0 of the semantic conventions. Use {@link JvmMemoryTypeValues} instead.
786+
*/
787+
@Deprecated
788+
public static final class TypeValues {
789+
/** Heap memory. */
790+
public static final String HEAP = "heap";
791+
792+
/** Non-heap memory. */
793+
public static final String NON_HEAP = "non_heap";
794+
795+
private TypeValues() {}
796+
}
797+
670798
{% endif %}
671799

672800
{%- if class == "ResourceAttributes" %}
@@ -723,6 +851,22 @@ public final class {{class}} {
723851
@Deprecated
724852
public static final AttributeKey<String> FAAS_ID = stringKey("faas.id");
725853

854+
/**
855+
* The version string of the auto instrumentation agent, if used.
856+
*
857+
* @deprecated This item has been renamed in 1.22.0 of the semantic conventions. Use {@link ResourceAttributes#TELEMETRY_DISTRO_VERSION} instead.
858+
*/
859+
@Deprecated
860+
public static final AttributeKey<String> TELEMETRY_AUTO_VERSION = stringKey("telemetry.auto.version");
861+
862+
/**
863+
* Container image tag.
864+
*
865+
* @deprecated This item has been renamed in 1.22.0 of the semantic conventions. Use {@link ResourceAttributes#CONTAINER_IMAGE_TAGS} instead.
866+
*/
867+
@Deprecated
868+
public static final AttributeKey<String> CONTAINER_IMAGE_TAG = stringKey("container.image.tag");
869+
726870
{% endif %}
727871

728872
private {{class}}() {}

0 commit comments

Comments
 (0)