Java code-generation for the OpenTelemetry Semantic Conventions.

Published releases are available on maven central. Replace {{version}} with the latest released version:

<project>
  <dependencies>
    <!-- Stable semantic conventions. Note: generated code is still subject to breaking changes while published with "-alpha" suffix. -->
    <dependency>
      <groupId>io.opentelemetry.semconv</groupId>
      <artifactId>opentelemetry-semconv</artifactId>
      <version>{{version}}</version>
    </dependency>
    <!-- Incubating semantic conventions. Breaking changes expected. Library instrumentation SHOULD NOT depend on this. -->
    <dependency>
      <groupId>io.opentelemetry.semconv</groupId>
      <artifactId>opentelemetry-semconv-incubating</artifactId>
      <version>{{version}}</version>
    </dependency>
  </dependencies>
</project>

dependencies {
  // Stable semantic conventions. Note: generated code is still subject to breaking changes while published with "-alpha" suffix.
  implementation "io.opentelemetry.semconv:opentelemetry-semconv:{{version}}"
  // Incubating semantic conventions. Breaking changes expected. Library instrumentation SHOULD NOT depend on this.
  implementation "io.opentelemetry.semconv:opentelemetry-semconv-incubating:{{version}}"
}

Java 17 or higher is required to build the projects in this repository. The built artifacts can be used on Java 8 or higher.

To use these artifacts, you must also depend on io.opentelemetry:opentelemetry-api:{{version}}. See opentelemetry-java releases for more information.

Requires docker.

In a shell, execute the following gradle tasks:

./gradlew clean generateSemanticConventions --console=plain
./gradlew spotlessApply

This will download the version of open-telemetry/semantic-conventions defined in the semanticConventionsVersion variable of build.gradle.kts and generate semantic conventions classes from the release contents.

TODO: Update the following paragraph with new strategy for managing compatibility

This repository publishes -alpha artifacts and as discussed in opentelemetry-java/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). The process for retaining removed attributes is to carefully add entries to the 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 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.

Before you start - see OpenTelemetry general contributing requirements and recommendations.

Make sure to review the projects license and sign the CNCF CLA. A signed CLA will be enforced by an automatic check once you submit a PR, but you can also sign it after opening your PR.

This repository is an extension of open-telemetry/opentelemetry-java. See opentelemetry-java contributors for code owners.

TODO(jack-berg): add code coverage badge?