Refine description of Instrumentation Scope for Logs (#3855)

Fixes
#3841

## Changes

- Update "Instrumentation Scope" term in glossary.
- Update "Attribute Collections" (in common definitions) to include
instrumentation scope attributes.
- Change the instrumentation scope type definition from `(Name,Version)
tuple of strings` to Instrumentation Scope definition (as the current
definition misses Scheme URL and Attributes).
- Refer to `InstrumentationScope` Data Model field in Bridge API to make
the spec easier to follow.
- Move the part relevant to Bridge API usage from the Data Model.
- Remove "Version is optional. Name SHOULD be specified if version is
specified, otherwise Name is optional." which should act as
recommendation in the API. But the API already contains information how
the parameters should be used.

---------

Co-authored-by: Reiley Yang <[email protected]>
Co-authored-by: Tigran Najaryan <[email protected]>

CHANGELOG.md

@@ -15,6 +15,9 @@ release.
 
 ### Logs
 
+- Refine description of Instrumentation Scope.
+  ([#3855](https://github.com/open-telemetry/opentelemetry-specification/pull/3855))
+
 ### Events
 
 ### Resource

specification/common/README.md

@@ -155,8 +155,9 @@ at this time, as discussed in
 
 ## Attribute Collections
 
-[Resources](../resource/sdk.md), Metrics
-[data points](../metrics/data-model.md#metric-points),
+[Resources](../resource/sdk.md),
+[Instrumentation Scopes](../glossary.md#instrumentation-scope),
+[Metric points](../metrics/data-model.md#metric-points),
 [Spans](../trace/api.md#set-attributes), Span
 [Events](../trace/api.md#add-events), Span
 [Links](../trace/api.md#link) and

specification/glossary.md

@@ -28,7 +28,7 @@ Some other fundamental terms are documented in the [overview document](overview.
   * [Instrumented Library](#instrumented-library)
   * [Instrumentation Library](#instrumentation-library)
   * [Instrumentation Scope](#instrumentation-scope)
-  * [Tracer Name / Meter Name](#tracer-name--meter-name)
+  * [Tracer Name / Meter Name / Logger Name](#tracer-name--meter-name--logger-name)
   * [Execution Unit](#execution-unit)
 - [Logs](#logs)
   * [Log Record](#log-record)
@@ -169,19 +169,19 @@ fully qualified name of the emitting code (e.g. fully qualified library name or
 fully qualified class name).
 
 The instrumentation scope is used to obtain a
-[Tracer or Meter](#tracer-name--meter-name).
+[Tracer, Meter, or Logger](#tracer-name--meter-name--logger-name).
 
 The instrumentation scope may have zero or more additional attributes that provide
 additional information about the scope. For example for a scope that specifies an
 instrumentation library an additional attribute may be recorded to denote the URL of the
 repository URL the library's source code is stored. Since the scope is a build-time
 concept the attributes of the scope cannot change at runtime.
 
-### Tracer Name / Meter Name
+### Tracer Name / Meter Name / Logger 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)).
+[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/bridge-api.md#loggerprovider).
 The name/version pair identifies the
 [Instrumentation Scope](#instrumentation-scope), for example the
 [Instrumentation Library](#instrumentation-library) or another unit of

specification/logs/bridge-api.md

@@ -58,7 +58,8 @@ The `LoggerProvider` MUST provide the following functions:
 
 #### Get a Logger
 
-This API MUST accept the following parameters:
+This API MUST accept the following [instrumentation scope](data-model.md#field-instrumentationscope)
+parameters:
 
 * `name`: This name uniquely identifies the [instrumentation scope](../glossary.md#instrumentation-scope),
   such as the [instrumentation library](../glossary.md#instrumentation-library)
@@ -68,6 +69,9 @@ This API MUST accept the following parameters:
   [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.
+  For log sources which define a logger name (e.g. Java
+  [Logger Name](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)))
+  the Logger Name should be recorded as the instrumentation scope name.
 
 * `version` (optional): Specifies the version of the instrumentation scope if
   the scope has a version (e.g. a library version). Example value: 1.0.0.

specification/logs/data-model.md

@@ -430,17 +430,11 @@ This field is optional.
 
 ### Field: `InstrumentationScope`
 
-Type: (Name,Version) tuple of strings.
+Type: [Instrumentation Scope](../glossary.md#instrumentation-scope).
 
 Description: the [instrumentation scope](../glossary.md#instrumentation-scope).
 Multiple occurrences of events coming from the same scope can happen across time and
-they all have the same value of `InstrumentationScope`. For log sources which define
-a logger name (e.g. Java
-[Logger Name](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)))
-the Logger Name SHOULD be recorded as the Instrumentation Scope name.
-
-Version is optional. Name SHOULD be specified if version is specified, otherwise Name
-is optional.
+they all have the same value of `InstrumentationScope`. This field is optional.
 
 ### Field: `Attributes`