Stabilize opentelemetry-semconv

[jack-berg]

Want to start a conversation about what stands in the way of marking the opentelemetry-semconv artifact as stable. We've come a long way recently, re-organizing by domain, switching from build-tools to weaver based code generation, and changing how we think about deprecated / incubating attributes.

[breedx-splk]

With incubating in place, it seems like most of the roadblocks have been cleared. I suppose the main thing to think about is needing to be able to support future breaking changes though major semver bumps, which should be seldom and annoying at worst?

[jack-berg]

It would also be good to think through what might change in a future where we're generating helpers / constants for producing semantic convention metrics (#12), events, and anything else.

Does the class organization around root namespace work for this? For example, we currently have classes named HttpAttributes and HttpIncubatingAttributes. These names imply that the only hold the http attributes. If we added metric generation, would we feel comfortable adding classes like HttpMetrics, HttpIncubatingMetrics?

Maybe we think of the current class organization as the embodiment of the semantic convention attribute registry - a global registry of attributes agnostic of which conventions they're used in. Then, we can independently decide how to organize anything else we generate for specific conventions.

[lmolkova]

I'd be really interested in stabilizing it for a selfish reason. I'd like to use opentelemetry-instrumentation-api as a dependency in Azure SDK otel plugin, but it depends on io.opentelemetry.semconv:opentelemetry-semconv which is in alpha. Having alpha dependencies on this stable artifact gives me a pause - I would consider it a stability blocker for our plugin. It won't cause breaking changes on the API level, but I'd like to provide runtime behavior guarantees to my users.

It seems there are no major blockers preventing io.opentelemetry.semconv:opentelemetry-semconv from being stabilized, so I wonder if it's something that can be considered in the near future.

[lmolkova]

I agree it'd be nice to make a final call on the code organization.

I'd like to call out a recent refactoring we've done around semconv yaml folder structure that'd be great to consider:

├── model
│   ├── {root-namespace}
│   │   ├── events.yaml
│   │   ├── metrics.yaml
│   │   ├── registry.yaml
│   │   ├── resources.yaml
│   │   ├── spans.yaml

https://github.com/open-telemetry/semantic-conventions/blob/main/CONTRIBUTING.md#code-structure

for Java, it'd probably translate to this:

├── io/opentelemetry/semconv
│   ├── http
│   │   ├── HttpEvents.java   # if ever defined
│   │   ├── HttpMetrics.java
│   │   ├── HttpAttributes.java
│   │   ├── HttpSpans.java # if ever auto-generated

Following current pattern (attributes only), I'm not sure what would be the right place for metrics and other signals

├── io/opentelemetry/semconv
│   ├── ExceptionEvents.java
│   ├── ExceptionMetrics.java # if ever..
│   ├── ExceptionAttributes.java
│   ├── HttpEvents.java   # if ever...
│   ├── HttpMetrics.java
│   ├── HttpAttributes.java
│   ├── HttpSpans.java # if ever..
│   ├── ......  # there will be a lot of files here

It feels like it needs some separation either by the root namespace or type (attribute/metric/span/event/resource). In semconv we decided to move away from type to the root namespace.

[trask]

I like this:

├── io/opentelemetry/semconv
│   ├── http
│   │   ├── HttpEvents.java   # if ever defined
│   │   ├── HttpMetrics.java
│   │   ├── HttpAttributes.java
│   │   ├── HttpSpans.java # if ever auto-generated

[trask]

(sorry @brunobat 😭)

[jack-berg]

I like this:

Do we gain enough from the additional directory to justify the churn? The role of packages is to:

• Organize code
• Prevent name collisions
• Interactions with class / method visibility keys

This reorg would is more aesthetically pleasing (who likes looking a a directory with hundreds of files?) but doesn't improve anything with respective to name collisions or visibility.

If we continue with the single package structure we have today, we still at least get all components of a particular namespace grouped when sorted.

[lmolkova]

It does not feel like the end of the world if we kept the current structure. If it was marked stable already, we'd not consider breaking it just for aesthetics.

[jack-berg]

One benefit of the current structure is that a wildcard import is much more useful. I.e. I can do:

import io.opentelemetry.semconv.*;

Instead of:

import io.opentelemetry.semconv.HttpAttributes;
import io.opentelemetry.semconv.NetworkAttributes;
import io.opentelemetry.semconv.ServiceAttributes;

Seems useful since many conventions draw on attributes from multiple domains.

[trask]

Discussed in Java SIG and decided to move forward with stabilizing the current structure.

TBD how to communicate that we are planning to drop the deprecated SemanticAttributes and ResourceAttributes classes, e.g. through an RC release(?)

[trask]

@jack-berg I realized I wasn't quite sure your thoughts around the RC release proposal. Was it to release an RC where those two classes are not present? I like that.

[jack-berg]

Yes exactly. The RC has to be a preview of what to expect with the stable release.

[jack-berg]

I say we cut a release for 1.29.0 now, and target an RC / stable version for the next version of semantic conventions, 1.30.0. That gives us a concrete target for a stable version, without adding delay for anyone looking to use semantic-conventions:1.29.0, which was released 3 weeks ago already.

Thoughts?

[trask]

works for me, I'll give the release workflow a try...