Ideas on how to InstrumentationLibrary -> Scope

[bogdandrutu]

This is a try to document what is the ideal scenario to extend the protocol to support the notion of "instrumentation scope", and allow the tracer/meter/logger to share the same concepts.

There were multiple proposals, disagreements, ideas in lots of places:

• Clarify that Trace/Meter are associated with Instrumentation Scope #2276
• Is it possible to rename "instrumentation library" to "instrumentation scope" everywhere? #2203
• Add LoggerName to Log Data Model #1236
• Add InstrumentationLibrary to describe telemetry from a named Tracer/Meter oteps#84

OTLP ideal end goal, based on lots of discussions/comments:

// Resource information.
message Resource {
  // Set of labels that describe the resource.
  repeated opentelemetry.proto.common.v1.AttributeKeyValue attributes = 1;
}

// Scope is a message representing the instrumentation scope
message Scope {
  // TBD: Do we need a first class "name" concept?
  // Set of labels that describe the instrumentation scope.
  repeated opentelemetry.proto.common.v1.AttributeKeyValue attributes = 1;
}

// A collection of ScopeMetrics from a Resource.
message ResourceMetrics {
  // The Resource for the metrics in this message.
  // If this field is not set then no Resource is known.
  Resource resource = 1;
  // A list of metrics that originate from a Resource and their scope.
  repeated ScopeMetrics scope_metrics = 2;
}

// A collection of Metrics from a Scope within a Resource.
message ScopeMetrics {
  // The Instrumentation scope information for the metrics in this message.
  // If this field is not set then no Scope is known.
  Scope scope = 1;

  // A list of metrics that originate from an Instrumentation scope.
  repeated Metric metrics = 2;
}

How to get there?

There are few places where changes are necessary:

1. The OTLP protocol can be changed following a "backwards" compatible approach:
   • Rename "InstrumentationLibrary" to "Scope".
   • Add "attributes" to the new Scope concept.
   • Deprecate the current "name"/"version" in favor of semantic conventions for these fields in the new "attributes".
2. The current "TracerProvider.get()" API:
   • Probably it is fine to relax the need to have this as defined right now "instrumentation library name" and suggest that as a "MAY".
   • When doing this change probably the SDK should stop populating the old "instrumentation library name" field in the protocol, and start using the new semantic convention (or proposed solution) for "scope.name". This will cause current receivers to receive an empty instrumentation library name which is ok, since the "instrumentation" itself is not stable.
   • Alternative we can simply continue to populate, the change of this "meaning" cannot cause that much inconvenience to the receivers. Not sure what receivers can do with this value, since is more or less a semantic convention anyway in regard to the format of the name and uniqueness, etc.
3. The SDK (InstrumentationLibrary struct/class)
   • Ideally, if possible to rename/deprecate and add the new concept. This is probably very language specific. Need to collect more feedback from the maintainers.

[tigrannajaryan]

Add "attributes" to the new Scope concept.

This goes a step further than was discussed in the last spec SIG meeting. A smaller step would be to only add a "subscope_name" as an additional field to "instrumentation_library_name/version" and call the message with these 3 fields a Scope. But perhaps "attributes" field+semantic conventions for scopes is a better approach if we can come with other use-cases when recording additional attributes is necessary.

Probably it is fine to relax the need to have this as defined right now "instrumentation library name" and suggest that as a "MAY".

I think this one people disagree with because this dilutes the semantics of the existing API. I tend to agree with this position. I think we need to keep existing TracerProvider.get() API's semantics unchanged since it is declared stable. It needs to populate instrumentation library name and version.

We can add something like TracerProvider.getScoped() which will accept the new set of parameters (either libname/ver/subscope or just "attributes").

[jmacd]

I like this proposal. It solves the problem posed in open-telemetry/oteps#78.

[bogdandrutu]

@jmacd I wish I would have understood better your proposal back then, anyway good time now to fix that.

[mwear]

I generally like this approach, as a scope would give us a place to store instrumentation library as well as additional metadata. There was a lengthy discussion at the spec SIG where concerns were raised around backwards compatibility, and ways to work around incompatibilities were suggested. Is there any chance we can document what the concerns were and how they could be resolved?

[dyladan]

I can document at least my concern:

I am concerned that expanding what the name is allowed to be will lose the information of which library actually generated a log line. Loggers can easily be named "http" when they are monitoring HTTP requests (rather than the "@opentelemetry/instrumentation-http" that we have for traces and metrics). If the same concept of "scope" is used with the logging, tracing, and metrics APIs this misuse will inevitably leak into the trace and metric API use.
IIRC @bogdandrutu's proposed resolution (and please bogdan, expand on this if I am misstating) was that the scope would typically be the fully qualified class name of the instrumentation class anyway, because that is how he has seen logger name use "in the wild" and he doesn't expect it to be a problem. Instrumentation libraries would use their own fully qualified class names and first party instrumentations would use their own fully qualified class names. On the call today he seemed to believe that calling the field "instrumentation library name" was confusing to users, particularly in the case where the instrumentation library and the instrumented library are the same (first party instrumentation).

I, (and I believe @Aneurysm9 although I would let him speak for himself) am not completely convinced by this. At least in JavaScript I have not seen any consistent use of logger name, and certainly would not expect fully qualified class name to be commonly used as a logger name (JavaScript doesn't even have a common idiom for globally referencing a class anyway). Some popular JS logging libraries (winston, npmlog) don't even have the concept of a logger name, and those that do offer little to no guidance as to what a logger name should be (bunyan, pino)

[Aneurysm9]

I do share Dan's concern that assumptions about user behavior are being made without adequate evidentiary support. I also think that, even if those assumptions are correct, this solution is overly broad and does more than it needs to do.

It seems that the current concern is that InstrumentationLibrary as a concept does not fit some expected/traditional uses because "Library" is too large a scope for what some developers would expect to use to identify the logger they use. If a narrower scope is expected then I do not see why we need to completely upend the structure and semantics of the InstrumentationLibrary data in OTLP or the semantics of the existing APIs.

It is proposed that:

There are few places where changes are necessary:

The OTLP protocol can be changed following a "backwards" compatible approach:
* Rename "InstrumentationLibrary" to "Scope".
* Add "attributes" to the new Scope concept.
* Deprecate the current "name"/"version" in favor of semantic conventions for these fields in the new "attributes".

With some further discussion of what this means for the existing APIs and SDKs.

Instead, I think there is a single, simple change required:

• Add attributes to the InstrumentationLibrary

Doing this, coupled with defining semantic conventions for those attributes, would allow for further narrowing the scope of the InstrumentationLibrary to the point where it covered a single class or method or however users wished to use the flexibility it affords. This requires no changes to existing APIs or SDKs and does not break the expectations of existing users. It adds new control surfaces for users who want them and requires nothing of those that don't.

[dyladan]

Instead, I think there is a single, simple change required:

• Add attributes to the InstrumentationLibrary

Doing this, coupled with defining semantic conventions for those attributes, would allow for further narrowing the scope of the InstrumentationLibrary to the point where it covered a single class or method or however users wished to use the flexibility it affords. This requires no changes to existing APIs or SDKs and does not break the expectations of existing users. It adds new control surfaces for users who want them and requires nothing of those that don't.

Last week I thought we had agreed on a variation of this where scope was going to be added as an additional field without removing the existing instr lib name/version fields. That was fine with me and this version proposed by @Aneurysm9 is equally acceptable to me.

[Aneurysm9]

Adding attributes to InstrumentationLibrary was what I had in mind last week. Perhaps I was not clear about my thoughts if the expectation was that only a single new scalar field would be added. That would seem to be a stop-gap to me and likely to lead to further requests for additional scoping fields. Using a set of attributes moves that out of the data model/API realm and into the semantic conventions where we have at least the beginnings of a mechanism for schema evolution that would make changes potentially less impactful.