Generate semantic conventions for event names and body fields

[mcumings]

Area(s)

area:android

What happened?

Description

Recently, the io.opentelemetry.semconv.incubating.AndroidIncubatingAttributes#ANDROID_STATE attribute has been deprecated with documentation pointing users to use device.app.lifecycle instead. The problem is that there are no semantic convention constants in generated code which refer to this new name. A similar condition exists for ios.state.

Projects are frequently configured to fail on compilation warnings. Kotlin provides no mechanism for ignoring a specific warning which would force consumers to disable compilation failure on all compile warnings, require the consumer to define their own semantic convention definition for these attributes, or to avoid updating to recent semantic convention library releases.

Expected Result

Deprecated constants have appropriate replacement comments/API to transition to.

Actual Result

Compilation results in deprecation warnings, leading to compilation failure (when warnings-as-errors is enabled).

Semantic convention version

1.29.0-alpha (1.27.0-alpha works)

Additional context

open-telemetry/semantic-conventions#794 and open-telemetry/semantic-conventions#1461 look to be related to this change.

Tagging @breedx-splk on this, as requested. Thanks!

[joaopgrassi]

CC @MSNev

[MSNev]

Both android.state and ios.state where never meant to be top level attributes, as they are specific event fields only and not generic attributes.

They were only originally added (as attributes) due to tooling constraints at the time which did not support the correct definition of an event. This was also (indirectly) included in the brief for the definitions.

This attribute represents the state the application has transitioned into at the occurrence of the event.

The real issue is not that they have been deprecated, but that the Java/Android environment is now not creating definitions which can be used as both of these attributes are now defined correctly as event fields in the following locations

• ios.state
• android.state

So the real issue is either (or a combination of)

• Java is not emitting the semantic conventions for event fields
• The semantic convention tooling (weaver / jq) is not providing enough support to help generating these fields.

[lmolkova]

Transferring this issue from semantic conventions.

@mcumings, the problem is that we don't yet generate event definitions here in this repo (semantic-conventions-java). So this is effectively a feature request to start generating them.

You can keep using deprecated attributes if you suppress warnings or hardcode them in your code to avoid warnings.

[mcumings]

Ok, sounds like I got caught in the middle of a transition.

From the OTel perspective of the attributes being transitioned to a new API specific to events with the original attributes going away altogether, the deprecation makes sense.

To convey our underlying use case, we cannot have traces live so long as to encompass the entire lifecycle of a screen, as doing so would result in a massive trace. Specifying these lifecycle transitions only as events has therefore not be sufficient in and of itself. As a result, we have been creating new, span-linked traces for a subset of these transitions (e.g., background to foreground, and vice versa), with the less significant events being documented as events within the active trace. To recreate this with the upcoming API changes, it seems like we'll need to (re)create these deprecated attributes for use on our traces and then also eventually leverage the new/upcoming events API changes to document there as well, once available. Not great, but workable.

Unfortunately, suppressing deprecations is not always possible without suppressing all warnings. Java is nicer in this regard, but Kotlin in still working on it.