open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

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
This commit is contained in:
Tigran Najaryan 2020-08-19 13:49:28 -04:00 committed by Josh Suereth
parent 795086a9a5
commit 2096cb3ec5
1 changed files with 50 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
specification/common/common.md
View File

@ -6,7 +6,7 @@ Table of Contents
</summary> </summary>
- [Attributes](#attributes) - [Attributes](#attributes)
- [Attribute Naming](#attribute-naming) - [Attribute and Label Naming](#attribute-and-label-naming)
</details> </details>
## Attributes ## 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 both containing an array of strings to represent a mapping
`header_keys[i] -> header_values[i]`). `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 _This section applies to Resource, Span and Log attribute names (also known as
sequence. 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 - Use namespacing to avoid name clashes. Delimit the namespaces using a dot
character. For example `service.version` denotes the service version where 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` words by underscores (i.e. use snake_case). For example `http.status_code`
denotes the status code in the http namespace. 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 `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 an attribute named `service.instance` because `service.instance` is already a
namespace. Because of this rule be careful when choosing attribute names: namespace. Because of this rule be careful when choosing names: every existing
every existing attribute name prohibits existence of an equally named name prohibits existence of an equally named namespace in the future, and vice
namespace in the future, and vice versa: any existing namespace prohibits versa: any existing namespace prohibits existence of an equally named
existence of an equally named attribute in the future. 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 - All names that are part of OpenTelemetry semantic conventions SHOULD be part
SHOULD be part of a namespace. of a namespace.
- When coming up with a new convention make sure to check existing namespaces - When coming up with a new semantic convention make sure to check existing
for namespaces for
[Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions), [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), [Spans](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions),
and and
[Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions) [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 - 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`). namespace (e.g. `service`) or a nested namespace (e.g. `service.instance`).
- Semantic conventions MUST limit attribute names to printable Basic Latin - Semantic conventions MUST limit names to printable Basic Latin characters
characters (more precisely to (more precisely to
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) [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 subset of Unicode code points). It is recommended to further limit names to
names to the following Unicode code points: Latin alphabet, Numeric, the following Unicode code points: Latin alphabet, Numeric, Underscore, Dot
Underscore, Dot (as namespace delimiter). (as namespace delimiter).
#### Recommendations for Application Developers ### Recommendations for Application Developers
As an application developer when you need to record an attribute first consult As an application developer when you need to record an attribute or a label
existing semantic conventions for first consult existing semantic conventions for
[Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/resource/semantic_conventions), [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), [Spans](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/trace/semantic_conventions),
and and
[Metrics](https://github.com/open-telemetry/opentelemetry-specification/tree/master/specification/metrics/semantic_conventions). [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 If an appropriate name does not exists you will need to come up with a new name.
new name. To do that consider a few options: To do that consider a few options:
- The attribute is specific to your company and may be possibly used outside the - The name is specific to your company and may be possibly used outside the
company as well. To avoid name clashes with attributes introduced by other company as well. To avoid clashes with names introduced by other companies (in
companies (in a distributed system that uses applications from multiple a distributed system that uses applications from multiple vendors) it is
vendors) it is recommended to prefix the attribute name by your company's recommended to prefix the new name by your company's reverse domain name, e.g.
reverse domain name, e.g. `com.acme.shopname`. `com.acme.shopname`.
- The attribute is specific to your application that will be used internally - The name is specific to your application that will be used internally only. If
only. If you already have an internal company process that helps you to ensure you already have an internal company process that helps you to ensure no name
no name clashes happen then feel free to follow it. Otherwise it is clashes happen then feel free to follow it. Otherwise it is recommended to
recommended to prefix the attribute name by your application name, provided prefix the attribute name or label key by your application name, provided that
that the application name is reasonably unique within your organization (e.g. the application name is reasonably unique within your organization (e.g.
`myuniquemapapp.longitude` is likely fine). Make sure the application name `myuniquemapapp.longitude` is likely fine). Make sure the application name
does not clash with an existing semantic convention namespace. does not clash with an existing semantic convention namespace.
- The attribute may be generally applicable to applications in the industry. In - The name may be generally applicable to applications in the industry. In that
that case consider submitting a proposal to this specification to add a new case consider submitting a proposal to this specification to add a new name to
attribute to the semantic conventions, if necessary also to add a new the semantic conventions, and if necessary also to add a new namespace.
namespace for the attribute.
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 (more precisely to
[U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters) [U+0021 .. U+007E](https://en.wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters)
subset of Unicode code points). subset of Unicode code points).