From d541ee789dd3b725edb17969824ee0f34d1882d1 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Wed, 22 Jul 2020 11:30:11 -0700 Subject: [PATCH 01/56] Centralize attributes definition (#722) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Centralize attributes definition Signed-off-by: Bogdan Drutu * Update specification/common/common.md Co-authored-by: Christian Neumüller * Update specification/common/common.md Co-authored-by: Christian Neumüller * Update specification/common/common.md Co-authored-by: Christian Neumüller * Update specification/common/common.md Co-authored-by: Christian Neumüller * Update specification/common/common.md Co-authored-by: Christian Neumüller * Update specification/common/common.md Co-authored-by: Christian Neumüller * Update specification/overview.md Co-authored-by: Christian Neumüller Co-authored-by: Christian Neumüller --- specification/common/common.md | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) create mode 100644 specification/common/common.md diff --git a/specification/common/common.md b/specification/common/common.md new file mode 100644 index 0000000000..b8d99a5eef --- /dev/null +++ b/specification/common/common.md @@ -0,0 +1,29 @@ +# Common specification concepts + +
+ +Table of Contents + + +- [Attributes](#attribute) + +
+ +## Attributes + +Attributes are a list of zero or more key-value pairs. An `Attribute` MUST have the following properties: + +- The attribute key, which MUST be a non-`null` and non-empty string. +- The attribute value, which is either: + - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer. + - An array of primitive type values. The array MUST be homogeneous, + i.e. it MUST NOT contain values of different types. For protocols that do + not natively support array values such values SHOULD be represented as JSON strings. + +`null` values within arrays MUST be preserved as-is (i.e., passed on to span +processors / exporters as `null`). If exporters do not support exporting `null` +values, they MAY replace those values by 0, `false`, or empty strings. +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]`). From a2fe1a32b4355b7fdc27984e2d8c59a3fa27ed16 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 27 Jul 2020 10:51:44 -0700 Subject: [PATCH 02/56] DocFX sanity check (#742) --- specification/common/common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/common.md b/specification/common/common.md index b8d99a5eef..b55f47c1bb 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -5,7 +5,7 @@ Table of Contents -- [Attributes](#attribute) +- [Attributes](#attributes) From 3f8bc51558fb1c991cfe6d11d65cd5e75b011a3a Mon Sep 17 00:00:00 2001 From: Giovanni Liva Date: Thu, 13 Aug 2020 19:10:46 +0200 Subject: [PATCH 03/56] Consistency between Span and Resource attributes (#777) * Consistency between Span and Resource attributes * Address feedback * Wording --- specification/common/common.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index b55f47c1bb..681721fb11 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -20,6 +20,15 @@ Attributes are a list of zero or more key-value pairs. An `Attribute` MUST have i.e. it MUST NOT contain values of different types. For protocols that do not natively support array values such values SHOULD be represented as JSON strings. +Attributes SHOULD preserve the order in which they're set. + +Attribute values expressing a numerical value of zero, an empty string, or an +empty array are considered meaningful and MUST be stored and passed on to +processors / exporters. Attribute values of `null` are considered to be not set +and get discarded as if that `Attribute` has never been created. +As an exception to this, if overwriting of values is supported, this results in +removing the attribute. + `null` values within arrays MUST be preserved as-is (i.e., passed on to span processors / exporters as `null`). If exporters do not support exporting `null` values, they MAY replace those values by 0, `false`, or empty strings. From 79d41669f42e5a16467d32f8e5db51e4c2fb50b2 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Mon, 17 Aug 2020 12:40:17 -0400 Subject: [PATCH 04/56] Add conventions for attribute names (#807) * Add conventions for attribute names Resolves: https://github.com/open-telemetry/opentelemetry-specification/issues/726 * Address PR comments * Re-word company/application specific attribute recommendations --- specification/common/common.md | 88 +++++++++++++++++++++++++++++++++- 1 file changed, 87 insertions(+), 1 deletion(-) diff --git a/specification/common/common.md b/specification/common/common.md index 681721fb11..62637d5ec9 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,89 @@ 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 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 + 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 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). 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 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. + +- 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). + From 00959df881843dc2606d45c350ed3d6627db8470 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Wed, 19 Aug 2020 13:49:28 -0400 Subject: [PATCH 05/56] Extend attribute naming rules to metric labels (#821) * Extend attribute naming rules to metric labels We earlier defined naming rules for attributes, however we do not have similar rules for metric labels. This commit extends the exact same set of rules to metric labels. This was brought up in this comment https://github.com/open-telemetry/opentelemetry-specification/pull/807#discussion_r471550053 * Address PR comments --- specification/common/common.md | 95 +++++++++++++++++++--------------- 1 file changed, 52 insertions(+), 43 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 62637d5ec9..7cedad5f3f 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -6,7 +6,7 @@ Table of Contents - [Attributes](#attributes) - - [Attribute Naming](#attribute-naming) + - [Attribute and Label Naming](#attribute-and-label-naming) ## Attributes @@ -37,12 +37,22 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). -### Attribute Naming +## Attribute and Label Naming -Attribute name (also known as the "attribute key") MUST be a valid Unicode -sequence. +_This section applies to Resource, Span and Log attribute names (also known as +the "attribute keys") and to keys of Metric labels. For brevity within this +section when we use the term "name" without an adjective it is implied to mean +"attribute name or metric label key"._ -Attribute names SHOULD follow these rules: +Every name MUST be a valid Unicode sequence. + +_Note: we merely require that the names are represented as Unicode sequences. +This specification does not define how exactly the Unicode sequences are +encoded. The encoding can vary from one programming language to another and from +one wire format to another. Use the idiomatic way to represent Unicode in the +particular programming language or wire format._ + +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 @@ -56,68 +66,67 @@ 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 +- 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. + namespace. Because of this rule be careful when choosing names: every existing + name prohibits existence of an equally named namespace in the future, and vice + versa: any existing namespace prohibits existence of an equally named + attribute or label key in the future. -#### Recommendations for OpenTelemetry Authors +### Recommendations for OpenTelemetry Authors -- All attribute names that are part of OpenTelemetry semantic conventions - SHOULD be part of a namespace. +- All 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 +- When coming up with a new semantic 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. + to see if the new name 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 printable Basic Latin - characters (more precisely to +- Semantic conventions MUST limit 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). It is recommended to further limit attribute - names to the following Unicode code points: Latin alphabet, Numeric, - Underscore, Dot (as namespace delimiter). + subset of Unicode code points). It is recommended to further limit names to + the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot + (as namespace delimiter). -#### Recommendations for Application Developers +### Recommendations for Application Developers -As an application developer when you need to record an attribute first consult -existing semantic conventions for +As an application developer when you need to record an attribute or a label +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 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. +If an appropriate name does not exists you will need to come up with a new name. +To do that consider a few options: + +- The name is specific to your company and may be possibly used outside the + company as well. To avoid clashes with names introduced by other companies (in + a distributed system that uses applications from multiple vendors) it is + recommended to prefix the new name by your company's reverse domain name, e.g. + `com.acme.shopname`. + +- The name 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 or label key 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. -- 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. +- The name may be generally applicable to applications in the industry. In that + case consider submitting a proposal to this specification to add a new name to + the semantic conventions, and if necessary also to add a new namespace. -It is recommended to limit attribute names to printable Basic Latin characters +It is recommended to limit 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). From 56f773081f0750cb1f81ff22be1fe1e6adbd52f6 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Wed, 19 Aug 2020 14:43:05 -0700 Subject: [PATCH 06/56] Fix lint check in makefile, fix errors (#837) Signed-off-by: Bogdan Drutu --- specification/common/common.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/common.md b/specification/common/common.md index 7cedad5f3f..f6a917b4cf 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -7,6 +7,7 @@ Table of Contents - [Attributes](#attributes) - [Attribute and Label Naming](#attribute-and-label-naming) + ## Attributes @@ -130,4 +131,3 @@ It is recommended to limit 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). - From 596379ff14b7849a63bfe7a7973a1424765be232 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Mon, 24 Aug 2020 13:14:37 -0400 Subject: [PATCH 07/56] Require that names and namespaces are one global space across all semantic convention areas (#832) * Require that names and namespaces are one global space across all semantic convention areas We have semantic conventions for Resources, Spans and Metrics (in the future also Logs are expected). It was not clear if the attribute names across all convention areas should be globally unique. This commit asserts that conventions are one space, they are not independent spaces with their own namespaces each. We prohibit using the same Span or Resource attribute name or metric label name but give them slightly different meanings or value sets. Resolves: https://github.com/open-telemetry/opentelemetry-specification/issues/815 * Address PR comments Co-authored-by: Bogdan Drutu --- specification/common/common.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index f6a917b4cf..44f5ccf2f5 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -91,6 +91,15 @@ 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 exist for four areas: for Resource, Span and Log + attribute names as well as Metric label keys. In addition, for spans we have + two more areas: Event and Link attribute names. Identical namespaces or names + in all these areas MUST have identical meanings. For example the `http.method` + span attribute name denotes exactly the same concept as the `http.method` + metric label, has the same data type and the same set of possible values (in + both cases it records the value of the HTTP protocol's request method as a + string). + - Semantic conventions MUST limit 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) From f52034ca043ba29f12ceecb4fa0f7d0ccb976a29 Mon Sep 17 00:00:00 2001 From: Armin Ruech Date: Fri, 25 Sep 2020 11:49:15 +0200 Subject: [PATCH 08/56] Define `null` as an invalid value for attributes and declare attempts to set `null` as undefined behavior (#992) --- specification/common/common.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 44f5ccf2f5..974cf51821 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -25,10 +25,10 @@ Attributes SHOULD preserve the order in which they're set. Attribute values expressing a numerical value of zero, an empty string, or an empty array are considered meaningful and MUST be stored and passed on to -processors / exporters. Attribute values of `null` are considered to be not set -and get discarded as if that `Attribute` has never been created. -As an exception to this, if overwriting of values is supported, this results in -removing the attribute. +processors / exporters. + +Attribute values of `null` are not valid and attempting to set a `null` value is +undefined behavior. `null` values within arrays MUST be preserved as-is (i.e., passed on to span processors / exporters as `null`). If exporters do not support exporting `null` From 89262a0119acf250eb4cf86785952aa1dd69ef98 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 4 Nov 2020 21:29:48 +0100 Subject: [PATCH 09/56] Fix absolute links to spec (#1192) * Remove absolute links where possible. * Work around semantic conventions. * Docfx. * Fix YAML. * More docfx. --- specification/common/common.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 974cf51821..0352f819ab 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -82,10 +82,10 @@ Names SHOULD follow these rules: - When coming up with a new semantic 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), + [Resources](../resource/semantic_conventions/README.md), + [Spans](../trace/semantic_conventions/README.md), and - [Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions) + [Metrics](../metrics/semantic_conventions/README.md) to see if the new name fits. - When a new namespace is necessary consider whether it should be a top-level @@ -111,10 +111,10 @@ Names SHOULD follow these rules: As an application developer when you need to record an attribute or a label 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), +[Resources](../resource/semantic_conventions/README.md), +[Spans](../trace/semantic_conventions/README.md), and -[Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions). +[Metrics](../metrics/semantic_conventions/README.md). If an appropriate name does not exists you will need to come up with a new name. To do that consider a few options: From b8ab1015169249a30c871658a099abc5affe9fbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Tue, 10 Nov 2020 17:05:58 +0100 Subject: [PATCH 10/56] Remove ordering reqirement for attributes. (#1212) * Remove ordering for attributes. * Fill in CHANGELOG link --- specification/common/common.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 0352f819ab..fca4b007a1 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -21,8 +21,6 @@ Attributes are a list of zero or more key-value pairs. An `Attribute` MUST have i.e. it MUST NOT contain values of different types. For protocols that do not natively support array values such values SHOULD be represented as JSON strings. -Attributes SHOULD preserve the order in which they're set. - Attribute values expressing a numerical value of zero, an empty string, or an empty array are considered meaningful and MUST be stored and passed on to processors / exporters. From ccef73a2020018078b1ad3a19d7a8ad3340a01c1 Mon Sep 17 00:00:00 2001 From: Przemek Maciolek <58699843+pmm-sumo@users.noreply.github.com> Date: Tue, 10 Nov 2020 21:19:52 +0100 Subject: [PATCH 11/56] Include attribute name pluralization guidelines (#1115) (#1140) --- specification/common/common.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index fca4b007a1..3a759e09e0 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -7,6 +7,9 @@ Table of Contents - [Attributes](#attributes) - [Attribute and Label Naming](#attribute-and-label-naming) + - [Name Pluralization Guidelines](#name-pluralization-guidelines) + - [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) + - [Recommendations for Application Developers](#recommendations-for-application-developers) @@ -72,6 +75,19 @@ Names SHOULD follow these rules: name prohibits existence of an equally named namespace in the future, and vice versa: any existing namespace prohibits existence of an equally named attribute or label key in the future. + +### Name Pluralization guidelines + +- When an attribute represents a single entity, the attribute name SHOULD be singular. + Examples: `host.name`, `db.user`, `container.id`. + +- When attribute can represent multiple entities, the attribute name SHOULD be pluralized + and the value type SHOULD be an array. E.g. `process.command_args` might include multiple + values: the executable name and command arguments. + +- When an attribute represents a measurement, + [Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization) + SHOULD be followed for the attribute name. ### Recommendations for OpenTelemetry Authors From e99bc0be7df3409a96e22f52b60c12344c4cea78 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Tue, 10 Nov 2020 15:51:16 -0500 Subject: [PATCH 12/56] Add guidance on when to use and not use nested namespaces (#1197) This topic has come up at least 3 times now. I believe a clarification is warranted. The clarification is aligned with previous recommendations: https://github.com/open-telemetry/opentelemetry-specification/pull/789#issuecomment-675506855 https://github.com/open-telemetry/opentelemetry-specification/pull/882#issuecomment-690945900 https://github.com/open-telemetry/opentelemetry-specification/pull/1194#issuecomment-722431982 --- specification/common/common.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index 3a759e09e0..15d25304c4 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -63,6 +63,10 @@ Names SHOULD follow these rules: - 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. + Note: the fact that an entity is located within another entity is typically + not a sufficient reason for forming nested namespaces. The purpose of a + namespace is to avoid name clashes, not to indicate entity hierarchies. This + purpose should primarily drive the decision about forming nested namespaces. - 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` From 640a5c5413d8b951bb58f1775ede42da81cf4b15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Wed, 11 Nov 2020 02:15:41 +0100 Subject: [PATCH 13/56] Nulls SHOULD NOT be allowed in arrays. (#1214) * Nulls SHOULD NOT be allowed in arrays. * Fill in CHANGELOG link Co-authored-by: Armin Ruech --- specification/common/common.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index 15d25304c4..f1526b9518 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -31,6 +31,9 @@ processors / exporters. Attribute values of `null` are not valid and attempting to set a `null` value is undefined behavior. +`null` values SHOULD NOT be allowed in arrays. However, if it is impossible to +make sure that no `null` values are accepted +(e.g. in languages that do not have appropriate compile-time type checking), `null` values within arrays MUST be preserved as-is (i.e., passed on to span processors / exporters as `null`). If exporters do not support exporting `null` values, they MAY replace those values by 0, `false`, or empty strings. From 49b70ba92699f3beb399d410fb7e132b38a05aa5 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Tue, 17 Nov 2020 16:41:56 -0500 Subject: [PATCH 14/56] Declare freeze of Trace API Specification 1.0 (#1121) * Declare freeze of Trace Specification 1.0 We want to freeze Trace specification 1.0 so that we no longer accept substantial changes (unless a fundamental problem is found in the spec). Resolves https://github.com/open-telemetry/opentelemetry-specification/issues/1120 --- .../common/attribute-and-label-naming.md | 130 ++++++++++++++++++ specification/common/common.md | 126 +---------------- 2 files changed, 133 insertions(+), 123 deletions(-) create mode 100644 specification/common/attribute-and-label-naming.md diff --git a/specification/common/attribute-and-label-naming.md b/specification/common/attribute-and-label-naming.md new file mode 100644 index 0000000000..d84eab4c62 --- /dev/null +++ b/specification/common/attribute-and-label-naming.md @@ -0,0 +1,130 @@ +# Attribute and Label Naming + +
+ +Table of Contents + + +- [Name Pluralization Guidelines](#name-pluralization-guidelines) +- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) +- [Recommendations for Application Developers](#recommendations-for-application-developers) + +
+ +_This section applies to Resource, Span and Log attribute names (also known as +the "attribute keys") and to keys of Metric labels. For brevity within this +section when we use the term "name" without an adjective it is implied to mean +"attribute name or metric label key"._ + +Every name MUST be a valid Unicode sequence. + +_Note: we merely require that the names are represented as Unicode sequences. +This specification does not define how exactly the Unicode sequences are +encoded. The encoding can vary from one programming language to another and from +one wire format to another. Use the idiomatic way to represent Unicode in the +particular programming language or wire format._ + +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. + Note: the fact that an entity is located within another entity is typically + not a sufficient reason for forming nested namespaces. The purpose of a + namespace is to avoid name clashes, not to indicate entity hierarchies. This + purpose should primarily drive the decision about forming nested namespaces. + +- 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. + +- 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 names: every existing + name prohibits existence of an equally named namespace in the future, and vice + versa: any existing namespace prohibits existence of an equally named + attribute or label key in the future. + +## Name Pluralization guidelines + +- When an attribute represents a single entity, the attribute name SHOULD be singular. + Examples: `host.name`, `db.user`, `container.id`. + +- When attribute can represent multiple entities, the attribute name SHOULD be pluralized + and the value type SHOULD be an array. E.g. `process.command_args` might include multiple + values: the executable name and command arguments. + +- When an attribute represents a measurement, + [Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization) + SHOULD be followed for the attribute name. + +## Recommendations for OpenTelemetry Authors + +- All names that are part of OpenTelemetry semantic conventions SHOULD be part + of a namespace. + +- When coming up with a new semantic convention make sure to check existing + namespaces for + [Resources](../resource/semantic_conventions/README.md), + [Spans](../trace/semantic_conventions/README.md), + and + [Metrics](../metrics/semantic_conventions/README.md) + to see if the new name 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 exist for four areas: for Resource, Span and Log + attribute names as well as Metric label keys. In addition, for spans we have + two more areas: Event and Link attribute names. Identical namespaces or names + in all these areas MUST have identical meanings. For example the `http.method` + span attribute name denotes exactly the same concept as the `http.method` + metric label, has the same data type and the same set of possible values (in + both cases it records the value of the HTTP protocol's request method as a + string). + +- Semantic conventions MUST limit 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). It is recommended to further limit 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 or a label +first consult existing semantic conventions for +[Resources](../resource/semantic_conventions/README.md), +[Spans](../trace/semantic_conventions/README.md), +and +[Metrics](../metrics/semantic_conventions/README.md). +If an appropriate name does not exists you will need to come up with a new name. +To do that consider a few options: + +- The name is specific to your company and may be possibly used outside the + company as well. To avoid clashes with names introduced by other companies (in + a distributed system that uses applications from multiple vendors) it is + recommended to prefix the new name by your company's reverse domain name, e.g. + `com.acme.shopname`. + +- The name 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 or label key 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. + +- The name may be generally applicable to applications in the industry. In that + case consider submitting a proposal to this specification to add a new name to + the semantic conventions, and if necessary also to add a new namespace. + +It is recommended to limit 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). diff --git a/specification/common/common.md b/specification/common/common.md index f1526b9518..51ce946c48 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -1,15 +1,13 @@ # Common specification concepts +**Status**: [Feature-freeze](../document-status.md). +
Table of Contents - [Attributes](#attributes) - - [Attribute and Label Naming](#attribute-and-label-naming) - - [Name Pluralization Guidelines](#name-pluralization-guidelines) - - [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) - - [Recommendations for Application Developers](#recommendations-for-application-developers)
@@ -42,122 +40,4 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). -## Attribute and Label Naming - -_This section applies to Resource, Span and Log attribute names (also known as -the "attribute keys") and to keys of Metric labels. For brevity within this -section when we use the term "name" without an adjective it is implied to mean -"attribute name or metric label key"._ - -Every name MUST be a valid Unicode sequence. - -_Note: we merely require that the names are represented as Unicode sequences. -This specification does not define how exactly the Unicode sequences are -encoded. The encoding can vary from one programming language to another and from -one wire format to another. Use the idiomatic way to represent Unicode in the -particular programming language or wire format._ - -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. - Note: the fact that an entity is located within another entity is typically - not a sufficient reason for forming nested namespaces. The purpose of a - namespace is to avoid name clashes, not to indicate entity hierarchies. This - purpose should primarily drive the decision about forming nested namespaces. - -- 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. - -- 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 names: every existing - name prohibits existence of an equally named namespace in the future, and vice - versa: any existing namespace prohibits existence of an equally named - attribute or label key in the future. - -### Name Pluralization guidelines - -- When an attribute represents a single entity, the attribute name SHOULD be singular. - Examples: `host.name`, `db.user`, `container.id`. - -- When attribute can represent multiple entities, the attribute name SHOULD be pluralized - and the value type SHOULD be an array. E.g. `process.command_args` might include multiple - values: the executable name and command arguments. - -- When an attribute represents a measurement, - [Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization) - SHOULD be followed for the attribute name. - -### Recommendations for OpenTelemetry Authors - -- All names that are part of OpenTelemetry semantic conventions SHOULD be part - of a namespace. - -- When coming up with a new semantic convention make sure to check existing - namespaces for - [Resources](../resource/semantic_conventions/README.md), - [Spans](../trace/semantic_conventions/README.md), - and - [Metrics](../metrics/semantic_conventions/README.md) - to see if the new name 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 exist for four areas: for Resource, Span and Log - attribute names as well as Metric label keys. In addition, for spans we have - two more areas: Event and Link attribute names. Identical namespaces or names - in all these areas MUST have identical meanings. For example the `http.method` - span attribute name denotes exactly the same concept as the `http.method` - metric label, has the same data type and the same set of possible values (in - both cases it records the value of the HTTP protocol's request method as a - string). - -- Semantic conventions MUST limit 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). It is recommended to further limit 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 or a label -first consult existing semantic conventions for -[Resources](../resource/semantic_conventions/README.md), -[Spans](../trace/semantic_conventions/README.md), -and -[Metrics](../metrics/semantic_conventions/README.md). -If an appropriate name does not exists you will need to come up with a new name. -To do that consider a few options: - -- The name is specific to your company and may be possibly used outside the - company as well. To avoid clashes with names introduced by other companies (in - a distributed system that uses applications from multiple vendors) it is - recommended to prefix the new name by your company's reverse domain name, e.g. - `com.acme.shopname`. - -- The name 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 or label key 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. - -- The name may be generally applicable to applications in the industry. In that - case consider submitting a proposal to this specification to add a new name to - the semantic conventions, and if necessary also to add a new namespace. - -It is recommended to limit 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). +See [Attribute and Label Naming](attribute-and-label-naming.md) for naming guidelines. From f3aaff67a7c6b4d4d0edf8c476d536f5e20bb2c2 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Thu, 4 Feb 2021 06:06:46 -0800 Subject: [PATCH 15/56] Add lifecycle statuses to all documents (#1385) --- specification/common/attribute-and-label-naming.md | 2 ++ specification/common/common.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/common/attribute-and-label-naming.md b/specification/common/attribute-and-label-naming.md index d84eab4c62..0a9e3356e8 100644 --- a/specification/common/attribute-and-label-naming.md +++ b/specification/common/attribute-and-label-naming.md @@ -1,5 +1,7 @@ # Attribute and Label Naming +**Status**: [Experimental](../document-status.md) +
Table of Contents diff --git a/specification/common/common.md b/specification/common/common.md index 51ce946c48..203a25b912 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -1,6 +1,6 @@ # Common specification concepts -**Status**: [Feature-freeze](../document-status.md). +**Status**: [Stable, Feature-freeze](../document-status.md)
From 8d474bfb544a28a5c0c16dba2e42462de255cd69 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Wed, 28 Apr 2021 10:38:46 -0400 Subject: [PATCH 16/56] Clarify usage of "otel." attribute namespace (#1640) I noticed developers adding their own attributes to this namespace without going through the specification. We need to regulate this namespace through the specification, just like we do it for other semantic conventions. --- specification/common/attribute-and-label-naming.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/specification/common/attribute-and-label-naming.md b/specification/common/attribute-and-label-naming.md index 0a9e3356e8..6ebe80ed2f 100644 --- a/specification/common/attribute-and-label-naming.md +++ b/specification/common/attribute-and-label-naming.md @@ -130,3 +130,17 @@ It is recommended to limit 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). + +## otel.* Namespace + +Attribute and label names that start with `otel.` are reserved to be defined by +OpenTelemetry specification. These are typically used to express OpenTelemetry +concepts in formats that don't have a corresponding concept. + +For example, the `otel.library.name` attribute is used to record the +instrumentation library name, which is an OpenTelemetry concept that is natively +represented in OTLP, but does not have an equivalent in other telemetry formats +and protocols. + +Any additions to the `otel.*` namespace MUST be approved as part of +OpenTelemetry specification. From c74933e8556a3128db67d5746ca52186cea910a8 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Thu, 1 Jul 2021 00:11:54 +0200 Subject: [PATCH 17/56] Rename Metrics labels to attributes (#1775) --- ...nd-label-naming.md => attribute-naming.md} | 36 +++++++++---------- specification/common/common.md | 2 +- 2 files changed, 18 insertions(+), 20 deletions(-) rename specification/common/{attribute-and-label-naming.md => attribute-naming.md} (84%) diff --git a/specification/common/attribute-and-label-naming.md b/specification/common/attribute-naming.md similarity index 84% rename from specification/common/attribute-and-label-naming.md rename to specification/common/attribute-naming.md index 6ebe80ed2f..6599f6b239 100644 --- a/specification/common/attribute-and-label-naming.md +++ b/specification/common/attribute-naming.md @@ -1,4 +1,4 @@ -# Attribute and Label Naming +# Attribute Naming **Status**: [Experimental](../document-status.md) @@ -13,10 +13,9 @@ Table of Contents
-_This section applies to Resource, Span and Log attribute names (also known as -the "attribute keys") and to keys of Metric labels. For brevity within this -section when we use the term "name" without an adjective it is implied to mean -"attribute name or metric label key"._ +_This section applies to Resource, Span, Log, and Metric attribute names (also +known as the "attribute keys"). For brevity within this section when we use the +term "name" without an adjective it is implied to mean "attribute name"._ Every name MUST be a valid Unicode sequence. @@ -50,8 +49,8 @@ Names SHOULD follow these rules: namespace. Because of this rule be careful when choosing names: every existing name prohibits existence of an equally named namespace in the future, and vice versa: any existing namespace prohibits existence of an equally named - attribute or label key in the future. - + attribute key in the future. + ## Name Pluralization guidelines - When an attribute represents a single entity, the attribute name SHOULD be singular. @@ -81,14 +80,13 @@ 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 exist for four areas: for Resource, Span and Log - attribute names as well as Metric label keys. In addition, for spans we have - two more areas: Event and Link attribute names. Identical namespaces or names - in all these areas MUST have identical meanings. For example the `http.method` - span attribute name denotes exactly the same concept as the `http.method` - metric label, has the same data type and the same set of possible values (in - both cases it records the value of the HTTP protocol's request method as a - string). +- Semantic conventions exist for four areas: for Resource, Span, Log, and Metric + attribute names. In addition, for spans we have two more areas: Event and Link + attribute names. Identical namespaces or names in all these areas MUST have + identical meanings. For example the `http.method` span attribute name denotes + exactly the same concept as the `http.method` metric attribute, has the same + data type and the same set of possible values (in both cases it records the + value of the HTTP protocol's request method as a string). - Semantic conventions MUST limit names to printable Basic Latin characters (more precisely to @@ -99,8 +97,8 @@ Names SHOULD follow these rules: ## Recommendations for Application Developers -As an application developer when you need to record an attribute or a label -first consult existing semantic conventions for +As an application developer when you need to record an attribute first consult +existing semantic conventions for [Resources](../resource/semantic_conventions/README.md), [Spans](../trace/semantic_conventions/README.md), and @@ -117,7 +115,7 @@ To do that consider a few options: - The name 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 or label key by your application name, provided that + 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. @@ -133,7 +131,7 @@ subset of Unicode code points). ## otel.* Namespace -Attribute and label names that start with `otel.` are reserved to be defined by +Attribute names that start with `otel.` are reserved to be defined by OpenTelemetry specification. These are typically used to express OpenTelemetry concepts in formats that don't have a corresponding concept. diff --git a/specification/common/common.md b/specification/common/common.md index 203a25b912..1b34c4f9f8 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -40,4 +40,4 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). -See [Attribute and Label Naming](attribute-and-label-naming.md) for naming guidelines. +See [Attribute Naming](attribute-naming.md) for naming guidelines. From 93c832328c2ce8aed3872590629e68147f22b112 Mon Sep 17 00:00:00 2001 From: Jakub Malinowski Date: Wed, 4 Aug 2021 00:26:10 +0200 Subject: [PATCH 18/56] Add an option to limit length of values of attributes and metric values (#1130) --- specification/common/common.md | 51 ++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index 1b34c4f9f8..6cb26c12f9 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -8,6 +8,8 @@ Table of Contents - [Attributes](#attributes) + - [Attribute Limits](#attribute-limits) + - [Exempt Entities](#exempt-entities)
@@ -41,3 +43,52 @@ both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). See [Attribute Naming](attribute-naming.md) for naming guidelines. + +### Attribute Limits + +Execution of erroneous code can result in unintended attributes. If there are no +limits placed on attributes, they can quickly exhaust available memory, resulting +in crashes that are difficult to recover from safely. + +By default an SDK SHOULD apply truncation as per the list of +[configurable parameters](#attribute-limits-configuration) below. + +If an SDK provides a way to: + +- set an attribute value length limit such that for each + attribute value: + - if it is a string, if it exceeds that limit (counting any character in it as + 1), SDKs MUST truncate that value, so that its length is at most equal + to the limit, + - if it is an array of strings, then apply the above rule to each of the + values separately, + - otherwise a value MUST NOT be truncated; +- set a limit of unique attribute keys such that: + - for each unique attributes key, addition of which would result in exceeding + the limit, SDK MUST discard that key/value pair. + +There MAY be a log emitted to indicate to the user that an attribute was +truncated or discarded. To prevent excessive logging, the log MUST NOT be +emitted more than once per record on which an attribute is set. + +If the SDK implements the limits above, it MUST provide a way to change these +limits programmatically. Names of the configuration options SHOULD be the same as +in the list below. + +An SDK MAY implement model-specific limits, for example +`SpanAttributeCountLimit`. If both a general and a model-specific limit are +implemented, then the SDK MUST first attempt to use the model-specific limit, if +it isn't set and doesn't have a default, then the SDK MUST attempt to use the +general limit. + + +**Configurable parameters:** + +* `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record; +* `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length; + +#### Exempt Entities + +Attributes, which belong to Metrics, are exempt from the limits described above +at this time, as discussed in +[Metrics Attribute Limits](../metrics/sdk.md#attribute-limits). From 7ff2672959df485dd4fb9ad80d623fcd8e36c348 Mon Sep 17 00:00:00 2001 From: Owais Lone Date: Tue, 14 Sep 2021 16:40:45 +0530 Subject: [PATCH 19/56] Prefer global limit over model-specific default (#1893) --- specification/common/common.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 6cb26c12f9..c3f434aa89 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -78,8 +78,9 @@ in the list below. An SDK MAY implement model-specific limits, for example `SpanAttributeCountLimit`. If both a general and a model-specific limit are implemented, then the SDK MUST first attempt to use the model-specific limit, if -it isn't set and doesn't have a default, then the SDK MUST attempt to use the -general limit. +it isn't set, then the SDK MUST attempt to use the general limit. If neither are +defined, then the SDK MUST try to use the model-specific limit default value, +followed by the global limit default value. **Configurable parameters:** From 64387bc16e93768879c63af6f45bbd7e189e39b8 Mon Sep 17 00:00:00 2001 From: Owais Lone Date: Thu, 23 Sep 2021 05:19:00 +0530 Subject: [PATCH 20/56] Exempt resources from attribute limits (#1892) Resources are not susceptible to scenarios where excessive attributes can be recorded unlike Spans. Resources are also immutable and it can be hard for some SDKs to apply the limits at source at the time the attributes are added to a resource. Furthermore, limits and Resources both are generally defined and passed on to a TracerProvider which forces a TracerProvider to either mutate the resource or generate a new one with duplicate attributes in order to apply the limits to it. Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> --- specification/common/common.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index c3f434aa89..b0779ad652 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -90,6 +90,14 @@ followed by the global limit default value. #### Exempt Entities +Resource attributes SHOULD be exempt from the limits described above as resources +are not susceptible to the scenarios (auto-instrumentation) that result in +excessive attributes count or size. Resources are also sent only once per batch +instead of per span so it is relatively cheaper to have more/larger attributes +on them. Resources are also immutable by design and they are generally passed +down to TracerProvider along with limits. This makes it awkward to implement +attribute limits for Resources. + Attributes, which belong to Metrics, are exempt from the limits described above at this time, as discussed in [Metrics Attribute Limits](../metrics/sdk.md#attribute-limits). From a66bd4dc17d982350942f1a700609cb455e87db7 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Tue, 16 Nov 2021 10:05:01 -0500 Subject: [PATCH 21/56] Provide a normative definition of Attribute (singular) rather than Attributes (plural) (#2123) * Provide a normative definition of Attribute (singular) - Providing a normative definition of **attribute** (singular) - Other copyedits /cc @austinlparker @tedsuo * Move anchor to make markdown checker happy --- 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 b0779ad652..19d3d87eb7 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -7,21 +7,23 @@ Table of Contents -- [Attributes](#attributes) +- [Attribute](#attribute) - [Attribute Limits](#attribute-limits) - [Exempt Entities](#exempt-entities) -## Attributes +## Attribute -Attributes are a list of zero or more key-value pairs. An `Attribute` MUST have the following properties: + -- The attribute key, which MUST be a non-`null` and non-empty string. -- The attribute value, which is either: +An `Attribute` is a key-value pair, which MUST have the following properties: + +- The attribute key MUST be a non-`null` and non-empty string. +- The attribute value is either: - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer. - An array of primitive type values. The array MUST be homogeneous, - i.e. it MUST NOT contain values of different types. For protocols that do + i.e., it MUST NOT contain values of different types. For protocols that do not natively support array values such values SHOULD be represented as JSON strings. Attribute values expressing a numerical value of zero, an empty string, or an @@ -64,7 +66,7 @@ If an SDK provides a way to: values separately, - otherwise a value MUST NOT be truncated; - set a limit of unique attribute keys such that: - - for each unique attributes key, addition of which would result in exceeding + - for each unique attribute key, addition of which would result in exceeding the limit, SDK MUST discard that key/value pair. There MAY be a log emitted to indicate to the user that an attribute was From 02c9500d75446df5250a92369b393f6ecfef40f4 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 24 Nov 2021 09:57:38 -0500 Subject: [PATCH 22/56] [editorial] Ensure all ToCs are generated using markdown-toc (#2146) --- specification/common/attribute-naming.md | 11 +++++++---- specification/common/common.md | 12 +++++++----- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 6599f6b239..1cf593b9f7 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -3,13 +3,16 @@ **Status**: [Experimental](../document-status.md)
- -Table of Contents - +Table of Contents -- [Name Pluralization Guidelines](#name-pluralization-guidelines) + + +- [Name Pluralization guidelines](#name-pluralization-guidelines) - [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) - [Recommendations for Application Developers](#recommendations-for-application-developers) +- [otel.* Namespace](#otel-namespace) + +
diff --git a/specification/common/common.md b/specification/common/common.md index 19d3d87eb7..3e5f170456 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -3,13 +3,15 @@ **Status**: [Stable, Feature-freeze](../document-status.md)
- -Table of Contents - +Table of Contents + + - [Attribute](#attribute) - - [Attribute Limits](#attribute-limits) - - [Exempt Entities](#exempt-entities) + * [Attribute Limits](#attribute-limits) + + [Exempt Entities](#exempt-entities) + +
From 3321b3e8b816e60a3f2054487277462e67b16b2b Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Mon, 13 Dec 2021 13:04:41 -0500 Subject: [PATCH 23/56] Prohibit usage of retired names in semantic conventions (#2191) * Prohibit usage of retired names in semantic conventions This change adds a prohibition clause that requires that no old metric or attribute name is used for a new attribute. This is important to ensure reversibility of schema transformation (converting from a new version to an old version of schema). Without this restriction the following is possible: Schema version 1. Attribute A exists. Schema version 2. Attribute A is renamed to B. Appropriate schema file is created. Schema version 3. Attribute A is introduced (a completely different new attribute). Now attempting to go from Version 3 to version 1 is impossible since it requires renaming B to A (for the change in version 2), but a different attribute A already exists. * Fix based on comments * Add changelog entry Co-authored-by: Carlos Alberto Cortez --- specification/common/attribute-naming.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 1cf593b9f7..9cd2f187b5 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -8,6 +8,7 @@ - [Name Pluralization guidelines](#name-pluralization-guidelines) +- [Name Reuse Prohibition](#name-reuse-prohibition) - [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) - [Recommendations for Application Developers](#recommendations-for-application-developers) - [otel.* Namespace](#otel-namespace) @@ -67,6 +68,15 @@ Names SHOULD follow these rules: [Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization) SHOULD be followed for the attribute name. +## Name Reuse Prohibition + +A new attribute MUST NOT be added with the same name as an attribute that +existed in the past but was renamed (with a corresponding schema file). + +When introducing a new attribute name check all existing schema files to make +sure the name does not appear as a key of any "rename_attributes" section (keys +denote old attribute names in rename operations). + ## Recommendations for OpenTelemetry Authors - All names that are part of OpenTelemetry semantic conventions SHOULD be part From aeab66376aa5caa809d3282c8cb235f2176e6f61 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Wed, 26 Jan 2022 16:47:43 -0500 Subject: [PATCH 24/56] Clarify that attribute keys are unique in collections (#2248) Attributes keys must be unique. The key/value pair collections in the specification was always intended to model a map. There was a recent confusion about this. This change clarifies the spec. Resolves https://github.com/open-telemetry/opentelemetry-specification/issues/2245 --- specification/common/common.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/specification/common/common.md b/specification/common/common.md index 3e5f170456..f098255a22 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -10,6 +10,7 @@ - [Attribute](#attribute) * [Attribute Limits](#attribute-limits) + [Exempt Entities](#exempt-entities) +- [Attribute Collections](#attribute-collections) @@ -105,3 +106,35 @@ attribute limits for Resources. Attributes, which belong to Metrics, are exempt from the limits described above at this time, as discussed in [Metrics Attribute Limits](../metrics/sdk.md#attribute-limits). + +## Attribute Collections + +[Resources](../resource/sdk.md), Metrics +[data points](../metrics/datamodel.md#metric-points), +[Spans](../trace/api.md#set-attributes), Span +[Events](../trace/api.md#add-events), Span +[Links](../trace/api.md#specifying-links) and +[Log Records](../logs/data-model.md) may contain a collection of attributes. The +keys in each such collection are unique, i.e. there MUST NOT exist more than one +key-value pair with the same key. The enforcement of uniqueness may be performed +in a variety of ways as it best fits the limitations of the particular +implementation. + +Normally for the telemetry generated using OpenTelemetry SDKs the attribute +key-value pairs are set via an API that either accepts a single key-value pair +or a collection of key-value pairs. Setting an attribute with the same key as an +existing attribute SHOULD overwrite the existing attribute's value. See for +example Span's [SetAttribute](../trace/api.md#set-attributes) API. + +A typical implementation of [SetAttribute](../trace/api.md#set-attributes) API +will enforce the uniqueness by overwriting any existing attribute values pending +to be exported, so that when the Span is eventually exported the exporters see +only unique attributes. The OTLP format in particular requires that exported +Resources, Spans, Metric data points and Log Records contain only unique +attributes. + +Some other implementations may use a streaming approach where every +[SetAttribute](../trace/api.md#set-attributes) API call immediately results in +that individual attribute value being exported using a streaming wire protocol. +In such cases the enforcement of uniqueness will likely be the responsibility of +the recipient of this data. From 96108c0700a4e46920ddd8caa7201dca0f33a69c Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Tue, 15 Feb 2022 11:34:11 -0500 Subject: [PATCH 25/56] Clarify that Trace/Meter are associated with Instrumentation Scope (#2276) * Clarify that Trace/Meter are associated with Instrumentation Scope This is a slightly different take on https://github.com/open-telemetry/opentelemetry-specification/issues/2203 Instead of renaming instrumentation library to instrumentation scope everywhere this PR suggests targetted editing of wording of the Trace/Meter obtaining API to allow not just instrumentation library but other instrumentation scopes to be used as a parameter. This change does not force renaming of API parameters and is not a breaking change. We consider it a clarification of usage to match the intent that we had for the "name" field. If this PR is accepted there will be a follow up PR that will suggest to rename InstrumentationLibrary* messages in OTLP proto to InstrumentationScope* message. Such a change will not be a breaking change for the OTLP wire format and is acceptable. If this PR is accepted we will also close https://github.com/open-telemetry/opentelemetry-specification/pull/1236 since it will be no longer necessary. The logger name will be recorded as the instrumentation scope. This clarification will be a follow up PR that clarifies the behavior in https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md --- specification/common/attribute-naming.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 9cd2f187b5..fecbf3b21b 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -148,8 +148,8 @@ Attribute names that start with `otel.` are reserved to be defined by OpenTelemetry specification. These are typically used to express OpenTelemetry concepts in formats that don't have a corresponding concept. -For example, the `otel.library.name` attribute is used to record the -instrumentation library name, which is an OpenTelemetry concept that is natively +For example, the `otel.scope.name` attribute is used to record the +instrumentation scope name, which is an OpenTelemetry concept that is natively represented in OTLP, but does not have an equivalent in other telemetry formats and protocols. From 6ea715593f5c3e526ec2b150835ac5aac9862e02 Mon Sep 17 00:00:00 2001 From: David Ashpole Date: Thu, 3 Mar 2022 00:30:53 -0500 Subject: [PATCH 26/56] Describe how to convert non-string primitives for protocols which only support strings (#2343) * Describe how to handle converting non-string primitives for protocols that only support strings * update wording to make clear that only non-string values are converted to strings * unify language * Update specification/common/common.md Co-authored-by: Joshua MacDonald Co-authored-by: Joshua MacDonald Co-authored-by: Bogdan Drutu --- specification/common/common.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index f098255a22..80a13012f4 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -26,8 +26,9 @@ An `Attribute` is a key-value pair, which MUST have the following properties: - The attribute value is either: - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer. - An array of primitive type values. The array MUST be homogeneous, - i.e., it MUST NOT contain values of different types. For protocols that do - not natively support array values such values SHOULD be represented as JSON strings. + i.e., it MUST NOT contain values of different types. + +For protocols that do not natively support non-string values, non-string values SHOULD be represented as JSON-encoded strings. For example, the expression `int64(100)` will be encoded as `100`, `float64(1.5)` will be encoded as `1.5`, and an empty array of any type will be encoded as `[]`. Attribute values expressing a numerical value of zero, an empty string, or an empty array are considered meaningful and MUST be stored and passed on to From d7400c86534bf25cb88c3ad2736cfa431fbea6fe Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 21 Mar 2022 23:05:45 -0700 Subject: [PATCH 27/56] Fix links (#2426) --- specification/common/common.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/common/common.md b/specification/common/common.md index 80a13012f4..774c236130 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -9,6 +9,7 @@ - [Attribute](#attribute) * [Attribute Limits](#attribute-limits) + + [Configurable Parameters](#configurable-parameters) + [Exempt Entities](#exempt-entities) - [Attribute Collections](#attribute-collections) @@ -57,7 +58,7 @@ limits placed on attributes, they can quickly exhaust available memory, resultin in crashes that are difficult to recover from safely. By default an SDK SHOULD apply truncation as per the list of -[configurable parameters](#attribute-limits-configuration) below. +[configurable parameters](#configurable-parameters) below. If an SDK provides a way to: @@ -88,8 +89,7 @@ it isn't set, then the SDK MUST attempt to use the general limit. If neither are defined, then the SDK MUST try to use the model-specific limit default value, followed by the global limit default value. - -**Configurable parameters:** +#### Configurable Parameters * `AttributeCountLimit` (Default=128) - Maximum allowed attribute count per record; * `AttributeValueLengthLimit` (Default=Infinity) - Maximum allowed attribute value length; From 91bf1f1201718c5c7c42ee4141138fec561e9ce6 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Tue, 22 Mar 2022 08:59:37 -0400 Subject: [PATCH 28/56] Implement OTEP 0178: Mapping external data to AnyValue (#2385) OTEP 0178 [0] proposed this mapping. This PR merges the proposal into specification. The content of this PR is mostly copy/paste of the text of the OTEP minus the irrelevant sections such as "Alternates", etc. 0 - https://github.com/open-telemetry/oteps/blob/main/text/0178-mapping-to-otlp-anyvalue.md --- .../common/attribute-type-mapping.md | 255 ++++++++++++++++++ specification/common/common.md | 3 + 2 files changed, 258 insertions(+) create mode 100644 specification/common/attribute-type-mapping.md diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md new file mode 100644 index 0000000000..46a25c1504 --- /dev/null +++ b/specification/common/attribute-type-mapping.md @@ -0,0 +1,255 @@ +# Mapping Arbitrary Data to OTLP AnyValue + +**Status**: [Experimental](../document-status.md) + +
+Table of Contents + + + +- [Converting to AnyValue](#converting-to-anyvalue) + * [Primitive Values](#primitive-values) + + [Integer Values](#integer-values) + + [Enumerations](#enumerations) + + [Floating Point Values](#floating-point-values) + + [String Values](#string-values) + + [Byte Sequences](#byte-sequences) + * [Composite Values](#composite-values) + + [Array Values](#array-values) + + [Associative Arrays With Unique Keys](#associative-arrays-with-unique-keys) + + [Associative Arrays With Non-Unique Keys](#associative-arrays-with-non-unique-keys) + + [Sets](#sets) + * [Other Values](#other-values) + * [Empty Values](#empty-values) + + + +
+ +This document defines how to map (convert) arbitrary data (e.g. in-memory +objects) to OTLP's [AnyValue](https://github.com/open-telemetry/opentelemetry-proto/blob/cc4ed55c082cb75e084d40b4ddf3805eda099f97/opentelemetry/proto/common/v1/common.proto#L27). + +The mapping is needed when OpenTelemetry needs to convert a value produced outside +OpenTelemetry into a value that can be exported using an OTLP exporter, or otherwise be +converted to be used inside OpenTelemetry boundaries. Example use cases are the following: + +- In [Logging Library SDK](../logs/logging-library-sdk.md)s, to convert values received + from logging libraries into OpenTelemetry representation. +- In the Collector, to convert values received from various data sources into + [pdata](https://github.com/open-telemetry/opentelemetry-collector/blob/4998703dadd19fa91a88eabf7ccc68d728bee3fd/model/pdata/common.go#L84) + internal representation. + +## Converting to AnyValue + +[AnyValue](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L27) +is capable of representing primitive and structured data of certain types. + +Implementations that have source data in any form, such as in-memory objects +or data coming from other formats that needs to be converted to AnyValue SHOULD +follow the rules described below. + +### Primitive Values + +#### Integer Values + +Integer values which are within the range of 64 bit signed numbers +[-2^63..2^63-1] SHOULD be converted to AnyValue's +[int_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L33) +field. + +Integer values which are outside the range of 64 bit signed numbers SHOULD be +converted to AnyValue's +[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) +field using decimal representation. + +#### Enumerations + +Values, which belong to a limited enumerated set (e.g. a Java +[enum](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html)), SHOULD be +converted to AnyValue's +[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) +field with the value of the string set to the symbolic name of the enumeration. + +If it is not possible to obtain the symbolic name of the enumeration, the +implementation SHOULD map enumeration values to AnyValue's +[int_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L33) +field set to the enum's ordinal value, when such an ordinal number is naturally +obtainable. + +If it is also not possible to obtain the ordinal value, the enumeration SHOULD be +converted to AnyValue's +[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) +field in any manner that the implementation deems reasonable. + +#### Floating Point Values + +Floating point values which are within the range and precision of IEEE 754 +64-bit floating point numbers (including IEEE 32-bit floating point values) +SHOULD be converted to AnyValue's +[double_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L34) +field. + +Floating point values which are outside the range or precision of IEEE 754 +64-bit floating point numbers (e.g. IEEE 128-bit floating bit values) SHOULD be +converted to AnyValue's +[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) +field using decimal floating point representation. + +#### String Values + +String values which are valid UTF-8 sequences SHOULD be converted to +AnyValue's +[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) +field. + +String values which are not valid Unicode sequences SHOULD be converted to +AnyValue's +[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) +with the bytes representing the string in the original order and format of the +source string. + +#### Byte Sequences + +Byte sequences (e.g. Go's `[]byte` slice or raw byte content of a file) SHOULD +be converted to AnyValue's +[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) +field. + +### Composite Values + +#### Array Values + +Values that represent ordered sequences of other values (such as +[arrays](https://docs.oracle.com/javase/specs/jls/se7/html/jls-10.html), +[vectors](https://en.cppreference.com/w/cpp/container/vector), ordered +[lists](https://docs.python.org/3/tutorial/datastructures.html#more-on-lists), +[slices](https://golang.org/ref/spec#Slice_types)) SHOULD be converted to +AnyValue's +[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) +field. String values and byte sequences are an exception from this rule (see +above). + +The rules described in this document should be applied recursively to each element +of the array. + +#### Associative Arrays With Unique Keys + +Values that represent associative arrays with unique keys (also often known +as maps, dictionaries or key-value stores) SHOULD be converted to AnyValue's +[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) +field. + +If the keys of the source array are not strings, they MUST be converted to +strings by any means available, often via a toString() or stringify functions +available in programming languages. The conversion function MUST be chosen in a +way that ensures that the resulting string keys are unique in the target array. + +The value part of each element of the source array SHOULD be converted to +AnyValue recursively. + +For example a JSON object `{"a": 123, "b": "def"}` SHOULD be converted to + +``` +AnyValue{ + kvlist_value:KeyValueList{ + values:[ + KeyValue{key:"a",value:AnyValue{int_value:123}}, + KeyValue{key:"b",value:AnyValue{string_value:"def"}}, + ] + } +} +``` + +The rules described in this document should be applied recursively to each value +of the associative array. + +#### Associative Arrays With Non-Unique Keys + +Values that represent an associative arrays with non-unique keys where multiple values may be associated with the same key (also sometimes known +as multimaps, multidicts) SHOULD be converted to AnyValue's +[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) +field. + +The resulting +[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) +field MUST list each key only once and the value of each element of +[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) +field MUST be an array represented using AnyValue's +[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) +field, each element of the +[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) +representing one value of source array associated with the given key. + +For example an associative array shown in the following table: + +|Key|Value| +|---|---| +|"abc"|123| +|"def"|"foo"| +|"def"|"bar"| + +SHOULD be converted to: + +``` +AnyValue{ + kvlist_value:KeyValueList{ + values:[ + KeyValue{ + key:"abc", + value:AnyValue{array_value:ArrayValue{values[ + AnyValue{int_value:123} + ]}} + }, + KeyValue{ + key:"def", + value:AnyValue{array_value:ArrayValue{values[ + AnyValue{string_value:"foo"}, + AnyValue{string_value:"bar"} + ]}} + }, + ] + } +} +``` + +The rules described in this document should be applied recursively to each value +of the associative array. + +#### Sets + +Unordered collections of unique values (such as +[Java Sets](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Set.html), +[C++ sets](https://en.cppreference.com/w/cpp/container/set), +[Python Sets](https://docs.python.org/3/tutorial/datastructures.html#sets)) SHOULD be +converted to AnyValue's +[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) +field, where each element of the set becomes an element of the array. + +The rules described in this document should be applied recursively to each value +of the set. + +### Other Values + +Any other values not listed above SHOULD be converted to AnyValue's +[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) +field if the source data can be serialized to a string (can be stringified) +using toString() or stringify functions available in programming languages. + +If the source data cannot be serialized to a string then the value SHOULD be +converted AnyValue's +[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) +field by serializing it into a byte sequence by any means available. + +If the source data cannot be serialized neither to a string nor to a byte +sequence then it SHOULD by converted to an empty AnyValue. + +### Empty Values + +If the source data has no type associated with it and is empty, null, nil or +otherwise indicates absence of data it SHOULD be converted to an +[empty](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L29) +AnyValue, where all the fields are unset. + +Empty values which has a type associated with them (e.g. empty associative +array) SHOULD be converted using the corresponding rules defined for the types +above. diff --git a/specification/common/common.md b/specification/common/common.md index 774c236130..6c3e80a527 100644 --- a/specification/common/common.md +++ b/specification/common/common.md @@ -51,6 +51,9 @@ both containing an array of strings to represent a mapping See [Attribute Naming](attribute-naming.md) for naming guidelines. +See [this document](attribute-type-mapping.md) to find out how to map values obtained +outside OpenTelemetry into OpenTelemetry attribute values. + ### Attribute Limits Execution of erroneous code can result in unintended attributes. If there are no From a2feb348f55b0c81c4e244dcb53f12120cda0c48 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 8 Apr 2022 13:07:21 -0400 Subject: [PATCH 29/56] [editorial] Ensure common section has a README (#2479) --- specification/common/{common.md => README.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename specification/common/{common.md => README.md} (100%) diff --git a/specification/common/common.md b/specification/common/README.md similarity index 100% rename from specification/common/common.md rename to specification/common/README.md From 5bcfad43863425abb861c39a58b474c42fbba68e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 16 May 2022 10:16:33 -0700 Subject: [PATCH 30/56] Define attribute requirement levels (#2522) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * nits * review comments * No exceptions for Required attributes, clarifications on performance * Conditional clarifications * nits * Conditional -> required conditionally and minor fixes * Align requirement levels with RFC levels better * Clarify Note on required attributes * Update specification/common/attribute-requirement-level.md Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> * Clarify Note on required attributes * Remove performance from conditionally required attributes * Clarify Conditionally Required case when condition is false * Apply suggestions from code review Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Christian Neumüller * headings for levels and moving things around * nits: formatting Co-authored-by: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Co-authored-by: Christian Neumüller Co-authored-by: Reiley Yang --- specification/common/README.md | 2 + .../common/attribute-requirement-level.md | 69 +++++++++++++++++++ 2 files changed, 71 insertions(+) create mode 100644 specification/common/attribute-requirement-level.md diff --git a/specification/common/README.md b/specification/common/README.md index 6c3e80a527..18d46fe00c 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -51,6 +51,8 @@ both containing an array of strings to represent a mapping See [Attribute Naming](attribute-naming.md) for naming guidelines. +See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines. + See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md new file mode 100644 index 0000000000..5a7d6e323d --- /dev/null +++ b/specification/common/attribute-requirement-level.md @@ -0,0 +1,69 @@ +# Attribute Requirement Levels for Semantic Conventions + +**Status**: [Experimental](../document-status.md) + +
+Table of Contents + + + +- [Required](#required) +- [Conditionally Required](#conditionally-required) +- [Recommended](#recommended) +- [Optional](#optional) +- [Performance suggestions](#performance-suggestions) + + + +
+ +_This section applies to Log, Metric, Resource, and Span, and describes requirement levels for attributes defined in semantic conventions._ + +The following attribute requirement levels are specified: + +- [Required](#required) +- [Conditionally Required](#conditionally-required) +- [Recommended](#recommended) +- [Optional](#optional) + +The requirement level for attribute is defined by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When defining requirement levels, semantic conventions MUST take into account signal-specific requirements. + +For example, Metric attributes that may have high cardinality can only be defined with `Optional` level. + +Semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. + +For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `net.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it. + +## Required + +All instrumentations MUST populate the attribute. Semantic convention defining a Required attribute expects that an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, can ensure cardinality, security, and other requirements specific to signal defined by the convention. `http.method` is an example of a Required attribute. + +_Note: Consumers of telemetry can detect if telemetry item follows a specific semantic convention by checking the presence of a `Required` attribute defined by such convention. For example, the presence of `db.system` attribute on a span can be used as an indication that the span follows database semantics._ + +## Conditionally Required + +All instrumentations MUST add the attribute when given condition is satisfied. Semantic convention of a `Conditionally Required` level of an attribute MUST clarify the condition under which the attribute is expected to be populated. + +`http.route` is an example of a conditionally required attribute to be populated when instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute. + +When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Optional` requirement level on the attribute. + +For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.peer.ip` is available, instrumentation can do a DNS lookup, cache and populate `net.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. + +## Recommended + +Instrumentations SHOULD add the attribute by default if it's readily available and can be [efficiently populated](#performance-suggestions). Instrumentations MAY offer a configuration option to disable Recommended attributes. + +Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD use the `Optional` requirement level on them if the attributes are logically applicable. + +## Optional + +Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Optional` attributes. + +## Performance suggestions + +Here are several examples of expensive operations to be avoided by default: + +- DNS lookup to populate `net.peer.name` if only IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. +- forcing `http.route` calculation before HTTP framework calculates it +- reading response stream to find `http.response_content_length` when `Content-Length` header is not available From 1174ab5da2e48d38218fb33326384f3b0ea34adb Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 20 May 2022 02:12:03 -0400 Subject: [PATCH 31/56] [editorial] Add missing READMEs to section (#2559) --- specification/common/README.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/common/README.md b/specification/common/README.md index 18d46fe00c..3d1379fde4 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -1,3 +1,6 @@ + # Common specification concepts **Status**: [Stable, Feature-freeze](../document-status.md) From 5902a67bd1b2a32e379556ce396ccb5998bf44d8 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Thu, 2 Jun 2022 03:25:38 -0400 Subject: [PATCH 32/56] Move non-otlp.md to common directory (#2587) --- specification/common/mapping-to-non-otlp.md | 76 +++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 specification/common/mapping-to-non-otlp.md diff --git a/specification/common/mapping-to-non-otlp.md b/specification/common/mapping-to-non-otlp.md new file mode 100644 index 0000000000..cb80f685ca --- /dev/null +++ b/specification/common/mapping-to-non-otlp.md @@ -0,0 +1,76 @@ +# OpenTelemetry Transformation to non-OTLP Formats + +**Status**: [Stable](../document-status.md) + +All OpenTelemetry concepts and data recorded using OpenTelemetry API can be +directly and precisely represented using corresponding messages and fields of +OTLP format. However, for other formats this is not always the case. Sometimes a +format will not have a native way to represent a particular OpenTelemetry +concept or a field of a concept. + +This document defines the transformation between OpenTelemetry and formats other +than OTLP, for OpenTelemetry fields and concepts that have no direct semantic +equivalent in those other formats. + +Note: when a format has a direct semantic equivalent for a particular field or +concept then the recommendation in this document MUST be ignored. + +See also additional specific transformation rules for +[Jaeger](../trace/sdk_exporters/jaeger.md) and [Zipkin](../trace/sdk_exporters/zipkin.md). +The specific rules for Jaeger and Zipkin take precedence over the generic rules defined +in this document. + +## Mappings + +### InstrumentationScope + +OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value +pairs associated with the Span, Metric Data Point or LogRecord using the following mapping: + +| OpenTelemetry InstrumentationScope Field | non-OTLP Key | Notes | +| ------------------- | --- | --- | +| `InstrumentationScope.name`|`otel.scope.name`|since 1.10.0| +| `InstrumentationScope.version`|`otel.scope.version`|since 1.10.0| + +The following deprecated aliases MUST also be reported with exact same values for +backward compatibility reasons: + +| non-OTLP Key | Alias for | Notes | +| --- | --- | --- | +|`otel.library.name`|`otel.scope.name`|deprecated since 1.10.0| +|`otel.library.version`|`otel.scope.version`|deprecated since 1.10.0| + +### Span Status + +Span `Status` MUST be reported as key-value pairs associated with the Span, +unless the `Status` is `UNSET`. In the latter case it MUST NOT be reported. + +The following table defines the OpenTelemetry `Status`'s mapping to Span's +key-value pairs: + +|OpenTelemetry Status Field|non-OTLP Key|non-OTLP Value| +|--|--|--| +|Code | `otel.status_code` | Name of the code, either `OK` or `ERROR`. MUST NOT be set if the code is `UNSET`. | +|Description | `otel.status_description` | Description of the `Status` if it has a value otherwise not set. | + +### Dropped Attributes Count + +OpenTelemetry dropped attributes count MUST be reported as a key-value +pair associated with the corresponding data entity (e.g. Span, Span Link, Span Event, +Metric data point, LogRecord, etc). The key name MUST be `otel.dropped_attributes_count`. + +This key-value pair should only be recorded when it contains a non-zero value. + +### Dropped Events Count + +OpenTelemetry Span's dropped events count MUST be reported as a key-value pair +associated with the Span. The key name MUST be `otel.dropped_events_count`. + +This key-value pair should only be recorded when it contains a non-zero value. + +### Dropped Links Count + +OpenTelemetry Span's dropped links count MUST be reported as a key-value pair +associated with the Span. The key name MUST be `otel.dropped_links_count`. + +This key-value pair should only be recorded when it contains a non-zero value. From eaa674459d5e749779b6cc59b47acd5055b6e448 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Fri, 10 Jun 2022 22:19:33 -0400 Subject: [PATCH 33/56] Introduce Instrumentation Scope Attributes (#2579) --- specification/common/mapping-to-non-otlp.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/common/mapping-to-non-otlp.md b/specification/common/mapping-to-non-otlp.md index cb80f685ca..656b37fa35 100644 --- a/specification/common/mapping-to-non-otlp.md +++ b/specification/common/mapping-to-non-otlp.md @@ -74,3 +74,9 @@ OpenTelemetry Span's dropped links count MUST be reported as a key-value pair associated with the Span. The key name MUST be `otel.dropped_links_count`. This key-value pair should only be recorded when it contains a non-zero value. + +### Instrumentation Scope Attributes + +Exporters to formats that don't have a concept that is equivalent to the Scope +SHOULD record the attributes at the most suitable place in their corresponding format, +typically at the Span, Metric or LogRecord equivalent. From 22d04d6a7f2d9ad18d30f5348c281698d69b01b1 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Mon, 13 Jun 2022 12:00:00 -0400 Subject: [PATCH 34/56] Use consistent file name for data-model.md (#2586) --- specification/common/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/README.md b/specification/common/README.md index 3d1379fde4..35d6264b2a 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -119,7 +119,7 @@ at this time, as discussed in ## Attribute Collections [Resources](../resource/sdk.md), Metrics -[data points](../metrics/datamodel.md#metric-points), +[data 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#specifying-links) and From 00e08491b8a2a1087f62eab408787a3975393e67 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 8 Jul 2022 03:12:12 -0400 Subject: [PATCH 35/56] [editorial] Add note to Hugo front matter (#2651) --- specification/common/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/README.md b/specification/common/README.md index 35d6264b2a..2b377a731c 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -1,4 +1,4 @@ - # Common specification concepts From e7134eb80ed06d6ac52bd964db3eef92d3cd4a1e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 13 Jul 2022 10:01:44 -0700 Subject: [PATCH 36/56] Define net.sock attributes and clarify logical net.peer|host.name attributes (#2614) --- specification/common/attribute-requirement-level.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 5a7d6e323d..e015ef89eb 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -48,7 +48,7 @@ All instrumentations MUST add the attribute when given condition is satisfied. S When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Optional` requirement level on the attribute. -For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.peer.ip` is available, instrumentation can do a DNS lookup, cache and populate `net.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. +For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available, instrumentation can do a DNS lookup, cache and populate `net.sock.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. ## Recommended From 95338c68640bc1c5ead3f2025e2a811141893ac4 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Tue, 13 Sep 2022 09:45:58 -0500 Subject: [PATCH 37/56] Align log sdk naming with api (#2768) Resolves #2752. This aligns log SDK and API concepts which have diverged after the merged of #2676. This PR brings alignment to the log API and SDK, and in brings the log signal into alignment with tracing and metrics where there is conceptual overlap. There shouldn't be any new concepts introduced here. - Rename `../logs/logging-library-sdk.md` to `../logs/sdk.md` - Remove wording from SDK that implies that an API doesn't exist, like [this](https://github.com/open-telemetry/opentelemetry-specification/blame/main/specification/logs/logging-library-sdk.md#L60-L62). - Move [How to Create Log4j Style Appender](https://github.com/open-telemetry/opentelemetry-specification/blame/main/specification/logs/logging-library-sdk.md#L219) to `api.md` since it describes an API use case. - Move [Implicit / Explicit Context Injection](https://github.com/open-telemetry/opentelemetry-specification/blame/main/specification/logs/logging-library-sdk.md#L270-L288) sections to `api.md` since they describe API level considerations. - Rename Logger [create](https://github.com/open-telemetry/opentelemetry-specification/blame/main/specification/logs/api.md#L133) method to be emit, to align with SDK concept of `LogRecordProcessor#onEmit(..)`. - Rename `LogProcessor`, `LogExporter` to `LogRecordProcessor`, `LogRecordExporter`. - Fill in various SDK level TODOs related to shutdown and flushing. The language from these was taken directly from the metrics / tracing SDK - no new concepts were introduced. --- specification/common/attribute-type-mapping.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md index 46a25c1504..532d6156bc 100644 --- a/specification/common/attribute-type-mapping.md +++ b/specification/common/attribute-type-mapping.md @@ -33,7 +33,7 @@ The mapping is needed when OpenTelemetry needs to convert a value produced outsi OpenTelemetry into a value that can be exported using an OTLP exporter, or otherwise be converted to be used inside OpenTelemetry boundaries. Example use cases are the following: -- In [Logging Library SDK](../logs/logging-library-sdk.md)s, to convert values received +- In the [Logging SDK](../logs/sdk.md)s, to convert values received from logging libraries into OpenTelemetry representation. - In the Collector, to convert values received from various data sources into [pdata](https://github.com/open-telemetry/opentelemetry-collector/blob/4998703dadd19fa91a88eabf7ccc68d728bee3fd/model/pdata/common.go#L84) From a82836ba85f18217951719e05b3d4fb9a0fa7e94 Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 25 Oct 2022 08:46:06 -0700 Subject: [PATCH 38/56] Define semantic conventions yaml for non-otlp conventions (#2850) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Define semantic conventions yaml for non-otlp conventions Signed-off-by: Bogdan Drutu * Update semantic_conventions/trace/exporter/exporter.yaml Co-authored-by: Christian Neumüller * Update semantic_conventions/scope/exporter/exporter.yaml Co-authored-by: Joao Grassi * Rename otel to otel_span Signed-off-by: Bogdan Drutu Signed-off-by: Bogdan Drutu Co-authored-by: Christian Neumüller Co-authored-by: Joao Grassi --- specification/common/mapping-to-non-otlp.md | 37 ++++++++++++++------- 1 file changed, 25 insertions(+), 12 deletions(-) diff --git a/specification/common/mapping-to-non-otlp.md b/specification/common/mapping-to-non-otlp.md index 656b37fa35..a82dac3e63 100644 --- a/specification/common/mapping-to-non-otlp.md +++ b/specification/common/mapping-to-non-otlp.md @@ -27,18 +27,22 @@ in this document. OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value pairs associated with the Span, Metric Data Point or LogRecord using the following mapping: -| OpenTelemetry InstrumentationScope Field | non-OTLP Key | Notes | -| ------------------- | --- | --- | -| `InstrumentationScope.name`|`otel.scope.name`|since 1.10.0| -| `InstrumentationScope.version`|`otel.scope.version`|since 1.10.0| + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | Recommended | +| `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | Recommended | + The following deprecated aliases MUST also be reported with exact same values for backward compatibility reasons: -| non-OTLP Key | Alias for | Notes | -| --- | --- | --- | -|`otel.library.name`|`otel.scope.name`|deprecated since 1.10.0| -|`otel.library.version`|`otel.scope.version`|deprecated since 1.10.0| + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `otel.library.name` | string | Deprecated, use the `otel.scope.name` attribute. | `io.opentelemetry.contrib.mongodb` | Recommended | +| `otel.library.version` | string | Deprecated, use the `otel.scope.version` attribute. | `1.0.0` | Recommended | + ### Span Status @@ -48,10 +52,19 @@ unless the `Status` is `UNSET`. In the latter case it MUST NOT be reported. The following table defines the OpenTelemetry `Status`'s mapping to Span's key-value pairs: -|OpenTelemetry Status Field|non-OTLP Key|non-OTLP Value| -|--|--|--| -|Code | `otel.status_code` | Name of the code, either `OK` or `ERROR`. MUST NOT be set if the code is `UNSET`. | -|Description | `otel.status_description` | Description of the `Status` if it has a value otherwise not set. | + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK` | Recommended | +| `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | Recommended | + +`otel.status_code` MUST be one of the following: + +| Value | Description | +|---|---| +| `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | +| `ERROR` | The operation contains an error. | + ### Dropped Attributes Count From e7e679dbb8feac81822c11b2f13e9e905ee5fb08 Mon Sep 17 00:00:00 2001 From: Alan West <3676547+alanwest@users.noreply.github.com> Date: Thu, 26 Jan 2023 16:22:06 -0800 Subject: [PATCH 39/56] Add log attribute limit configuration (#2861) Fixes #2860 Adds log attribute limit configuration. These new environment variables bring more consistency between spans and logs. --- specification/common/README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/specification/common/README.md b/specification/common/README.md index 2b377a731c..f36cb92b85 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -91,11 +91,11 @@ limits programmatically. Names of the configuration options SHOULD be the same a in the list below. An SDK MAY implement model-specific limits, for example -`SpanAttributeCountLimit`. If both a general and a model-specific limit are -implemented, then the SDK MUST first attempt to use the model-specific limit, if -it isn't set, then the SDK MUST attempt to use the general limit. If neither are -defined, then the SDK MUST try to use the model-specific limit default value, -followed by the global limit default value. +`SpanAttributeCountLimit` or `LogRecordAttributeCountLimit`. If both a general +and a model-specific limit are implemented, then the SDK MUST first attempt to +use the model-specific limit, if it isn't set, then the SDK MUST attempt to use +the general limit. If neither are defined, then the SDK MUST try to use the +model-specific limit default value, followed by the global limit default value. #### Configurable Parameters From cfcd551eb632ed6c20c50a5f8b10cd36a0ed8ad4 Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Thu, 23 Feb 2023 11:38:55 -0500 Subject: [PATCH 40/56] Mark Attribute naming conventions as stable. (#3220) --- specification/common/attribute-naming.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index fecbf3b21b..d761b5f9fd 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -1,6 +1,6 @@ # Attribute Naming -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md)
Table of Contents From 229c66c6852b910d9d5b1fca50eb31c4a1d23ffb Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 1 Mar 2023 15:13:24 -0800 Subject: [PATCH 41/56] Rename Optional attribute requirement level to Opt-In (#3228) --- .../common/attribute-requirement-level.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index e015ef89eb..c030159409 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -10,7 +10,7 @@ - [Required](#required) - [Conditionally Required](#conditionally-required) - [Recommended](#recommended) -- [Optional](#optional) +- [Opt-In](#opt-in) - [Performance suggestions](#performance-suggestions) @@ -24,11 +24,11 @@ The following attribute requirement levels are specified: - [Required](#required) - [Conditionally Required](#conditionally-required) - [Recommended](#recommended) -- [Optional](#optional) +- [Opt-In](#opt-in) The requirement level for attribute is defined by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When defining requirement levels, semantic conventions MUST take into account signal-specific requirements. -For example, Metric attributes that may have high cardinality can only be defined with `Optional` level. +For example, Metric attributes that may have high cardinality can only be defined with `Opt-In` level. Semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. @@ -46,7 +46,7 @@ All instrumentations MUST add the attribute when given condition is satisfied. S `http.route` is an example of a conditionally required attribute to be populated when instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute. -When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Optional` requirement level on the attribute. +When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available, instrumentation can do a DNS lookup, cache and populate `net.sock.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. @@ -54,11 +54,11 @@ For example, `net.peer.name` is `Conditionally Required` by [Database convention Instrumentations SHOULD add the attribute by default if it's readily available and can be [efficiently populated](#performance-suggestions). Instrumentations MAY offer a configuration option to disable Recommended attributes. -Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD use the `Optional` requirement level on them if the attributes are logically applicable. +Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD use the `Opt-In` requirement level on them if the attributes are logically applicable. -## Optional +## Opt-In -Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Optional` attributes. +Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Opt-In` attributes. ## Performance suggestions From 33069b0557075d6b52384891bc73286a39ec8186 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 6 Mar 2023 10:20:11 -0800 Subject: [PATCH 42/56] Proofread of attribute requirement levels in preparation for stability (#3270) --- .../common/attribute-requirement-level.md | 25 +++++++++++-------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index c030159409..59432e6096 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -26,44 +26,47 @@ The following attribute requirement levels are specified: - [Recommended](#recommended) - [Opt-In](#opt-in) -The requirement level for attribute is defined by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When defining requirement levels, semantic conventions MUST take into account signal-specific requirements. +The requirement level for an attribute is specified by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When specifying requirement levels, a semantic convention MUST take into account signal-specific requirements. For example, Metric attributes that may have high cardinality can only be defined with `Opt-In` level. -Semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. +A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `net.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it. ## Required -All instrumentations MUST populate the attribute. Semantic convention defining a Required attribute expects that an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, can ensure cardinality, security, and other requirements specific to signal defined by the convention. `http.method` is an example of a Required attribute. +All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.method` is an example of a Required attribute. -_Note: Consumers of telemetry can detect if telemetry item follows a specific semantic convention by checking the presence of a `Required` attribute defined by such convention. For example, the presence of `db.system` attribute on a span can be used as an indication that the span follows database semantics._ +_Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._ ## Conditionally Required -All instrumentations MUST add the attribute when given condition is satisfied. Semantic convention of a `Conditionally Required` level of an attribute MUST clarify the condition under which the attribute is expected to be populated. +All instrumentations MUST populate the attribute when the given condition is satisfied. The semantic convention of a `Conditionally Required` attribute MUST clarify the condition under which the attribute is to be populated. -`http.route` is an example of a conditionally required attribute to be populated when instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute. +`http.route` is an example of a conditionally required attribute that is populated when the instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute. -When the condition on `Conditionally Required` attribute is not satisfied and there is no requirement to populate attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. +When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. -For example, `net.peer.name` is `Conditionally Required` by [Database convention](../trace/semantic_conventions/database.md) when available. When only `net.sock.peer.addr` is available, instrumentation can do a DNS lookup, cache and populate `net.sock.peer.name` but only if user explicitly enables instrumentation to do so, considering performance issues the DNS lookup introduces. +For example, `net.peer.name` is `Conditionally Required` by the [Database convention](../trace/semantic_conventions/database.md) when available. When `net.sock.peer.addr` is available instead, instrumentation can do a DNS lookup, cache and populate `net.peer.name`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. ## Recommended Instrumentations SHOULD add the attribute by default if it's readily available and can be [efficiently populated](#performance-suggestions). Instrumentations MAY offer a configuration option to disable Recommended attributes. -Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD use the `Opt-In` requirement level on them if the attributes are logically applicable. +Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD allow for users to +opt-in to emit them as defined for the `Opt-In` requirement level (if the attributes are logically applicable). ## Opt-In Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Opt-In` attributes. +This attribute requirement level is recommended for attributes that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled enabled explicitly by a user making an informed decision. + ## Performance suggestions Here are several examples of expensive operations to be avoided by default: -- DNS lookup to populate `net.peer.name` if only IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. -- forcing `http.route` calculation before HTTP framework calculates it +- DNS lookups to populate `net.peer.name` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. +- forcing an `http.route` calculation before the HTTP framework calculates it - reading response stream to find `http.response_content_length` when `Content-Length` header is not available From 008957579546ada1000645d3dc64f3a6db5ee40b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 7 Mar 2023 11:22:32 -0800 Subject: [PATCH 43/56] Attribute requirement level follow-up edits (#3293) --- specification/common/attribute-requirement-level.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 59432e6096..c7fb99345c 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -36,7 +36,7 @@ For example, [Database semantic convention](../trace/semantic_conventions/databa ## Required -All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.method` is an example of a Required attribute. +All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.method` is an example of a Required attribute. _Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._ @@ -61,7 +61,7 @@ opt-in to emit them as defined for the `Opt-In` requirement level (if the attrib Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Opt-In` attributes. -This attribute requirement level is recommended for attributes that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled enabled explicitly by a user making an informed decision. +This attribute requirement level is recommended for attributes that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled explicitly by a user making an informed decision. ## Performance suggestions From c9c56e052b8b1de7436ac8d11789cf4932234358 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 16 Mar 2023 06:31:51 -0700 Subject: [PATCH 44/56] Clarify that attribute requirement levels apply to instrumentation libraries (#3289) Based on discussion in semconv stability WG Closes #3283 ## Changes Clarifies that attribute requirement levels apply to instrumentation. And that, because users can transform their telemetry in a number of ways (e.g. metric views, span processors, and collector transformations), these requirement levels cannot be relied on by telemetry consumers. --------- Co-authored-by: Liudmila Molkova Co-authored-by: Bogdan Drutu --- specification/common/attribute-requirement-level.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index c7fb99345c..3543970a29 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -19,6 +19,8 @@ _This section applies to Log, Metric, Resource, and Span, and describes requirement levels for attributes defined in semantic conventions._ +Attribute requirement levels apply to the [instrumentation library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library). + The following attribute requirement levels are specified: - [Required](#required) From 9cf537a2a9aaf37b41c7f7f9843f667084df809f Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 6 Apr 2023 21:56:17 -0700 Subject: [PATCH 45/56] Mark attribute requirement levels as stable (#3368) --- specification/common/attribute-requirement-level.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 3543970a29..e9da7f0702 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -1,6 +1,6 @@ # Attribute Requirement Levels for Semantic Conventions -**Status**: [Experimental](../document-status.md) +**Status**: [Stable](../document-status.md)
Table of Contents From 32292d935e744b21302ba43e8fd9fc8fa36b90cb Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Fri, 7 Apr 2023 15:55:06 -0400 Subject: [PATCH 46/56] [editorial] Use path, not external URL, for link into glossary (#3375) - Contributes to https://github.com/open-telemetry/opentelemetry.io/issues/2429 - This is part of an effort to normalize links, for improved link checking on the OTel website --- specification/common/attribute-requirement-level.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index e9da7f0702..cfbc22b9da 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -19,7 +19,7 @@ _This section applies to Log, Metric, Resource, and Span, and describes requirement levels for attributes defined in semantic conventions._ -Attribute requirement levels apply to the [instrumentation library](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library). +Attribute requirement levels apply to the [instrumentation library](../glossary.md#instrumentation-library). The following attribute requirement levels are specified: From c5237e8a4665fd5f15713cf7eea189c4671236b9 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 8 May 2023 16:19:51 -0700 Subject: [PATCH 47/56] BREAKING: Replace `net.peer.*`/`net.host.*` with `client.*`/`server.*` (and `source.*`/`destination.*`) (#3402) --- specification/common/attribute-requirement-level.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index cfbc22b9da..aca07f487c 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -50,7 +50,7 @@ All instrumentations MUST populate the attribute when the given condition is sat When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. -For example, `net.peer.name` is `Conditionally Required` by the [Database convention](../trace/semantic_conventions/database.md) when available. When `net.sock.peer.addr` is available instead, instrumentation can do a DNS lookup, cache and populate `net.peer.name`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. +For example, `server.address` is `Conditionally Required` by the [Database convention](../trace/semantic_conventions/database.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. ## Recommended @@ -69,6 +69,6 @@ This attribute requirement level is recommended for attributes that are particul Here are several examples of expensive operations to be avoided by default: -- DNS lookups to populate `net.peer.name` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. +- DNS lookups to populate `server.address` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. - forcing an `http.route` calculation before the HTTP framework calculates it - reading response stream to find `http.response_content_length` when `Content-Length` header is not available From cf7de341175ef80da14a90cc905ea85127507233 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 8 May 2023 17:46:55 -0700 Subject: [PATCH 48/56] BREAKING: Rename remaining network attributes from `net.*` to `network.*` and align definitions with ECS (#3426) --- specification/common/attribute-requirement-level.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index aca07f487c..fc3f5b89d3 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -34,7 +34,7 @@ For example, Metric attributes that may have high cardinality can only be define A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. -For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `net.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it. +For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `network.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it. ## Required From a99da5e5cf7717ceac3d704c0cd9c67f2cf94f18 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 8 May 2023 19:55:53 -0700 Subject: [PATCH 49/56] BREAKING: Introduce common `url.*` attributes, and improve use of namespacing under `http.*` (#3355) --- specification/common/attribute-naming.md | 6 +-- .../common/attribute-requirement-level.md | 4 +- specification/common/url.md | 45 +++++++++++++++++++ 3 files changed, 50 insertions(+), 5 deletions(-) create mode 100644 specification/common/url.md diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index d761b5f9fd..67aee0ad09 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -44,7 +44,7 @@ Names SHOULD follow these rules: purpose should primarily drive the decision about forming nested namespaces. - 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` + words by underscores (i.e. use snake_case). For example `http.response.status_code` denotes the status code in the http namespace. - Names SHOULD NOT coincide with namespaces. For example if @@ -96,8 +96,8 @@ denote old attribute names in rename operations). - Semantic conventions exist for four areas: for Resource, Span, Log, and Metric attribute names. In addition, for spans we have two more areas: Event and Link attribute names. Identical namespaces or names in all these areas MUST have - identical meanings. For example the `http.method` span attribute name denotes - exactly the same concept as the `http.method` metric attribute, has the same + identical meanings. For example the `http.request.method` span attribute name denotes + exactly the same concept as the `http.request.method` metric attribute, has the same data type and the same set of possible values (in both cases it records the value of the HTTP protocol's request method as a string). diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index fc3f5b89d3..52f8e34f26 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -38,7 +38,7 @@ For example, [Database semantic convention](../trace/semantic_conventions/databa ## Required -All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.method` is an example of a Required attribute. +All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.request.method` is an example of a Required attribute. _Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._ @@ -71,4 +71,4 @@ Here are several examples of expensive operations to be avoided by default: - DNS lookups to populate `server.address` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. - forcing an `http.route` calculation before the HTTP framework calculates it -- reading response stream to find `http.response_content_length` when `Content-Length` header is not available +- reading response stream to find `http.response.body.size` when `Content-Length` header is not available diff --git a/specification/common/url.md b/specification/common/url.md new file mode 100644 index 0000000000..bbe041ba67 --- /dev/null +++ b/specification/common/url.md @@ -0,0 +1,45 @@ +# Semantic conventions for URL + +**Status**: [Experimental](../document-status.md) + +This document defines semantic conventions that describe URL and its components. + +
+Table of Contents + + + +- [Attributes](#attributes) +- [Sensitive information](#sensitive-information) + + + +
+ +## Attributes + + +| Attribute | Type | Description | Examples | Requirement Level | +|---|---|---|---|---| +| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | +| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | +| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended | +| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended | +| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | + +**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. +`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. +`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. + +**[2]:** When missing, the value is assumed to be `/` + +**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. + + +## Sensitive information + +Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) subcomponent, MUST NOT be recorded. + +Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing `url.query` attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties. + +_Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._ From c98792c522a1a0d1fe2bb1d7b353ea5094fc2682 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Fri, 26 May 2023 11:23:42 -0400 Subject: [PATCH 50/56] Explain why custom attributes are not recommended to be placed in Otel namespaces (#3507) The @open-telemetry/technical-committee discussed and decided to keep the existing recommendations but clarify them and explain the purpose. --- specification/common/attribute-naming.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 67aee0ad09..badb9acbd0 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -133,6 +133,13 @@ To do that consider a few options: `myuniquemapapp.longitude` is likely fine). Make sure the application name does not clash with an existing semantic convention namespace. +- It is not recommended to use existing OpenTelemetry semantic convention namespace + as a prefix for a new company- or application-specific attribute name. Doing so + may result in a name clash in the future, if OpenTelemetry decides to use that + same name for a different purpose or if some other third party instrumentation + decides to use that exact same attribute name and you combine that instrumentation + with your own. + - The name may be generally applicable to applications in the industry. In that case consider submitting a proposal to this specification to add a new name to the semantic conventions, and if necessary also to add a new namespace. From e40b6d56c22fad3ccea4656602a03e21bbf88207 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 12 Jul 2023 10:58:54 -0400 Subject: [PATCH 51/56] [editorial] Hugo front-matter fixes for aliases and linkTitle (#3592) - Followup changes for https://github.com/open-telemetry/opentelemetry.io/issues/2793 - There are only changes to Hugo front matter - Adds `likeTitle`s for "Compatibility" pages - Adds aliases for pages that have moved or were renamed - Related: https://github.com/open-telemetry/opentelemetry.io/issues/3013 -- the `compatibility/openmetrics` spec page is in the list because it was renamed /cc @svrnm @cartermp --- specification/common/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/specification/common/README.md b/specification/common/README.md index f36cb92b85..239bdf2014 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -1,6 +1,7 @@ + # Common specification concepts **Status**: [Stable, Feature-freeze](../document-status.md) From d028b068c7f3cb475d37c202ea7e2e67e939589f Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Tue, 3 Oct 2023 12:13:38 -0400 Subject: [PATCH 52/56] Remove local stubs of semantic conventions. (#3711) --- specification/common/attribute-naming.md | 14 +++----------- .../common/attribute-requirement-level.md | 6 ++++-- 2 files changed, 7 insertions(+), 13 deletions(-) diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index badb9acbd0..548703db6f 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -65,7 +65,7 @@ Names SHOULD follow these rules: values: the executable name and command arguments. - When an attribute represents a measurement, - [Metric Name Pluralization Guidelines](../metrics/semantic_conventions/README.md#pluralization) + [Metric Name Pluralization Guidelines](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#pluralization) SHOULD be followed for the attribute name. ## Name Reuse Prohibition @@ -83,11 +83,7 @@ denote old attribute names in rename operations). of a namespace. - When coming up with a new semantic convention make sure to check existing - namespaces for - [Resources](../resource/semantic_conventions/README.md), - [Spans](../trace/semantic_conventions/README.md), - and - [Metrics](../metrics/semantic_conventions/README.md) + namespaces ([Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md)) to see if the new name fits. - When a new namespace is necessary consider whether it should be a top-level @@ -111,11 +107,7 @@ denote old attribute names in rename operations). ## Recommendations for Application Developers As an application developer when you need to record an attribute first consult -existing semantic conventions for -[Resources](../resource/semantic_conventions/README.md), -[Spans](../trace/semantic_conventions/README.md), -and -[Metrics](../metrics/semantic_conventions/README.md). +existing [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md). If an appropriate name does not exists you will need to come up with a new name. To do that consider a few options: diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 52f8e34f26..1866c413ca 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -34,7 +34,8 @@ For example, Metric attributes that may have high cardinality can only be define A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. -For example, [Database semantic convention](../trace/semantic_conventions/database.md) references `network.transport` attribute defined in [General attributes](../trace/semantic_conventions/span-general.md) with `Conditionally Required` level on it. + +For example, [Database semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) references `network.transport` attribute defined in [General attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/README.md) with `Conditionally Required` level on it. ## Required @@ -50,7 +51,8 @@ All instrumentations MUST populate the attribute when the given condition is sat When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. -For example, `server.address` is `Conditionally Required` by the [Database convention](../trace/semantic_conventions/database.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. + +For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. ## Recommended From 093bd1f5d7c85e2f300c2686cb60c27625c692ae Mon Sep 17 00:00:00 2001 From: Carlos Alberto Cortez Date: Wed, 11 Oct 2023 01:15:24 +0200 Subject: [PATCH 53/56] Add a new AddLink() operation to Span. (#3678) Fixes #454 Related to #3337 As the Messaging SIG merged its last OTEP 222, we will be adding operations that require Links after Span creation, taking a direct route with `AddLink()`, albeit without any of the new members suggested in #3337, e.g. `timestamp` (to be discussed in a separate issue). ``` AddLink(spanContext, attributes /* optional */) ``` --- specification/common/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/README.md b/specification/common/README.md index 239bdf2014..1f17536bb6 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -123,7 +123,7 @@ at this time, as discussed in [data 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#specifying-links) and +[Links](../trace/api.md#link) and [Log Records](../logs/data-model.md) may contain a collection of attributes. The keys in each such collection are unique, i.e. there MUST NOT exist more than one key-value pair with the same key. The enforcement of uniqueness may be performed From 33d1c2fd03685f294dafbc158a9b02edec8edd53 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Mon, 23 Oct 2023 08:19:08 -0700 Subject: [PATCH 54/56] Rename/replace `(client|server).socket.(address|port)` attributes with `network.(peer|local).(address|port)`. (#3713) Co-authored-by: Armin Ruech --- specification/common/attribute-requirement-level.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 1866c413ca..7f510fe731 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -52,7 +52,7 @@ All instrumentations MUST populate the attribute when the given condition is sat When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. -For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `server.socket.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. +For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `network.peer.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. ## Recommended From dc5e136fff95880cf1a748de2b59cceeb8d774ca Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Fri, 24 Nov 2023 10:05:54 -0600 Subject: [PATCH 55/56] Move attribute documents to semantic-conventions repository (#3758) Co-authored-by: Armin Ruech <7052238+arminru@users.noreply.github.com> --- specification/common/README.md | 4 +- specification/common/attribute-naming.md | 156 +----------------- .../common/attribute-requirement-level.md | 76 +-------- specification/common/url.md | 45 ----- 4 files changed, 6 insertions(+), 275 deletions(-) delete mode 100644 specification/common/url.md diff --git a/specification/common/README.md b/specification/common/README.md index 1f17536bb6..1b46da3e62 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -53,9 +53,9 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). -See [Attribute Naming](attribute-naming.md) for naming guidelines. +See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines. -See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines. +See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md) for requirement levels guidelines. See [this document](attribute-type-mapping.md) to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 548703db6f..68f6ca6560 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -1,156 +1,4 @@ # Attribute Naming -**Status**: [Stable](../document-status.md) - -
-Table of Contents - - - -- [Name Pluralization guidelines](#name-pluralization-guidelines) -- [Name Reuse Prohibition](#name-reuse-prohibition) -- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) -- [Recommendations for Application Developers](#recommendations-for-application-developers) -- [otel.* Namespace](#otel-namespace) - - - -
- -_This section applies to Resource, Span, Log, and Metric attribute names (also -known as the "attribute keys"). For brevity within this section when we use the -term "name" without an adjective it is implied to mean "attribute name"._ - -Every name MUST be a valid Unicode sequence. - -_Note: we merely require that the names are represented as Unicode sequences. -This specification does not define how exactly the Unicode sequences are -encoded. The encoding can vary from one programming language to another and from -one wire format to another. Use the idiomatic way to represent Unicode in the -particular programming language or wire format._ - -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. - Note: the fact that an entity is located within another entity is typically - not a sufficient reason for forming nested namespaces. The purpose of a - namespace is to avoid name clashes, not to indicate entity hierarchies. This - purpose should primarily drive the decision about forming nested namespaces. - -- For each multi-word dot-delimited component of the attribute name separate the - words by underscores (i.e. use snake_case). For example `http.response.status_code` - denotes the status code in the http namespace. - -- 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 names: every existing - name prohibits existence of an equally named namespace in the future, and vice - versa: any existing namespace prohibits existence of an equally named - attribute key in the future. - -## Name Pluralization guidelines - -- When an attribute represents a single entity, the attribute name SHOULD be singular. - Examples: `host.name`, `db.user`, `container.id`. - -- When attribute can represent multiple entities, the attribute name SHOULD be pluralized - and the value type SHOULD be an array. E.g. `process.command_args` might include multiple - values: the executable name and command arguments. - -- When an attribute represents a measurement, - [Metric Name Pluralization Guidelines](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/metrics.md#pluralization) - SHOULD be followed for the attribute name. - -## Name Reuse Prohibition - -A new attribute MUST NOT be added with the same name as an attribute that -existed in the past but was renamed (with a corresponding schema file). - -When introducing a new attribute name check all existing schema files to make -sure the name does not appear as a key of any "rename_attributes" section (keys -denote old attribute names in rename operations). - -## Recommendations for OpenTelemetry Authors - -- All names that are part of OpenTelemetry semantic conventions SHOULD be part - of a namespace. - -- When coming up with a new semantic convention make sure to check existing - namespaces ([Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md)) - to see if the new name 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 exist for four areas: for Resource, Span, Log, and Metric - attribute names. In addition, for spans we have two more areas: Event and Link - attribute names. Identical namespaces or names in all these areas MUST have - identical meanings. For example the `http.request.method` span attribute name denotes - exactly the same concept as the `http.request.method` metric attribute, has the same - data type and the same set of possible values (in both cases it records the - value of the HTTP protocol's request method as a string). - -- Semantic conventions MUST limit 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). It is recommended to further limit 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](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/README.md). -If an appropriate name does not exists you will need to come up with a new name. -To do that consider a few options: - -- The name is specific to your company and may be possibly used outside the - company as well. To avoid clashes with names introduced by other companies (in - a distributed system that uses applications from multiple vendors) it is - recommended to prefix the new name by your company's reverse domain name, e.g. - `com.acme.shopname`. - -- The name 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. - -- It is not recommended to use existing OpenTelemetry semantic convention namespace - as a prefix for a new company- or application-specific attribute name. Doing so - may result in a name clash in the future, if OpenTelemetry decides to use that - same name for a different purpose or if some other third party instrumentation - decides to use that exact same attribute name and you combine that instrumentation - with your own. - -- The name may be generally applicable to applications in the industry. In that - case consider submitting a proposal to this specification to add a new name to - the semantic conventions, and if necessary also to add a new namespace. - -It is recommended to limit 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). - -## otel.* Namespace - -Attribute names that start with `otel.` are reserved to be defined by -OpenTelemetry specification. These are typically used to express OpenTelemetry -concepts in formats that don't have a corresponding concept. - -For example, the `otel.scope.name` attribute is used to record the -instrumentation scope name, which is an OpenTelemetry concept that is natively -represented in OTLP, but does not have an equivalent in other telemetry formats -and protocols. - -Any additions to the `otel.*` namespace MUST be approved as part of -OpenTelemetry specification. +This page has moved to +[github.com/open-telemetry/semantic-conventions/docs/general/attribute-naming.md](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md). diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md index 7f510fe731..bcbe62b0a8 100644 --- a/specification/common/attribute-requirement-level.md +++ b/specification/common/attribute-requirement-level.md @@ -1,76 +1,4 @@ # Attribute Requirement Levels for Semantic Conventions -**Status**: [Stable](../document-status.md) - -
-Table of Contents - - - -- [Required](#required) -- [Conditionally Required](#conditionally-required) -- [Recommended](#recommended) -- [Opt-In](#opt-in) -- [Performance suggestions](#performance-suggestions) - - - -
- -_This section applies to Log, Metric, Resource, and Span, and describes requirement levels for attributes defined in semantic conventions._ - -Attribute requirement levels apply to the [instrumentation library](../glossary.md#instrumentation-library). - -The following attribute requirement levels are specified: - -- [Required](#required) -- [Conditionally Required](#conditionally-required) -- [Recommended](#recommended) -- [Opt-In](#opt-in) - -The requirement level for an attribute is specified by semantic conventions depending on attribute availability across instrumented entities, performance, security, and other factors. When specifying requirement levels, a semantic convention MUST take into account signal-specific requirements. - -For example, Metric attributes that may have high cardinality can only be defined with `Opt-In` level. - -A semantic convention that refers to an attribute from another semantic convention MAY modify the requirement level within its own scope. Otherwise, requirement level from the referred semantic convention applies. - - -For example, [Database semantic convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) references `network.transport` attribute defined in [General attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/README.md) with `Conditionally Required` level on it. - -## Required - -All instrumentations MUST populate the attribute. A semantic convention defining a Required attribute expects an absolute majority of instrumentation libraries and applications are able to efficiently retrieve and populate it, and can additionally meet requirements for cardinality, security, and any others specific to the signal defined by the convention. `http.request.method` is an example of a Required attribute. - -_Note: Consumers of telemetry can detect if a telemetry item follows a specific semantic convention by checking for the presence of a `Required` attribute defined by such convention. For example, the presence of the `db.system` attribute on a span can be used as an indication that the span follows database semantics._ - -## Conditionally Required - -All instrumentations MUST populate the attribute when the given condition is satisfied. The semantic convention of a `Conditionally Required` attribute MUST clarify the condition under which the attribute is to be populated. - -`http.route` is an example of a conditionally required attribute that is populated when the instrumented HTTP framework provides route information for the instrumented request. Some low-level HTTP server implementations do not support routing and corresponding instrumentations can't populate the attribute. - -When a `Conditionally Required` attribute's condition is not satisfied, and there is no requirement to populate the attribute, semantic conventions MAY provide special instructions on how to handle it. If no instructions are given and if instrumentation can populate the attribute, instrumentation SHOULD use the `Opt-In` requirement level on the attribute. - - -For example, `server.address` is `Conditionally Required` by the [Database convention](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/README.md) when available. When `network.peer.address` is available instead, instrumentation can do a DNS lookup, cache and populate `server.address`, but only if the user explicitly enables the instrumentation to do so, considering the performance issues that DNS lookups introduce. - -## Recommended - -Instrumentations SHOULD add the attribute by default if it's readily available and can be [efficiently populated](#performance-suggestions). Instrumentations MAY offer a configuration option to disable Recommended attributes. - -Instrumentations that decide not to populate `Recommended` attributes due to [performance](#performance-suggestions), security, privacy, or other consideration by default, SHOULD allow for users to -opt-in to emit them as defined for the `Opt-In` requirement level (if the attributes are logically applicable). - -## Opt-In - -Instrumentations SHOULD populate the attribute if and only if the user configures the instrumentation to do so. Instrumentation that doesn't support configuration MUST NOT populate `Opt-In` attributes. - -This attribute requirement level is recommended for attributes that are particularly expensive to retrieve or might pose a security or privacy risk. These should therefore only be enabled explicitly by a user making an informed decision. - -## Performance suggestions - -Here are several examples of expensive operations to be avoided by default: - -- DNS lookups to populate `server.address` when only an IP address is available to the instrumentation. Caching lookup results does not solve the issue for all possible cases and should be avoided by default too. -- forcing an `http.route` calculation before the HTTP framework calculates it -- reading response stream to find `http.response.body.size` when `Content-Length` header is not available +This page has moved to +[github.com/open-telemetry/semantic-conventions/docs/general/attribute-requirement-level.md](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md). diff --git a/specification/common/url.md b/specification/common/url.md deleted file mode 100644 index bbe041ba67..0000000000 --- a/specification/common/url.md +++ /dev/null @@ -1,45 +0,0 @@ -# Semantic conventions for URL - -**Status**: [Experimental](../document-status.md) - -This document defines semantic conventions that describe URL and its components. - -
-Table of Contents - - - -- [Attributes](#attributes) -- [Sensitive information](#sensitive-information) - - - -
- -## Attributes - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `url.scheme` | string | The [URI scheme](https://www.rfc-editor.org/rfc/rfc3986#section-3.1) component identifying the used protocol. | `https`; `ftp`; `telnet` | Recommended | -| `url.full` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv`; `//localhost` | Recommended | -| `url.path` | string | The [URI path](https://www.rfc-editor.org/rfc/rfc3986#section-3.3) component [2] | `/search` | Recommended | -| `url.query` | string | The [URI query](https://www.rfc-editor.org/rfc/rfc3986#section-3.4) component [3] | `q=OpenTelemetry` | Recommended | -| `url.fragment` | string | The [URI fragment](https://www.rfc-editor.org/rfc/rfc3986#section-3.5) component | `SemConv` | Recommended | - -**[1]:** For network calls, URL usually has `scheme://host[:port][path][?query][#fragment]` format, where the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. -`url.full` MUST NOT contain credentials passed via URL in form of `https://username:password@www.example.com/`. In such case username and password should be redacted and attribute's value should be `https://REDACTED:REDACTED@www.example.com/`. -`url.full` SHOULD capture the absolute URL when it is available (or can be reconstructed) and SHOULD NOT be validated or modified except for sanitizing purposes. - -**[2]:** When missing, the value is assumed to be `/` - -**[3]:** Sensitive content provided in query string SHOULD be scrubbed when instrumentations can identify it. - - -## Sensitive information - -Capturing URL and its components MAY impose security risk. User and password information, when they are provided in [User Information](https://datatracker.ietf.org/doc/html/rfc3986#section-3.2.1) subcomponent, MUST NOT be recorded. - -Instrumentations that are aware of specific sensitive query string parameters MUST scrub their values before capturing `url.query` attribute. For example, native instrumentation of a client library that passes credentials or user location in URL, must scrub corresponding properties. - -_Note: Applications and telemetry consumers should scrub sensitive information from URL attributes on collected telemetry. In systems unable to identify sensitive information, certain attribute values may be redacted entirely._ From 5ab265dee341471165db6103e2fb7e807c9bea0f Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Wed, 10 Jan 2024 14:53:41 -0300 Subject: [PATCH 56/56] Remove unwanted files and update links to spec repo --- .../general/attribute-definition.md | 48 ++-- specification/common/attribute-naming.md | 4 - .../common/attribute-requirement-level.md | 4 - .../common/attribute-type-mapping.md | 255 ------------------ specification/common/mapping-to-non-otlp.md | 95 ------- 5 files changed, 28 insertions(+), 378 deletions(-) rename specification/common/README.md => docs/general/attribute-definition.md (70%) delete mode 100644 specification/common/attribute-naming.md delete mode 100644 specification/common/attribute-requirement-level.md delete mode 100644 specification/common/attribute-type-mapping.md delete mode 100644 specification/common/mapping-to-non-otlp.md diff --git a/specification/common/README.md b/docs/general/attribute-definition.md similarity index 70% rename from specification/common/README.md rename to docs/general/attribute-definition.md index 1b46da3e62..42a82a609e 100644 --- a/specification/common/README.md +++ b/docs/general/attribute-definition.md @@ -1,10 +1,9 @@ -# Common specification concepts +# Attribute definition -**Status**: [Stable, Feature-freeze](../document-status.md) +**Status**: [Stable, Feature-freeze][DocumentStatus]
Table of Contents @@ -28,6 +27,7 @@ aliases: [/docs/reference/specification/common/common] An `Attribute` is a key-value pair, which MUST have the following properties: - The attribute key MUST be a non-`null` and non-empty string. + - Case sensitivity of keys is preserved. Keys that differ in casing are treated as distinct keys. - The attribute value is either: - A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer. - An array of primitive type values. The array MUST be homogeneous, @@ -53,11 +53,13 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). -See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines. +See [Attribute Naming](attribute-naming.md) for naming guidelines. -See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md) for requirement levels guidelines. +See [Requirement Level](attribute-requirement-level.md) for requirement levels guidelines. -See [this document](attribute-type-mapping.md) to find out how to map values obtained +See +[Mapping Arbitrary Data to OTLP AnyValue](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-type-mapping.md) +to find out how to map values obtained outside OpenTelemetry into OpenTelemetry attribute values. ### Attribute Limits @@ -115,16 +117,16 @@ attribute limits for Resources. Attributes, which belong to Metrics, are exempt from the limits described above at this time, as discussed in -[Metrics Attribute Limits](../metrics/sdk.md#attribute-limits). +[Metrics Attribute Limits](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#attribute-limits). ## Attribute Collections -[Resources](../resource/sdk.md), Metrics -[data 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 -[Log Records](../logs/data-model.md) may contain a collection of attributes. The +[Resources](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md), Metrics +[data points](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#metric-points), +[Spans](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-attributes), Span +[Events](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#add-events), Span +[Links](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#link) and +[Log Records](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md) may contain a collection of attributes. The keys in each such collection are unique, i.e. there MUST NOT exist more than one key-value pair with the same key. The enforcement of uniqueness may be performed in a variety of ways as it best fits the limitations of the particular @@ -134,17 +136,23 @@ Normally for the telemetry generated using OpenTelemetry SDKs the attribute key-value pairs are set via an API that either accepts a single key-value pair or a collection of key-value pairs. Setting an attribute with the same key as an existing attribute SHOULD overwrite the existing attribute's value. See for -example Span's [SetAttribute](../trace/api.md#set-attributes) API. +example Span's +[SetAttribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-attributes) +API. -A typical implementation of [SetAttribute](../trace/api.md#set-attributes) API -will enforce the uniqueness by overwriting any existing attribute values pending +A typical implementation of +[SetAttribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-attributes) +API will enforce the uniqueness by overwriting any existing attribute values pending to be exported, so that when the Span is eventually exported the exporters see only unique attributes. The OTLP format in particular requires that exported Resources, Spans, Metric data points and Log Records contain only unique attributes. Some other implementations may use a streaming approach where every -[SetAttribute](../trace/api.md#set-attributes) API call immediately results in -that individual attribute value being exported using a streaming wire protocol. -In such cases the enforcement of uniqueness will likely be the responsibility of -the recipient of this data. +[SetAttribute](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#set-attributes) +API call immediately results in that individual attribute value being exported +using a streaming wire protocol. In such cases the enforcement of uniqueness +will likely be the responsibility of the recipient of this data. + +[DocumentStatus]: + https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md deleted file mode 100644 index 68f6ca6560..0000000000 --- a/specification/common/attribute-naming.md +++ /dev/null @@ -1,4 +0,0 @@ -# Attribute Naming - -This page has moved to -[github.com/open-telemetry/semantic-conventions/docs/general/attribute-naming.md](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md). diff --git a/specification/common/attribute-requirement-level.md b/specification/common/attribute-requirement-level.md deleted file mode 100644 index bcbe62b0a8..0000000000 --- a/specification/common/attribute-requirement-level.md +++ /dev/null @@ -1,4 +0,0 @@ -# Attribute Requirement Levels for Semantic Conventions - -This page has moved to -[github.com/open-telemetry/semantic-conventions/docs/general/attribute-requirement-level.md](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md). diff --git a/specification/common/attribute-type-mapping.md b/specification/common/attribute-type-mapping.md deleted file mode 100644 index 532d6156bc..0000000000 --- a/specification/common/attribute-type-mapping.md +++ /dev/null @@ -1,255 +0,0 @@ -# Mapping Arbitrary Data to OTLP AnyValue - -**Status**: [Experimental](../document-status.md) - -
-Table of Contents - - - -- [Converting to AnyValue](#converting-to-anyvalue) - * [Primitive Values](#primitive-values) - + [Integer Values](#integer-values) - + [Enumerations](#enumerations) - + [Floating Point Values](#floating-point-values) - + [String Values](#string-values) - + [Byte Sequences](#byte-sequences) - * [Composite Values](#composite-values) - + [Array Values](#array-values) - + [Associative Arrays With Unique Keys](#associative-arrays-with-unique-keys) - + [Associative Arrays With Non-Unique Keys](#associative-arrays-with-non-unique-keys) - + [Sets](#sets) - * [Other Values](#other-values) - * [Empty Values](#empty-values) - - - -
- -This document defines how to map (convert) arbitrary data (e.g. in-memory -objects) to OTLP's [AnyValue](https://github.com/open-telemetry/opentelemetry-proto/blob/cc4ed55c082cb75e084d40b4ddf3805eda099f97/opentelemetry/proto/common/v1/common.proto#L27). - -The mapping is needed when OpenTelemetry needs to convert a value produced outside -OpenTelemetry into a value that can be exported using an OTLP exporter, or otherwise be -converted to be used inside OpenTelemetry boundaries. Example use cases are the following: - -- In the [Logging SDK](../logs/sdk.md)s, to convert values received - from logging libraries into OpenTelemetry representation. -- In the Collector, to convert values received from various data sources into - [pdata](https://github.com/open-telemetry/opentelemetry-collector/blob/4998703dadd19fa91a88eabf7ccc68d728bee3fd/model/pdata/common.go#L84) - internal representation. - -## Converting to AnyValue - -[AnyValue](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L27) -is capable of representing primitive and structured data of certain types. - -Implementations that have source data in any form, such as in-memory objects -or data coming from other formats that needs to be converted to AnyValue SHOULD -follow the rules described below. - -### Primitive Values - -#### Integer Values - -Integer values which are within the range of 64 bit signed numbers -[-2^63..2^63-1] SHOULD be converted to AnyValue's -[int_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L33) -field. - -Integer values which are outside the range of 64 bit signed numbers SHOULD be -converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field using decimal representation. - -#### Enumerations - -Values, which belong to a limited enumerated set (e.g. a Java -[enum](https://docs.oracle.com/javase/tutorial/java/javaOO/enum.html)), SHOULD be -converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field with the value of the string set to the symbolic name of the enumeration. - -If it is not possible to obtain the symbolic name of the enumeration, the -implementation SHOULD map enumeration values to AnyValue's -[int_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L33) -field set to the enum's ordinal value, when such an ordinal number is naturally -obtainable. - -If it is also not possible to obtain the ordinal value, the enumeration SHOULD be -converted to AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -field in any manner that the implementation deems reasonable. - -#### Floating Point Values - -Floating point values which are within the range and precision of IEEE 754 -64-bit floating point numbers (including IEEE 32-bit floating point values) -SHOULD be converted to AnyValue's -[double_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L34) -field. - -Floating point values which are outside the range or precision of IEEE 754 -64-bit floating point numbers (e.g. IEEE 128-bit floating bit values) SHOULD be -converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field using decimal floating point representation. - -#### String Values - -String values which are valid UTF-8 sequences SHOULD be converted to -AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field. - -String values which are not valid Unicode sequences SHOULD be converted to -AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -with the bytes representing the string in the original order and format of the -source string. - -#### Byte Sequences - -Byte sequences (e.g. Go's `[]byte` slice or raw byte content of a file) SHOULD -be converted to AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -field. - -### Composite Values - -#### Array Values - -Values that represent ordered sequences of other values (such as -[arrays](https://docs.oracle.com/javase/specs/jls/se7/html/jls-10.html), -[vectors](https://en.cppreference.com/w/cpp/container/vector), ordered -[lists](https://docs.python.org/3/tutorial/datastructures.html#more-on-lists), -[slices](https://golang.org/ref/spec#Slice_types)) SHOULD be converted to -AnyValue's -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -field. String values and byte sequences are an exception from this rule (see -above). - -The rules described in this document should be applied recursively to each element -of the array. - -#### Associative Arrays With Unique Keys - -Values that represent associative arrays with unique keys (also often known -as maps, dictionaries or key-value stores) SHOULD be converted to AnyValue's -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field. - -If the keys of the source array are not strings, they MUST be converted to -strings by any means available, often via a toString() or stringify functions -available in programming languages. The conversion function MUST be chosen in a -way that ensures that the resulting string keys are unique in the target array. - -The value part of each element of the source array SHOULD be converted to -AnyValue recursively. - -For example a JSON object `{"a": 123, "b": "def"}` SHOULD be converted to - -``` -AnyValue{ - kvlist_value:KeyValueList{ - values:[ - KeyValue{key:"a",value:AnyValue{int_value:123}}, - KeyValue{key:"b",value:AnyValue{string_value:"def"}}, - ] - } -} -``` - -The rules described in this document should be applied recursively to each value -of the associative array. - -#### Associative Arrays With Non-Unique Keys - -Values that represent an associative arrays with non-unique keys where multiple values may be associated with the same key (also sometimes known -as multimaps, multidicts) SHOULD be converted to AnyValue's -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field. - -The resulting -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field MUST list each key only once and the value of each element of -[kvlist_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L36) -field MUST be an array represented using AnyValue's -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -field, each element of the -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -representing one value of source array associated with the given key. - -For example an associative array shown in the following table: - -|Key|Value| -|---|---| -|"abc"|123| -|"def"|"foo"| -|"def"|"bar"| - -SHOULD be converted to: - -``` -AnyValue{ - kvlist_value:KeyValueList{ - values:[ - KeyValue{ - key:"abc", - value:AnyValue{array_value:ArrayValue{values[ - AnyValue{int_value:123} - ]}} - }, - KeyValue{ - key:"def", - value:AnyValue{array_value:ArrayValue{values[ - AnyValue{string_value:"foo"}, - AnyValue{string_value:"bar"} - ]}} - }, - ] - } -} -``` - -The rules described in this document should be applied recursively to each value -of the associative array. - -#### Sets - -Unordered collections of unique values (such as -[Java Sets](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/Set.html), -[C++ sets](https://en.cppreference.com/w/cpp/container/set), -[Python Sets](https://docs.python.org/3/tutorial/datastructures.html#sets)) SHOULD be -converted to AnyValue's -[array_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L35) -field, where each element of the set becomes an element of the array. - -The rules described in this document should be applied recursively to each value -of the set. - -### Other Values - -Any other values not listed above SHOULD be converted to AnyValue's -[string_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L31) -field if the source data can be serialized to a string (can be stringified) -using toString() or stringify functions available in programming languages. - -If the source data cannot be serialized to a string then the value SHOULD be -converted AnyValue's -[bytes_value](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L37) -field by serializing it into a byte sequence by any means available. - -If the source data cannot be serialized neither to a string nor to a byte -sequence then it SHOULD by converted to an empty AnyValue. - -### Empty Values - -If the source data has no type associated with it and is empty, null, nil or -otherwise indicates absence of data it SHOULD be converted to an -[empty](https://github.com/open-telemetry/opentelemetry-proto/blob/38b5b9b6e5257c6500a843f7fdacf89dd95833e8/opentelemetry/proto/common/v1/common.proto#L29) -AnyValue, where all the fields are unset. - -Empty values which has a type associated with them (e.g. empty associative -array) SHOULD be converted using the corresponding rules defined for the types -above. diff --git a/specification/common/mapping-to-non-otlp.md b/specification/common/mapping-to-non-otlp.md deleted file mode 100644 index a82dac3e63..0000000000 --- a/specification/common/mapping-to-non-otlp.md +++ /dev/null @@ -1,95 +0,0 @@ -# OpenTelemetry Transformation to non-OTLP Formats - -**Status**: [Stable](../document-status.md) - -All OpenTelemetry concepts and data recorded using OpenTelemetry API can be -directly and precisely represented using corresponding messages and fields of -OTLP format. However, for other formats this is not always the case. Sometimes a -format will not have a native way to represent a particular OpenTelemetry -concept or a field of a concept. - -This document defines the transformation between OpenTelemetry and formats other -than OTLP, for OpenTelemetry fields and concepts that have no direct semantic -equivalent in those other formats. - -Note: when a format has a direct semantic equivalent for a particular field or -concept then the recommendation in this document MUST be ignored. - -See also additional specific transformation rules for -[Jaeger](../trace/sdk_exporters/jaeger.md) and [Zipkin](../trace/sdk_exporters/zipkin.md). -The specific rules for Jaeger and Zipkin take precedence over the generic rules defined -in this document. - -## Mappings - -### InstrumentationScope - -OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value -pairs associated with the Span, Metric Data Point or LogRecord using the following mapping: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `otel.scope.name` | string | The name of the instrumentation scope - (`InstrumentationScope.Name` in OTLP). | `io.opentelemetry.contrib.mongodb` | Recommended | -| `otel.scope.version` | string | The version of the instrumentation scope - (`InstrumentationScope.Version` in OTLP). | `1.0.0` | Recommended | - - -The following deprecated aliases MUST also be reported with exact same values for -backward compatibility reasons: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `otel.library.name` | string | Deprecated, use the `otel.scope.name` attribute. | `io.opentelemetry.contrib.mongodb` | Recommended | -| `otel.library.version` | string | Deprecated, use the `otel.scope.version` attribute. | `1.0.0` | Recommended | - - -### Span Status - -Span `Status` MUST be reported as key-value pairs associated with the Span, -unless the `Status` is `UNSET`. In the latter case it MUST NOT be reported. - -The following table defines the OpenTelemetry `Status`'s mapping to Span's -key-value pairs: - - -| Attribute | Type | Description | Examples | Requirement Level | -|---|---|---|---|---| -| `otel.status_code` | string | Name of the code, either "OK" or "ERROR". MUST NOT be set if the status code is UNSET. | `OK` | Recommended | -| `otel.status_description` | string | Description of the Status if it has a value, otherwise not set. | `resource not found` | Recommended | - -`otel.status_code` MUST be one of the following: - -| Value | Description | -|---|---| -| `OK` | The operation has been validated by an Application developer or Operator to have completed successfully. | -| `ERROR` | The operation contains an error. | - - -### Dropped Attributes Count - -OpenTelemetry dropped attributes count MUST be reported as a key-value -pair associated with the corresponding data entity (e.g. Span, Span Link, Span Event, -Metric data point, LogRecord, etc). The key name MUST be `otel.dropped_attributes_count`. - -This key-value pair should only be recorded when it contains a non-zero value. - -### Dropped Events Count - -OpenTelemetry Span's dropped events count MUST be reported as a key-value pair -associated with the Span. The key name MUST be `otel.dropped_events_count`. - -This key-value pair should only be recorded when it contains a non-zero value. - -### Dropped Links Count - -OpenTelemetry Span's dropped links count MUST be reported as a key-value pair -associated with the Span. The key name MUST be `otel.dropped_links_count`. - -This key-value pair should only be recorded when it contains a non-zero value. - -### Instrumentation Scope Attributes - -Exporters to formats that don't have a concept that is equivalent to the Scope -SHOULD record the attributes at the most suitable place in their corresponding format, -typically at the Span, Metric or LogRecord equivalent.