Clarify that Trace/Meter are associated with Instrumentation Scope

This is a slightly different take on open-telemetry#2203

Instead of renaming instrumentation library to instrumentation scope everywhere
this PR suggests targetted editing of wording of the Trace/Meter obtaining API
to allow not just instrumentation library but other instrumentation scopes to be
used as a parameter.

This change does not force renaming of API parameters and is not a breaking change.
We consider it a clarification of usage to match the intent that we had for the "name"
field.

If this PR is accepted there will be a follow up PR that will suggest to rename
InstrumentationLibrary* messages in OTLP proto to InstrumentationScope* message.
Such a change will not be a breaking change for the OTLP wire format and is acceptable.

If this PR is accepted we will also close open-telemetry#1236
since it will be no longer necessary. The logger name will be recorded as the
instrumentation scope. This clarification will be a follow up PR that clarifies the
behavior in https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md

CHANGELOG.md

@@ -17,6 +17,8 @@ release.
 - Add support for probability sampling in the OpenTelemetry `tracestate` entry and
   add optional specification for consistent probability sampling.
   ([#2047](https://github.com/open-telemetry/opentelemetry-specification/pull/2047))
+- Clarify that Tracer is associated with Instrumentation Scope
+  ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)).
 
 ### Metrics
 
@@ -41,6 +43,8 @@ release.
   [#2032](https://github.com/open-telemetry/opentelemetry-specification/pull/2061)
 - Changed default Prometheus Exporter host from `0.0.0.0` to `localhost`.
   ([#2282](https://github.com/open-telemetry/opentelemetry-specification/pull/2282))
+- Clarify that Meter is associated with Instrumentation Scope
+  ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)).
 
 ### Logs
 

specification/glossary.md

@@ -27,6 +27,7 @@ Some other fundamental terms are documented in the [overview document](overview.
   * [Exporter Library](#exporter-library)
   * [Instrumented Library](#instrumented-library)
   * [Instrumentation Library](#instrumentation-library)
+  * [Instrumentation Scope](#instrumentation-scope)
   * [Tracer Name / Meter Name](#tracer-name--meter-name)
   * [Execution Unit](#execution-unit)
 - [Logs](#logs)
@@ -151,11 +152,31 @@ Example: `io.opentelemetry.contrib.mongodb`.
 
 Synonyms: *Instrumenting Library*.
 
+### Instrumentation Scope
+
+A logical unit of the application code with which the emitted telemetry can be
+associated with. It is typically the developer's choice to decide what denotes a
+reasonable instrumentation scope. The most common approach is to use the
+[instrumentation library](#instrumentation-library) as the scope, however other
+scopes are also common, e.g. a module, a package, or a class can be chosen as
+the instrumentation scope.
+
+If the unit of code has a version then the instrumentation scope is defined by
+the (name,version) pair otherwise the version is omitted and only the name is
+used.
+
+The instrumentation scope is used to obtain a
+[Tracer or Meter](#tracer-name--meter-name).
+
 ### Tracer Name / Meter Name
 
 This refers to the `name` and (optional) `version` arguments specified when
-creating a new `Tracer` or `Meter` (see [Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider)).
-The name/version pair identifies the [Instrumentation Library](#instrumentation-library).
+creating a new `Tracer` or `Meter` (see
+[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider)).
+The name/version pair identifies the
+[Instrumentation Scope](#instrumentation-scope), for example the
+[Instrumentation Library](#instrumentation-library) or another unit of
+application in the scope of which the telemetry is emitted.
 
 ### Execution Unit
 

specification/metrics/api.md

@@ -108,8 +108,9 @@ The `MeterProvider` MUST provide the following functions:
 This API MUST accept the following parameters:
 
 * `name` (required): This name must identify the [instrumentation
-  library](../overview.md#instrumentation-libraries) (e.g.
-  `io.opentelemetry.contrib.mongodb`). If an application or library has built-in
+  scope](../glossary.md#instrumentation-scope) (e.g.
+  `io.opentelemetry.contrib.mongodb`), such as the instrumentation library,
+  package, module or class name. If an application or library has built-in
   OpenTelemetry instrumentation, both [Instrumented
   library](../glossary.md#instrumented-library) and [Instrumentation
   library](../glossary.md#instrumentation-library) may refer to the same

specification/trace/api.md

@@ -106,22 +106,24 @@ The `TracerProvider` MUST provide the following functions:
 
 This API MUST accept the following parameters:
 
-- `name` (required): This name must identify the [instrumentation library](../overview.md#instrumentation-libraries)
-  (e.g. `io.opentelemetry.contrib.mongodb`).
-  If an application or library has built-in OpenTelemetry instrumentation, both
+- `name` (required): This name must identify the [instrumentation
+  scope](../glossary.md#instrumentation-scope) (e.g.
+  `io.opentelemetry.contrib.mongodb`), such as the instrumentation library,
+  package, module or class name. If an application or library has built-in
+  OpenTelemetry instrumentation, both
   [Instrumented library](../glossary.md#instrumented-library) and
-  [Instrumentation library](../glossary.md#instrumentation-library) may refer to the same library.
-  In that scenario, the `name` denotes a module name or component name within that library
-  or application.
-  In case an invalid name (null or empty string) is specified, a working
-  Tracer implementation MUST be returned as a fallback rather than returning
-  null or throwing an exception, its `name` property SHOULD be set to an **empty** string,
-  and a message reporting that the specified value is invalid SHOULD be logged.
-  A library, implementing the OpenTelemetry API *may* also ignore this name and
-  return a default instance for all calls, if it does not support "named"
-  functionality (e.g. an implementation which is not even observability-related).
-  A TracerProvider could also return a no-op Tracer here if application owners configure
-  the SDK to suppress telemetry produced by this library.
+  [Instrumentation library](../glossary.md#instrumentation-library) may refer to
+  the same library. In that scenario, the `name` denotes a module name or
+  component name within that library or application. In case an invalid name
+  (null or empty string) is specified, a working Tracer implementation MUST be
+  returned as a fallback rather than returning null or throwing an exception,
+  its `name` property SHOULD be set to an **empty** string, and a message
+  reporting that the specified value is invalid SHOULD be logged. A library,
+  implementing the OpenTelemetry API *may* also ignore this name and return a
+  default instance for all calls, if it does not support "named" functionality
+  (e.g. an implementation which is not even observability-related). A
+  TracerProvider could also return a no-op Tracer here if application owners
+  configure the SDK to suppress telemetry produced by this library.
 - `version` (optional): Specifies the version of the instrumentation library (e.g. `1.0.0`).
 - [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be
   recorded in the emitted telemetry.