diff --git a/CHANGELOG.md b/CHANGELOG.md index 00e771629d1..3487c0c1609 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/specification/common/README.md b/specification/common/README.md index ea218cc7ce2..b0d110b22f4 100644 --- a/specification/common/README.md +++ b/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 diff --git a/specification/glossary.md b/specification/glossary.md index 1944b7387af..15637e61d45 100644 --- a/specification/glossary.md +++ b/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,7 +169,7 @@ 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 @@ -177,11 +177,11 @@ instrumentation library an additional attribute may be recorded to denote the UR 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 diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 610fa4862c7..1686ce11dba 100644 --- a/specification/logs/bridge-api.md +++ b/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. diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index b03459e4cc7..cde901399f6 100644 --- a/specification/logs/data-model.md +++ b/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`