From 2cf2cf942b1669dc0a9422b30c5e91be6ae1edf9 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 1 Dec 2020 06:40:49 +0100 Subject: [PATCH 01/14] Define the fallback case for service.name --- specification/resource/semantic_conventions/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 24b98e93952..70d1e9edcf8 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -47,6 +47,9 @@ Certain attribute groups in this document have a **Required** column. For these | `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No | **[1]:** MUST be the same for all instances of horizontally scaled services. +Although this is a required attribute, if the value could not be specified SDKs +MUST fallback to a language-specific name based on the running service. +If this fallback fails, the name MUST default to `unknown_service`. **[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. From adb4a6f326c9c2221eaf85894829650046ddec15 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 1 Dec 2020 17:56:47 +0100 Subject: [PATCH 02/14] Update specification/resource/semantic_conventions/README.md Co-authored-by: Armin Ruech --- specification/resource/semantic_conventions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 70d1e9edcf8..deffde6a0e5 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -47,7 +47,7 @@ Certain attribute groups in this document have a **Required** column. For these | `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No | **[1]:** MUST be the same for all instances of horizontally scaled services. -Although this is a required attribute, if the value could not be specified SDKs +Although this is a required attribute, if the value was not specified, SDKs MUST fallback to a language-specific name based on the running service. If this fallback fails, the name MUST default to `unknown_service`. From 9199c75948851966b742719973a4554de924e777 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 2 Dec 2020 06:51:35 +0100 Subject: [PATCH 03/14] Add a mention of fallback values in Resource Creation. --- specification/resource/sdk.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index 55d63d2fb76..c161f9a3dda 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -34,6 +34,10 @@ The interface MUST provide a way to create a new resource, from [`Attributes`](. Examples include a factory method or a constructor for a resource object. A factory method is recommended to enable support for cached objects. +Note that certain **required** `Resource` specific attributes +MUST have fallback values if they were not specified, e.g. `service.name`. +See [Resource standard attributes]((semantic_conventions/README.md)). + Required parameters: - [`Attributes`](../common/common.md#attributes) From 4c8bc87d84583041b469d81ca1be704cadbfb85d Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 2 Dec 2020 06:57:17 +0100 Subject: [PATCH 04/14] Add details on the fallback name. --- specification/resource/semantic_conventions/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index deffde6a0e5..3a201d10a50 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -48,7 +48,8 @@ Certain attribute groups in this document have a **Required** column. For these **[1]:** MUST be the same for all instances of horizontally scaled services. Although this is a required attribute, if the value was not specified, SDKs -MUST fallback to a language-specific name based on the running service. +MUST fallback to a language-specific name based on the running service +(typically inferred from process name, language, plaform, etc). If this fallback fails, the name MUST default to `unknown_service`. **[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. From 85114d7a5ff45edf66a2b05ed04521ebbd92e89e Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 2 Dec 2020 07:08:51 +0100 Subject: [PATCH 05/14] Try to update the service.yaml definition. --- semantic_conventions/resource/service.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/semantic_conventions/resource/service.yaml b/semantic_conventions/resource/service.yaml index 78983d4d9b2..094c11d3879 100644 --- a/semantic_conventions/resource/service.yaml +++ b/semantic_conventions/resource/service.yaml @@ -11,6 +11,10 @@ groups: Logical name of the service. note: > MUST be the same for all instances of horizontally scaled services. + Although this is a required attribute, if the value was not specified, SDKs + MUST fallback to a language-specific name based on the running service + (typically inferred from process name, language, plaform, etc). + If this fallback fails, the name MUST default to `unknown_service`. examples: ["shoppingcart"] - id: namespace type: string From 2af2f4a8db7741fdff677171f4536b5f6cd4c283 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 2 Dec 2020 07:17:17 +0100 Subject: [PATCH 06/14] Update. --- specification/resource/semantic_conventions/README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 3a201d10a50..6f3c96fa22f 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -46,11 +46,7 @@ Certain attribute groups in this document have a **Required** column. For these | `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | Yes | | `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No | -**[1]:** MUST be the same for all instances of horizontally scaled services. -Although this is a required attribute, if the value was not specified, SDKs -MUST fallback to a language-specific name based on the running service -(typically inferred from process name, language, plaform, etc). -If this fallback fails, the name MUST default to `unknown_service`. +**[1]:** MUST be the same for all instances of horizontally scaled services. Although this is a required attribute, if the value was not specified, SDKs MUST fallback to a language-specific name based on the running service (typically inferred from process name, language, plaform, etc). If this fallback fails, the name MUST default to `unknown_service`. **[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. From 399aedc56f61756abe84507ef3afdd26719d1163 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 2 Dec 2020 23:49:03 +0100 Subject: [PATCH 07/14] Update specification/resource/sdk.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/resource/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index c161f9a3dda..189f137a363 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -36,7 +36,7 @@ object. A factory method is recommended to enable support for cached objects. Note that certain **required** `Resource` specific attributes MUST have fallback values if they were not specified, e.g. `service.name`. -See [Resource standard attributes]((semantic_conventions/README.md)). +See [Resource standard attributes](semantic_conventions/README.md). Required parameters: From 7d29c88d7d1d885b3a3ebd9f6a3a804f188a899f Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 8 Dec 2020 22:07:24 -0600 Subject: [PATCH 08/14] Apply more feedback. --- semantic_conventions/resource/service.yaml | 6 +++--- specification/resource/sdk.md | 5 ++--- specification/resource/semantic_conventions/README.md | 9 ++++++++- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/semantic_conventions/resource/service.yaml b/semantic_conventions/resource/service.yaml index 094c11d3879..de520f45efe 100644 --- a/semantic_conventions/resource/service.yaml +++ b/semantic_conventions/resource/service.yaml @@ -12,9 +12,9 @@ groups: note: > MUST be the same for all instances of horizontally scaled services. Although this is a required attribute, if the value was not specified, SDKs - MUST fallback to a language-specific name based on the running service - (typically inferred from process name, language, plaform, etc). - If this fallback fails, the name MUST default to `unknown_service`. + MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), + e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value + MUST be set to `unknown_service`. examples: ["shoppingcart"] - id: namespace type: string diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index 189f137a363..30e281cf372 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -34,9 +34,8 @@ The interface MUST provide a way to create a new resource, from [`Attributes`](. Examples include a factory method or a constructor for a resource object. A factory method is recommended to enable support for cached objects. -Note that certain **required** `Resource` specific attributes -MUST have fallback values if they were not specified, e.g. `service.name`. -See [Resource standard attributes](semantic_conventions/README.md). +Note that certain **required** `Resource` attributes MUST be set to a default value if they were not specified. +See [Attributes with Default Value](semantic_conventions/README.md#attributes-with-default-value). Required parameters: diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 6f3c96fa22f..151d6558bb1 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -9,6 +9,7 @@ This document defines standard attributes for resources. These attributes are ty - [TODOs](#todos) - [Document Conventions](#document-conventions) +- [Attributes with Default Value](#attributes-with-default-value) - [Service](#service) - [Telemetry SDK](#telemetry-sdk) - [Compute Unit](#compute-unit) @@ -32,6 +33,12 @@ Attributes are grouped logically by the type of the concept that they described. Certain attribute groups in this document have a **Required** column. For these groups if any attribute from the particular group is present in the Resource then all attributes that are marked as Required MUST be also present in the Resource. However it is also valid if the entire attribute group is omitted (i.e. none of the attributes from the particular group are present even though some of them are marked as Required in this document). +## Attributes with Default Value + +The SDK MUST set a default value for the following attributes if they were not specified: + +- (`service.name`)[#service] + ## Service **type:** `service` @@ -46,7 +53,7 @@ Certain attribute groups in this document have a **Required** column. For these | `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | Yes | | `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No | -**[1]:** MUST be the same for all instances of horizontally scaled services. Although this is a required attribute, if the value was not specified, SDKs MUST fallback to a language-specific name based on the running service (typically inferred from process name, language, plaform, etc). If this fallback fails, the name MUST default to `unknown_service`. +**[1]:** MUST be the same for all instances of horizontally scaled services. Although this is a required attribute, if the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. **[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. From e68dca8dd3cf2e36a2336d24e91eeecfed9d0665 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Tue, 8 Dec 2020 22:51:23 -0600 Subject: [PATCH 09/14] Fix bad style. --- specification/resource/semantic_conventions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 151d6558bb1..289028334e7 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -37,7 +37,7 @@ Certain attribute groups in this document have a **Required** column. For these The SDK MUST set a default value for the following attributes if they were not specified: -- (`service.name`)[#service] +- [`service.name`](#service) ## Service From 2e2a2fb83afa7ec67478a0a91b8933492020ad20 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 11 Dec 2020 17:44:22 +0100 Subject: [PATCH 10/14] Update specification/resource/semantic_conventions/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/resource/semantic_conventions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 289028334e7..69fcb173796 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -35,7 +35,7 @@ Certain attribute groups in this document have a **Required** column. For these ## Attributes with Default Value -The SDK MUST set a default value for the following attributes if they were not specified: +The SDK MUST set a default value for the following attributes if they were not specified, even if the resource would otherwise not be present at all: - [`service.name`](#service) From d629603a9324a621a943f82cb5736449facf0e97 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 11 Dec 2020 17:45:08 +0100 Subject: [PATCH 11/14] Update specification/resource/semantic_conventions/README.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Christian Neumüller --- specification/resource/semantic_conventions/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 69fcb173796..0946e029531 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -53,7 +53,7 @@ The SDK MUST set a default value for the following attributes if they were not s | `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | Yes | | `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No | -**[1]:** MUST be the same for all instances of horizontally scaled services. Although this is a required attribute, if the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. +**[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. **[2]:** A string value having a meaning that helps to distinguish a group of services, for example the team name that owns a group of services. `service.name` is expected to be unique within the same namespace. If `service.namespace` is not specified in the Resource then `service.name` is expected to be unique for all services that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace. From cd782972bb36088c511a1a26bdc62615734fad0b Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 11 Dec 2020 19:10:42 -0600 Subject: [PATCH 12/14] Re-run the semantic convention generation step. --- semantic_conventions/resource/service.yaml | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/semantic_conventions/resource/service.yaml b/semantic_conventions/resource/service.yaml index de520f45efe..4fa491f2023 100644 --- a/semantic_conventions/resource/service.yaml +++ b/semantic_conventions/resource/service.yaml @@ -11,10 +11,9 @@ groups: Logical name of the service. note: > MUST be the same for all instances of horizontally scaled services. - Although this is a required attribute, if the value was not specified, SDKs - MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), - e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value - MUST be set to `unknown_service`. + If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated + with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. + If `process.executable.name` is not available, the value MUST be set to `unknown_service`. examples: ["shoppingcart"] - id: namespace type: string From aa0dcccb26755fbdb855b11f780290241edae8e7 Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Fri, 11 Dec 2020 19:13:36 -0600 Subject: [PATCH 13/14] Make service.instance.id non-required. --- semantic_conventions/resource/service.yaml | 1 - specification/resource/semantic_conventions/README.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/semantic_conventions/resource/service.yaml b/semantic_conventions/resource/service.yaml index 4fa491f2023..efc53055fd5 100644 --- a/semantic_conventions/resource/service.yaml +++ b/semantic_conventions/resource/service.yaml @@ -30,7 +30,6 @@ groups: examples: ["Shop"] - id: instance.id type: string - required: always brief: > The string ID of the service instance. note: > diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 0946e029531..97617d694a6 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -50,7 +50,7 @@ The SDK MUST set a default value for the following attributes if they were not s |---|---|---|---|---| | `service.name` | string | Logical name of the service. [1] | `shoppingcart` | Yes | | `service.namespace` | string | A namespace for `service.name`. [2] | `Shop` | No | -| `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | Yes | +| `service.instance.id` | string | The string ID of the service instance. [3] | `627cc493-f310-47de-96bd-71410b7dec09` | No | | `service.version` | string | The version string of the service API or implementation. | `2.0.0` | No | **[1]:** MUST be the same for all instances of horizontally scaled services. If the value was not specified, SDKs MUST fallback to `unknown_service:` concatenated with [`process.executable.name`](process.md#process), e.g. `unknown_service:bash`. If `process.executable.name` is not available, the value MUST be set to `unknown_service`. From b63c3a0c0d59a7d83de8b2a3e6c8bcbee4fe621e Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Mon, 14 Dec 2020 09:23:07 -0600 Subject: [PATCH 14/14] Update CHANGELOG. --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index fe047dcf885..50b8d5b9e96 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,9 @@ Updates: ([#1257](https://github.com/open-telemetry/opentelemetry-specification/pull/1257)) - Add/Update `Status` + `error` mapping for Jaeger & Zipkin Exporters ([#1257](https://github.com/open-telemetry/opentelemetry-specification/pull/1257)) +- Resource's service.name MUST have a default value, service.instance.id is not + required. + ([#1269](https://github.com/open-telemetry/opentelemetry-specification/pull/1269)) ## v0.7.0 (11-18-2020)