From 276a395ec67396f7020d563055694deb119ccd29 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 14 Aug 2020 15:31:11 -0400 Subject: [PATCH 1/3] Add conventions for attribute names Resolves: https://github.com/open-telemetry/opentelemetry-specification/issues/726 --- specification/common/common.md | 82 +++++++++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/specification/common/common.md b/specification/common/common.md index 681721fb11b..4290eaaffd5 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -6,7 +6,7 @@ Table of Contents - [Attributes](#attributes) - + - [Attribute Naming](#attribute-naming) ## Attributes @@ -36,3 +36,83 @@ This is required for map/dictionary structures represented as two arrays with indices that are kept in sync (e.g., two attributes `header_keys` and `header_values`, both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). + +### Attribute Naming + +Attribute name (also known as the "attribute key") MUST be a valid Unicode +sequence. + +Attribute names SHOULD follow these rules: + +- Use namespacing to avoid name clashes. Delimit the namespaces using a dot + character. For example `service.version` denotes the service version where + `service` is the namespace and `version` is an attribute in that namespace. + +- Namespaces can be nested. For example `telemetry.sdk` is a namespace inside + top-level `telemetry` namespace and `telemetry.sdk.name` is an attribute + inside `telemetry.sdk` namespace. + +- For each multi-word dot-delimited component of the attribute name separate the + words by underscores (i.e. use snake_case). For example `http.status_code` + denotes the status code in the http namespace. + +- Attribute names should not coincide with namespaces. For example if + `service.instance.id` is an attribute name then it is no longer valid to have + an attribute named `service.instance` because `service.instance` is already a + namespace. Because of this rule be careful when choosing attribute names: + every existing attribute name prohibits existence of an equally named + namespace in the future, and vice versa: any existing namespace prohibits + existence of an equally named attribute in the future. + +#### Recommendations for OpenTelemetry Authors + +- All attributes names that are part of OpenTelemetry semantic conventions + SHOULD be part of a namespace. + +- When coming up with a new convention make sure to check existing namespaces + for + [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions), + [Spans](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions), + and + [Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions) + to see if the new attributes fits. + +- When a new namespace is necessary consider whether it should be a top-level + namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`). + +- Semantic conventions MUST limit attribute names to + [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) + subset of Unicode code points only. It is recommended to further limit + attribute names to the following Unicode code points: Latin alphabet, Numeric, + Underscore, Dot (as namespace delimiter). + +#### Recommendations for Application Developers + +As an application developer when you need to record an attribute first consult +existing semantic conventions for +[Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions), +[Spans](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions), +and +[Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions). +If appropriate attribute name does not exists you will need to come up with a +new name. To do that consider a few options: + +- The attribute is specific to your company. It is recommended to prefix the + attribute name by your company's reverse domain name, e.g. + `com.acme.shopname`. + +- The attribute is specific to your application. It is recommended to prefix the + attribute name by your application name, provided that the application name is + resonably unique and is not a generic enough word (e.g. + `myuniquemapapp.longitude` is likely fine). Make sure the application name + does not clash with an existing semantic convention namespace. If in doubt + prefix it with your company's reverse domain name. + +- It is recommended to limit attribute names to + [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) + subset of Unicode code points only. + +- The attribute may be generally applicable to applications in the industry. In + that case consider submitting a proposal to this specification to add a new + attribute to the semantic conventions, if necessary also to add a new + namespace for the attribute. From 64d8449be3ebe7f2ffcd2470e1c6157252f1157c Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 14 Aug 2020 16:12:16 -0400 Subject: [PATCH 2/3] Address PR comments --- specification/common/common.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 4290eaaffd5..99dff8d39c4 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -56,7 +56,7 @@ Attribute names SHOULD follow these rules: words by underscores (i.e. use snake_case). For example `http.status_code` denotes the status code in the http namespace. -- Attribute names should not coincide with namespaces. For example if +- Attribute names SHOULD NOT coincide with namespaces. For example if `service.instance.id` is an attribute name then it is no longer valid to have an attribute named `service.instance` because `service.instance` is already a namespace. Because of this rule be careful when choosing attribute names: @@ -66,7 +66,7 @@ Attribute names SHOULD follow these rules: #### Recommendations for OpenTelemetry Authors -- All attributes names that are part of OpenTelemetry semantic conventions +- All attribute names that are part of OpenTelemetry semantic conventions SHOULD be part of a namespace. - When coming up with a new convention make sure to check existing namespaces @@ -80,10 +80,11 @@ Attribute names SHOULD follow these rules: - When a new namespace is necessary consider whether it should be a top-level namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`). -- Semantic conventions MUST limit attribute names to +- Semantic conventions MUST limit attribute names to printable Basic Latin + characters (more precisely to [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) - subset of Unicode code points only. It is recommended to further limit - attribute names to the following Unicode code points: Latin alphabet, Numeric, + subset of Unicode code points). It is recommended to further limit attribute + names to the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot (as namespace delimiter). #### Recommendations for Application Developers @@ -108,9 +109,10 @@ new name. To do that consider a few options: does not clash with an existing semantic convention namespace. If in doubt prefix it with your company's reverse domain name. -- It is recommended to limit attribute names to +- It is recommended to limit attribute names to printable Basic Latin characters + (more precisely to [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) - subset of Unicode code points only. + subset of Unicode code points). - The attribute may be generally applicable to applications in the industry. In that case consider submitting a proposal to this specification to add a new From d26c821255e53b86362f2459649f0cf9ea6e0245 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Mon, 17 Aug 2020 11:01:56 -0400 Subject: [PATCH 3/3] Re-word company/application specific attribute recommendations --- specification/common/common.md | 32 ++++++++++++++++++-------------- 1 file changed, 18 insertions(+), 14 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 99dff8d39c4..62637d5ec9e 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -98,23 +98,27 @@ and If appropriate attribute name does not exists you will need to come up with a new name. To do that consider a few options: -- The attribute is specific to your company. It is recommended to prefix the - attribute name by your company's reverse domain name, e.g. - `com.acme.shopname`. - -- The attribute is specific to your application. It is recommended to prefix the - attribute name by your application name, provided that the application name is - resonably unique and is not a generic enough word (e.g. +- The attribute is specific to your company and may be possibly used outside the + company as well. To avoid name clashes with attributes introduced by other + companies (in a distributed system that uses applications from multiple + vendors) it is recommended to prefix the attribute name by your company's + reverse domain name, e.g. `com.acme.shopname`. + +- The attribute is specific to your application that will be used internally + only. If you already have an internal company process that helps you to ensure + no name clashes happen then feel free to follow it. Otherwise it is + recommended to prefix the attribute name by your application name, provided + that the application name is reasonably unique within your organization (e.g. `myuniquemapapp.longitude` is likely fine). Make sure the application name - does not clash with an existing semantic convention namespace. If in doubt - prefix it with your company's reverse domain name. - -- It is recommended to limit attribute names to printable Basic Latin characters - (more precisely to - [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) - subset of Unicode code points). + does not clash with an existing semantic convention namespace. - The attribute may be generally applicable to applications in the industry. In that case consider submitting a proposal to this specification to add a new attribute to the semantic conventions, if necessary also to add a new namespace for the attribute. + +It is recommended to limit attribute names to printable Basic Latin characters +(more precisely to +[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) +subset of Unicode code points). +