Clarify library.* resource attributes

[arminru]

I would like to get some clarification about the library.* resource attributes added in #363.

The spec only briefly defines these to provide "Telemetry library information" and mentions opentelemetry as an example for library.name (see data-resource-semantic-conventions.md#library).

Should these attributes be used to report the language and version of the OpenTelemetry API in use or the configured SDK?
If it is about the API, I expect the name to always be opentelemetry unless someone is using a fork. Or should it be the package/module/class name of the language implementation like io.opentelemetry.OpenTelemetry or an artifact identifier like io.opentelemetry:opentelemetry-api?
If this is about the SDK, I would expect the name to be something like com.example:examplevendor-opentelemetrysdk to report if the default SDK or a vendor-provided SDK is in place.

The spec should clearly define what is meant to be reported. In order to report both the API version and the SDK vendor and version we should consider splitting the attributes into API and SDK to be reported separately.

cc @tigrannajaryan & @SergeyKanzhelev (#418 (comment))

[arminru]

@tigrannajaryan could you please elaborate on what the original intent was?

In the SIG spec meeting on Feb 25 we discovered that there are (at least) three different interpretations for these attributes, so there is definitely need to clarify this.

I assume the intent was to report the SDK (and/or API version?) used to produce OpenTelemetry data. Otherwise there would be no information about which SDK version is used and whether it is the built-in default SDK or if a vendor-provided SDK is configured.

One other interpretations that came up was that the attributes should be used to report the process/application/library/component/... being instrumented. IMHO this cannot be the case since there can only be one library.name/version specified on the resource and there is no way for users to specify the name or version of the instrumented lib/app.

Yet another interpretation was that the name of the instrumentation/plugin/integration (see #476 for the whole naming confusion there), i.e., the name provided when obtaining a named tracer/meter should be used here. While I think it would be useful to send this to the server and something like this should be added, I do not think this was the intent here. The producing tracer name would rather be something to be set on spans rather than on the resource, as multiple named tracers can exist in parallel within one monitored application and will usually inter-operate by producing spans that are linked to each other. Scoping it on the resource where only a single library.name/version can be specified wouldn't work either.

[tigrannajaryan]

My understanding is that "library.*" attributes are to represent the SDK. I do not know what exactly is the use case for this. I imagine there is certain usefulness in knowing what version of OpenTelemetry my apps are using by looking at my backend UI (e.g. I may want to know how outdated the SDK is in my fleet is to make a decision to update).

I think open-telemetry/oteps#84 addresses how to store the instrumentation library details.

As for "process/application/library/component/... being instrumented":

• Today we have semantic convensions for "service" (which I assume is the same thing as "application").
• We had "component" earlier but got rid of it in favour of each component using a unique prefix for its attributes and thus the presence of an attribute is an indication of which component emitted it.
• I don't think we have anything for the "process" today, although perhaps we need to, because OpenCensus for example natively includes (PID, Startime) in its proto and we don't have canonical mapping of this data from/to OTLP today. I was actually intending to make a proposal to add these to the semantic convention, but need some time to understand how to generalize it and instead of just catering to OpenCensus needs.

[arminru]

Thanks, @tigrannajaryan!

In PR #494 I added clarification about the current intent and renamed it to avoid confusion.