Refine description of Instrumentation Scope for Logs

CHANGELOG.md

@@ -22,6 +22,8 @@ release.
 
 - Fix `Resource` field type in Logs Data Model.
   ([#3826](https://github.com/open-telemetry/opentelemetry-specification/pull/3826))
+- Refine description of Instrumentation Scope.
+  ([#3855](https://github.com/open-telemetry/opentelemetry-specification/pull/3855))
 - Remove confusing description from `Body` field in Logs Data Model to make it clear the Bridge API must support a structured body.
   ([#3827](https://github.com/open-telemetry/opentelemetry-specification/pull/3827))
 - Deconstruct number scalar type to double and signed integer.

specification/common/README.md

@@ -124,8 +124,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

@@ -61,16 +61,13 @@ 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)
-  (e.g. `io.opentelemetry.contrib.mongodb`), 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.
+  such as the bridge implementation name. 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

@@ -428,17 +428,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 required.
 
 ### Field: `Attributes`