proposal to use annotation processor for incubating semconv

[SylvainJuge]

The semconv attributes in java is now split in two artifacts:

• one for stable definitions
• one for incubating definitions

While those bindings are very convenient to use, creating a library or component that depends on the incubating artifact can create unsolvable dependency issues:

• a library A depends on version N of incubating semconv
• another library B depends on version M != N of incubating semconv if either A or B use attributes that have different definitions, which is expected because incubating attributes are moving, then we can't have both A and B in the same classpath.

This is why we have to recommend to inline the usages of incubating semconv as written here in the README and also discussed here in a related PR.

However, from the maintainer of a component that relies on those incubating semconv it can become a non-trivial burden to maintain those duplicated attributes definitions.

However, I think that we should be able to provide an annotation processor that would check that the inlined attribute definition matches the one in the incubating semconv artifact.

Example of how an inlined attribute could be annotated for the code.stacktrace attribute

public class Attributes {
    @SemconvField(value = CodeIncubatingAttributes.class, field = "CODE_STACKTRACE")
  public static final AttributeKey<Long> CODE_STACKTRACE_ATTRIBUTE = AttributeKey.longKey("code.stacktrace");

}

The library where this duplicated attribute would be compiled with compileOnly dependency on the incubating semconv, and the annotation processor would check both match at compile time.

Adding an annotation processor is a very small change to the library build process. I also tried to use shading but the shadow plugin makes the setup very complex and tedious, also it makes the jar heavier that it should (+70kb to include all incubating semconv).

The annotation processor would check at least two things at compile-time:

• that a matching attribute exists in semconv
• that the values match in type (and maybe value but that's a bit challenging)

I already have an almost working implementation for this and I'd like to contribute it to contrib repo, it could also be something moved directly to the java semconv repo if you think that's relevant.

[jackshirazi]

Some discussion at the Java SIG May 23 2024 meeting

[laurit]

Another alternative would be to use the incubating semconv in the code and use byte buddy gradle/maven plugin to inline the semconv constants.

[SylvainJuge]

After doing a PoC implementation, this approach is 90% working except that checking the attribute key matches between two attributes is harder than expected.

• reading the initialization code requires to rely on compiler tree API which is part of the jdk.compiler java module
• because we compile with java8 compatibility, javac does not allow to add --add-modules option to compile it.
• if we compile the annotation processor with a version that supports JPMS, for example java 11, then the annotation processor can´t be used when compiling classes for java8.

It should still be possible to do the same by reading the classes with another tool like bytebuddy, but this also increases the complexity a lot just to ensure we prevent copy-paste errors and when semconv attributes changes in a non-compatible manner.

As a conclusion, until we have better options I think copying the incubating attributes and rely on the semconv-incubating artifact for testing is the best compromise we can achieve for now.

[SylvainJuge]

Closing this as a simpler approach was taken (and merged) in #1298:

• inline incubating semconv in instrumentation
• use semconv-incubating artifact in tests to validate expected attributes

Whenever the semconv-incubating is updated, we get feedback on the breaking changes from the test execution.