Semantic conventions for Instrumentation Scope Attributes

[joaopgrassi]

trafficstars

What are you trying to achieve?

Scope attributes were introduced in #2579 with the motivations behind it described in this OTEP. A first motivation was to have an attribute to hold a instrumentation scope "short name"

What did you expect to see?

Clearly defined semantic conventions around scope attributes so instrumentation/back-ends can rely/do things with it in a consistent manner.

Additional context.

I did some experimentation with the build-tools and how we would auto-generate the conventions tables, the same way we do for the rest today. You can see my attempt in this diff: https://github.com/open-telemetry/opentelemetry-specification/compare/main...dynatrace-oss-contrib:opentelemetry-specification:feature/scope_attributes_semconv?expand=1

My idea behind it was:

1. For scope attributes that are common across signals: A YAML file in semantic_conventions/common/scope.yaml generating a .md file in specification/common/scope.md.
2. If there's need for signal-specific scope attributes: A YAML file in semantic_conventions/metrics/scope-metrics.yaml generating a .md file in specification/metrics/semantic_conventions/scope-metrics.md

Those would give us:

• Common attributes: scope.* e.g. scope.short_name
• Signal-specific attributes: scope_metrics.* e.g. scope_metrics.my_meter_attribute

cc @dashpole @tigrannajaryan

[tigrannajaryan]

This is part of the Scope initiative. Triaging as accepted.

[tigrannajaryan]

Important questions to answer:

• Are Scope attributes considered a completely different namespace from the other attributes? I.e. can I have a Scope attribute http.host that has a completely different meaning from the Span attribute http.host?
• Or, are Scope attributes in the same namespace as all other attributes? If they are in the same namespace which of the existing attributes are OK to record on the Scope? All attributes? Some?
• What does it mean to record an attribute that is defined for a Span at the Scope? Does it mean it applies to all Spans (and is a form of compression) or it applies to the Scope only and the Span can have its own value recorded?

[dashpole]

Are Scope attributes considered a completely different namespace from the other attributes? I.e. can I have a Scope attribute http.host that has a completely different meaning from the Span attribute http.host?

I think the answer should be yes (namespaces are different), although we should try and avoid unnecessary collisions where possible to reduce confusion. I believe this is the same answer as the separation between resource vs trace/metric/log attributes.

What does it mean to record an attribute that is defined for a Span at the Scope?

I'd prefer if it was exclusively something that describes the scope and not telemetry within the scope. It would make aggregation of telemetry more complex if it was considered equivalent for an attribute to either be present in the scope, or present in all telemetry within the scope.

If there's need for signal-specific scope attributes

I'd prefer starting without any signal-specific attributes. We can always add them later if we have need to introduce such a concept.

[joaopgrassi]

The question of namespaces and scope attributes appearing in different places (resource, span) is highly relevant for #2535. I guess whatever we come up with here, needs to be at least considered on how it is mapped to non-otlp exporters.