From cf13824d34dd8af92eaa8ab5be4f910a662cbbbd Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 11 Mar 2021 15:40:43 +0100 Subject: [PATCH 1/7] Define the fallback tracer name for invalid values. --- specification/trace/api.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index b2cd0f3147e..e15261f94c2 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -109,8 +109,10 @@ This API MUST accept the following parameters: 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 - default Tracer implementation as a fallback is returned rather than returning - null or throwing an exception. + default Tracer implementation as a fallback MUST be returned rather than returning + null or throwing an exception, and `name` SHOULD be the set to the + `` literal, in order to signal the + specified value is invalid. 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). From 7471fedc00d1cfe9af371048f59f2894628f5fe3 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 11 Mar 2021 18:29:24 +0100 Subject: [PATCH 2/7] Update specification/trace/api.md Co-authored-by: Armin Ruech --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index e15261f94c2..28cb1ad9e1a 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -109,7 +109,7 @@ This API MUST accept the following parameters: 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 - default Tracer implementation as a fallback MUST be returned rather than returning + default Tracer implementation MUST be returned as a fallback rather than returning null or throwing an exception, and `name` SHOULD be the set to the `` literal, in order to signal the specified value is invalid. From 9fcd5bb71d611795fc89f32714b3e67aa198bd8e Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Thu, 11 Mar 2021 18:29:55 +0100 Subject: [PATCH 3/7] Update specification/trace/api.md Co-authored-by: Armin Ruech --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 28cb1ad9e1a..7a51032f29c 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -111,7 +111,7 @@ This API MUST accept the following parameters: In case an invalid name (null or empty string) is specified, a working default Tracer implementation MUST be returned as a fallback rather than returning null or throwing an exception, and `name` SHOULD be the set to the - `` literal, in order to signal the + "``" literal, in order to signal that the specified value is invalid. 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" From 5a44a561451192d6cac7c81db9d0dce8f56df579 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 17 Mar 2021 01:00:41 +0100 Subject: [PATCH 4/7] Update based on feedback. --- specification/trace/api.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 5a0420b7a87..808f8188e43 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -110,9 +110,8 @@ This API MUST accept the following parameters: or application. In case an invalid name (null or empty string) is specified, a working default Tracer implementation MUST be returned as a fallback rather than returning - null or throwing an exception, and `name` SHOULD be the set to the - "``" literal, in order to signal that the - specified value is invalid. + null or throwing an exception, and `name` SHOULD keep the original invalid value, + with a log message reporting that the specified value is invalid. 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). From ad4e4d4f4bc4ccfc120d81616a0db01fee290e84 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 17 Mar 2021 01:05:18 +0100 Subject: [PATCH 5/7] Update CHANGELOG. --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 47b66683342..60e3050a1c9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,8 @@ release. - Add `ForceFlush` to `Span Exporter` interface ([#1467](https://github.com/open-telemetry/opentelemetry-specification/pull/1467)) - Clarify the description for the `TraceIdRatioBased` sampler needs to include the sampler's sampling ratio. ([#1536](https://github.com/open-telemetry/opentelemetry-specification/pull/1536)) +- Define the fallback tracer name for invalid values. + ([#1534](https://github.com/open-telemetry/opentelemetry-specification/pull/1534)) ### Metrics From 19a3c8095ebe82649fef998f7b690223d590ed90 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 17 Mar 2021 14:54:26 +0100 Subject: [PATCH 6/7] Update specification/trace/api.md Co-authored-by: Yuri Shkuro --- specification/trace/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 808f8188e43..285a8752e11 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -110,8 +110,8 @@ This API MUST accept the following parameters: or application. In case an invalid name (null or empty string) is specified, a working default Tracer implementation MUST be returned as a fallback rather than returning - null or throwing an exception, and `name` SHOULD keep the original invalid value, - with a log message reporting that the specified value is invalid. + null or throwing an exception, its `name` property SHOULD keep the original invalid value, + 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). From f71c6ff901b8789c0045cf25ec6bfcec2f5759b9 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 17 Mar 2021 14:55:22 +0100 Subject: [PATCH 7/7] Remove the mention of 'default' Tracer. --- specification/trace/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/api.md b/specification/trace/api.md index 285a8752e11..a50a3ccbc58 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -109,7 +109,7 @@ This API MUST accept the following parameters: 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 - default Tracer implementation MUST be returned as a fallback rather than returning + Tracer implementation MUST be returned as a fallback rather than returning null or throwing an exception, its `name` property SHOULD keep the original invalid value, 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