From d2abeaccd636be7c0939ed31de265373901fab70 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 25 Apr 2022 17:19:06 -0400 Subject: [PATCH] Introduce Scope Attributes There are a few reasons why Scope attributes are a good idea: - There are 2 known use cases where Scope attributes can solve specific problems: - Add support for [Meter "short_name"](https://github.com/open-telemetry/opentelemetry-specification/pull/2422), represented as an attribute of Meter's Scope. - Add support for differentiating the type of data emitted from the scopes that belong to different data domains, e.g. profiling data emitted as log records or client-side data emitted as log records needs to be differentiated so that it can be easily routed and processed differently in the backends. We don't have a good way to handle this today. The type of the data can be recorded as an attribute Logger's Scope. - It makes Scope consistent with other primary data types: Resource, Span, Metric, LogRecord. See additional [discussion here](https://github.com/open-telemetry/opentelemetry-specification/issues/2450). --- text/0000-scope-attributes.md | 123 ++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 text/0000-scope-attributes.md diff --git a/text/0000-scope-attributes.md b/text/0000-scope-attributes.md new file mode 100644 index 000000000..16ca333aa --- /dev/null +++ b/text/0000-scope-attributes.md @@ -0,0 +1,123 @@ +# Introduce Scope Attributes + +This OTEP adds attributes to the Scope. + +## Motivation + +There are a few reasons why Scope attributes are a good idea: +- There are 2 known use cases where Scope attributes can solve specific problems: + - Add support for [Meter "short_name"](https://github.com/open-telemetry/opentelemetry-specification/pull/2422), + represented as an attribute of Meter's Scope. + - Add support for differentiating the type of data emitted from the scopes that belong + to different data domains, e.g. profiling data emitted as log records or client-side + data emitted as log records needs to be differentiated so that it can be easily + routed and processed differently in the backends. We don't have a good way to handle + this today. The type of the data can be recorded as an attribute Logger's Scope. +- It makes Scope consistent with other primary data types: Resource, Span, Metric, LogRecord. + +See additional [discussion here](https://github.com/open-telemetry/opentelemetry-specification/issues/2450). + +## Explanation + +The following is the summary of proposed changes: + +- Extend OpenTelemetry API to allow specifying Scope attributes when obtaining a Tracer, + Meter or LogEmitter. Scope attributes will be optional. +- Add `attributes` field to the [InstrumentationScope](https://github.com/open-telemetry/opentelemetry-proto/blob/88faab1197a2a105c7da659951e94bc951d37ab9/opentelemetry/proto/common/v1/common.proto#L83) + message of OTLP. +- Telemetry emitted via a Scope-ed Tracer, Meter or LogEmitter will be associated + with the Scope's attributes. +- OTLP Exporter will record the attributes in the InstrumentationScope message. +- Non-OTLP Exporters will record the attributes at the most suitable place in their + corresponding format and prefix the attribute names by `otel.scope.`. +- Create a section for Scope attributes' semantic conventions in the specification. +- When converting from OTLP to other formats OpenTelemetry Collector will record + the attributes at the most suitable place in the target format and prefix the attribute + names by `otel.scope.`. + +## Internal details + +### API Changes + +`Get a Tracer` API will be extended to add the following parameter: +- `attributes` (optional): Specifies the instrumentation scope attributes to associate + with emitted telemetry. + +`Get a Metter` API will be extended to add the following parameter: +- `attributes` (optional): Specifies the instrumentation scope attributes to associate + with emitted telemetry. + +`Get LogEmitter` SDK call will be altered to the following: +Accepts the instrumentation scope name and optional version and attributes and +returns a LogEmitter associated with the instrumentation scope. + +Since the attributes are optional this is a backwards compatible change. + +### OTLP Changes + +The InstrumentationScope message in OTLP will be modified to add 2 new fields: +attributes and dropped_attributes_count: + +```protobuf +message InstrumentationScope { + string name = 1; + string version = 2; + repeated KeyValue attributes = 3; + uint32 dropped_attributes_count = 4; +} +``` + +This change is backwards compatible from OTLP's interoperability perspective. Recipients +of old OTLP versions will not see the Scope attributes and will ignore them, which we +consider acceptable from interoperability perspective. This is aligned with our general +stance on what happens when telemetry sources _add_ new data which old recipients +don't understand: we expect the new data to be safely ignored. + +## Prior art and alternatives + +The [Meter "short_name" PR](https://github.com/open-telemetry/opentelemetry-specification/pull/2422) +had an alternate approach where the "short_name" was added as the only attribute to the +InstrumentationScope. This OTEP's proposal generalizes this and allows arbitrary +attributes which allows them to be used for use cases. + +Differentiating the type of data emitted from the scopes that belong to different data +domains can be alternatively done by recording attributes on the Span, Metric or LogRecord. +However, this will be less efficient since it will require the same attributes to be +specified repeatedly on the wire. It will be also cumbersome to require the callers +to always specify such attributes when creating a Span, Metric or a LogRecord as +opposed to specifying them once when obtaining the Trace, Meter or LogEmitter. + +## Example Usage + +The following is an example usage where LogEmitter is used to emit client-side +log records (pseudocode follows): + +``` +// obtain a logger once, at startup. +logger = LogEmitterProvider.GetLogEmitter("mylibrary", "1.0.0", KeyValue("otel.clientside", true)) + +// somewhere later in the code +logger.emit(LogRecord{Body:"click", Attributes:...}) +``` + +## Open questions + +- When emitting telemetry in non-OTLP formats is prefixing the attribute names with + `otel.scope` the right approach or we should just record the attributes as is? + The answer to this probably depends on whether we want to see Scope attributes + as a totally separate namespace from Span/Metric/LogRecord attributes (see also next + question). +- Should allow/encourage recording Span/Metric/LogRecord attributes at the Scope level + and when done so do they carry exactly the same semantics as if they were recorded + on Span/Metric/LogRecord? If we allow this do we need to introduce any precendce rules + in case the same attribute is recorded in both places? + The alternate is to disallow this and have completely separate set of semantic + conventions that are allowed for Scope attributes. +- Can all existing APIs in all languages be safely modified to ensure the addition + of the optional attributes is not a breaking change? (It should be, since we did a very + similar change when we [introduced the Scope](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)) + +## Future possibilities + +If this OTEP is accepted we need to then introduce the relevant semantic conventions +that will make the 2 use cases [described earlier](#motivation) possible.