From 9fca5e275634df8f80fe05f25eb1a8299123aeb4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 14 Mar 2024 12:19:23 -0400 Subject: [PATCH 1/2] [editorial] Adjust exporter page titles in Metrics and Traces (#3940) Co-authored-by: Reiley Yang Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- specification/metrics/sdk_exporters/in-memory.md | 2 +- specification/metrics/sdk_exporters/otlp.md | 2 +- specification/metrics/sdk_exporters/prometheus.md | 2 +- specification/metrics/sdk_exporters/stdout.md | 2 +- specification/trace/sdk_exporters/stdout.md | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md index 8171ba4be39..3a37039a064 100644 --- a/specification/metrics/sdk_exporters/in-memory.md +++ b/specification/metrics/sdk_exporters/in-memory.md @@ -2,7 +2,7 @@ linkTitle: In-memory ---> -# OpenTelemetry Metrics Exporter - In-memory +# Metrics Exporter - In-memory **Status**: [Stable](../../document-status.md) diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md index a81aab3961a..545c63e3a81 100644 --- a/specification/metrics/sdk_exporters/otlp.md +++ b/specification/metrics/sdk_exporters/otlp.md @@ -2,7 +2,7 @@ linkTitle: OTLP ---> -# OpenTelemetry Metrics Exporter - OTLP +# Metrics Exporter - OTLP **Status**: [Stable](../../document-status.md) diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md index d96c1009319..5506b99870d 100644 --- a/specification/metrics/sdk_exporters/prometheus.md +++ b/specification/metrics/sdk_exporters/prometheus.md @@ -2,7 +2,7 @@ linkTitle: Prometheus ---> -# OpenTelemetry Metrics Exporter - Prometheus +# Metrics Exporter - Prometheus **Status**: [Experimental](../../document-status.md) diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md index 4b39ca2861c..fa336eced62 100644 --- a/specification/metrics/sdk_exporters/stdout.md +++ b/specification/metrics/sdk_exporters/stdout.md @@ -2,7 +2,7 @@ linkTitle: Stdout ---> -# OpenTelemetry Metrics Exporter - Standard output +# Metrics Exporter - Standard output **Status**: [Stable](../../document-status.md) diff --git a/specification/trace/sdk_exporters/stdout.md b/specification/trace/sdk_exporters/stdout.md index 0ec93f343b5..3eb23b488f2 100644 --- a/specification/trace/sdk_exporters/stdout.md +++ b/specification/trace/sdk_exporters/stdout.md @@ -2,7 +2,7 @@ linkTitle: Stdout ---> -# OpenTelemetry Span Exporter - Standard output +# Span Exporter - Standard output **Status**: [Stable](../../document-status.md) From 6787e14e77ec5083c9e314be808fb0e115dc4ca4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 15 Mar 2024 15:35:42 +0100 Subject: [PATCH 2/2] Refine description of Instrumentation Scope for Logs (#3855) Fixes https://github.com/open-telemetry/opentelemetry-specification/issues/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 Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> --- CHANGELOG.md | 3 +++ specification/common/README.md | 5 +++-- specification/glossary.md | 8 ++++---- specification/logs/bridge-api.md | 6 +++++- specification/logs/data-model.md | 10 ++-------- 5 files changed, 17 insertions(+), 15 deletions(-) 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`