From 56bec66129f2c5f805b6f3e5229736dfa1e42f0a Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 18 Dec 2024 19:20:39 -0800 Subject: [PATCH] Refactor and update naming guidance (#1694) Co-authored-by: Trask Stalnaker --- .chloggen/1694.yaml | 8 + CONTRIBUTING.md | 2 +- docs/attributes-registry/README.md | 2 +- docs/general/README.md | 9 - docs/general/attribute-naming.md | 177 ------------- docs/general/events.md | 2 +- docs/general/metrics.md | 146 +---------- docs/general/naming.md | 312 +++++++++++++++++++++++ docs/system/README.md | 2 + model/README.md | 2 +- templates/registry/markdown/readme.md.j2 | 2 +- 11 files changed, 336 insertions(+), 328 deletions(-) create mode 100644 .chloggen/1694.yaml delete mode 100644 docs/general/attribute-naming.md create mode 100644 docs/general/naming.md diff --git a/.chloggen/1694.yaml b/.chloggen/1694.yaml new file mode 100644 index 0000000000..ddf40d60a4 --- /dev/null +++ b/.chloggen/1694.yaml @@ -0,0 +1,8 @@ +change_type: enhancement +component: docs +note: Update attribute, events, and metrics naming guidance to include new best practices. +subtext: | + - Use namespaces (with `.` delimiter) whenever possible. + - Use precise, descriptive, unambiguous names that leave room for expansion. + +issues: [1694] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f764273a9..4cfc04991c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -399,7 +399,7 @@ exists in some form in ECS, consider the following guidelines: data, user issue reports, feature requests, examples of prior work on a different standard or comparable evidence about the alternatives. - When no suitable alternatives are provided, altering an ECS name solely - for the purpose of complying with [Name Pluralization guidelines](docs/general/attribute-naming.md#name-pluralization-guidelines) + for the purpose of complying with [Name Pluralization guidelines](docs/general/naming.md#attribute-name-pluralization-guidelines) MAY BE avoided. - Do not use an existing ECS name as a namespace. If the name must differ, use a different namespace name to avoid clashes or avoid using the namespace diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 91df4271b1..4bfe974911 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -102,4 +102,4 @@ Currently, the following namespaces exist: - [VCS](vcs.md) - [Webengine](webengine.md) -[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers +[developers recommendations]: ../general/naming.md#recommendations-for-application-developers diff --git a/docs/general/README.md b/docs/general/README.md index a4bff5597e..83fd3366cb 100644 --- a/docs/general/README.md +++ b/docs/general/README.md @@ -17,12 +17,3 @@ The following general Semantic Conventions are defined: * [Logs](logs.md): General Semantic Conventions for logs. * [Metrics](metrics.md): General Semantic Conventions for metrics. * [Spans](trace.md): General Semantic Conventions for traces / spans. - -## Event Name Reuse Prohibition - -A new event MUST NOT be added with the same name as an event that existed in -the past but was renamed (with a corresponding schema file). - -When introducing a new event name check all existing schema files to make sure -the name does not appear as a key of any "rename_events" section (keys denote -old event names in rename operations). diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md deleted file mode 100644 index 34e84d2f9d..0000000000 --- a/docs/general/attribute-naming.md +++ /dev/null @@ -1,177 +0,0 @@ -# Attribute Naming - -**Status**: [Stable][DocumentStatus] - -
-Table of Contents - - - -- [Name Pluralization Guidelines](#name-pluralization-guidelines) -- [Name Abbreviation Guidelines](#name-abbreviation-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: - -- Names SHOULD be lowercase. - -- 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`, `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.md#pluralization) SHOULD be - followed for the attribute name. - -## Name Abbreviation Guidelines - -Abbreviations MAY be used when they are widely recognized and commonly used. - -Examples include common technical abbreviations such as `IP`, `DB`, `CPU`, -`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`. - -Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply -to multiple products or concepts. - -## 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](./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]() - 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). - -> Note: -> Semantic Conventions tooling limits names to lowercase -> Latin alphabet, Numeric, Underscore, Dot (as namespace delimiter). -> Names must start with a letter, end with an alphanumeric character, and must not -> contain two or more consecutive delimiters (Underscore or Dot). - -## Recommendations for Application Developers - -As an application developer when you need to record an attribute first consult -existing [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 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]() -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. - -[DocumentStatus]: - https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/general/events.md b/docs/general/events.md index c63aa5904a..4e80862f13 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -31,7 +31,7 @@ structure and semantics will also be defined. ## General event semantics * An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) - that uniquely identifies the event. Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). + that uniquely identifies the event. Event names are subject to the [Naming guidelines](/docs/general/naming.md). * Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the diff --git a/docs/general/metrics.md b/docs/general/metrics.md index fbe38ea7c4..961abaedf4 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -10,15 +10,7 @@ aliases: [metrics-general] - [General Guidelines](#general-guidelines) - - [Name Reuse Prohibition](#name-reuse-prohibition) - - [Metric attributes](#metric-attributes) - [Units](#units) - - [Naming rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) - - [Pluralization](#pluralization) - - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) - - [Do not use `total`](#do-not-use-total) -- [General Metric Semantic Conventions](#general-metric-semantic-conventions) - - [Instrument Naming](#instrument-naming) - [Instrument Units](#instrument-units) - [Instrument Types](#instrument-types) - [Consistent UpDownCounter timeseries](#consistent-updowncounter-timeseries) @@ -30,12 +22,16 @@ The following semantic conventions surrounding metrics are defined: * **[General Guidelines](#general-guidelines): General metrics guidelines.** * [Database](/docs/database/database-metrics.md): For SQL and NoSQL client metrics. * [FaaS](/docs/faas/faas-metrics.md): For [Function as a Service](https://wikipedia.org/wiki/Function_as_a_service) metrics. +* [GenAI](/docs/gen-ai/gen-ai-metrics.md): For Generative AI metrics. * [HTTP](/docs/http/http-metrics.md): For HTTP client and server metrics. * [Messaging](/docs/messaging/messaging-metrics.md): For messaging systems (queues, publish/subscribe, etc.) metrics. * [RPC](/docs/rpc/rpc-metrics.md): For RPC client and server metrics. +* [.NET](/docs/dotnet/README.md): For network-related metrics emitted by .NET runtime components. * **System metrics** * [System](/docs/system/system-metrics.md): For standard system metrics. + * [Container](/docs/system/container-metrics.md) * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. + * [K8s](/docs/system/k8s-metrics.md): For K8s metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. @@ -47,11 +43,8 @@ their own [Resource Semantic Conventions](/docs/resource/README.md). **Status**: [Experimental][DocumentStatus] -Metric names and attributes exist within a single universe and a single -hierarchy. Metric names and attributes MUST be considered within the universe of -all existing metric names. When defining new metric names and attributes, -consider the prior art of existing standard metrics and metrics from -frameworks/libraries. +When defining new metric names and attributes, consider the prior art of +existing standard metrics and metrics from frameworks/libraries. Associated metrics SHOULD be nested together in a hierarchy based on their usage. Define a top-level hierarchy for common metric categories: for OS @@ -78,41 +71,11 @@ where similar metrics have significantly different implementations across the breadth of all existing metrics. For example, every garbage collected runtime has slightly different strategies and measures. Using a single set of metric names for GC, not divided by the runtime, could create dissimilar comparisons -and confusion for end users. (For example, prefer `process.runtime.java.gc*` over -`process.runtime.gc.*`.) Measures of many operating system metrics are similarly +and confusion for end users. (For example, prefer `jvm.gc*` over +`gc.*`.) Measures of many operating system metrics are similarly ambiguous. -Metric names and attributes SHOULD follow the general -[name abbreviation guidelines](attribute-naming.md#name-abbreviation-guidelines). - -### Name Reuse Prohibition - -A new metric MUST NOT be added with the same name as a metric that existed in -the past but was renamed (with a corresponding schema file). - -When introducing a new metric name check all existing schema files to make sure -the name does not appear as a key of any "rename_metrics" section (keys denote -old metric names in rename operations). - -### Metric attributes - -Metric attributes SHOULD follow the general [attribute naming rules](attribute-naming.md). -In particular, metric attributes SHOULD have a namespace. - -Metric attributes SHOULD be added under the metric namespace when their usage and -semantics are exclusive to the metric. - -Examples: - -Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` -should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. - -Metrics can also have attributes outside of their namespace. - -Examples: - -Metric `http.server.request.duration` uses attributes from the registry such as -`server.port`, `error.type`. +Metric names and attributes SHOULD follow the general [naming guidelines](naming.md). ### Units @@ -126,97 +89,6 @@ When building components that interoperate between OpenTelemetry and a system using the OpenMetrics exposition format, use the [OpenMetrics Guidelines](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/compatibility/prometheus_and_openmetrics.md). -### Naming rules for Counters and UpDownCounters - -#### Pluralization - -Metric namespaces SHOULD NOT be pluralized. - -Metric names SHOULD NOT be pluralized, unless the value being recorded -represents discrete instances of a -[countable quantity](https://wikipedia.org/wiki/Count_noun). -Generally, the name SHOULD be pluralized only if the unit of the metric in -question is a non-unit (like `{fault}` or `{operation}`). - -Examples: - -* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time` -should not be pluralized, even if many data points are recorded. -* `system.paging.faults`, `system.disk.operations`, and `system.network.packets` -should be pluralized, even if only a single data point is recorded. - -#### Use `count` Instead of Pluralization for UpDownCounters - -If the value being recorded represents the count of concepts signified -by the namespace then the metric should be named `count` (within its namespace). - -For example if we have a namespace `system.process` which contains all metrics related -to the processes then to represent the count of the processes we can have a metric named -`system.process.count`. - -#### Do not use `total` - -UpDownCounters SHOULD NOT use `_total` because then they will look like -monotonic sums. - -Counters SHOULD NOT append `_total` either because then their meaning will -be confusing in delta backends. - -## General Metric Semantic Conventions - -**Status**: [Mixed][DocumentStatus] - -The following semantic conventions aim to keep naming consistent. They -provide guidelines for most of the cases in this specification and should be -followed for other instruments not explicitly defined in this document. - -### Instrument Naming - -**Status**: [Experimental][DocumentStatus] - -- **limit** - an instrument that measures the constant, known total amount of -something should be called `entity.limit`. For example, `system.memory.limit` -for the total amount of memory on a system. - -- **usage** - an instrument that measures an amount used out of a known total -(**limit**) amount should be called `entity.usage`. For example, -`system.memory.usage` with attribute `state = used | cached | free | ...` for the -amount of memory in a each state. Where appropriate, the sum of **usage** -over all attribute values SHOULD be equal to the **limit**. - - A measure of the amount consumed of an unlimited resource, or of a resource - whose limit is unknowable, is differentiated from **usage**. For example, the - maximum possible amount of virtual memory that a process may consume may - fluctuate over time and is not typically known. - -- **utilization** - an instrument that measures the *fraction* of **usage** -out of its **limit** should be called `entity.utilization`. For example, -`system.memory.utilization` for the fraction of memory in use. Utilization can -be with respect to a fixed limit or a soft limit. Utilization values are -represented as a ratio and are typically in the range `[0, 1]`, but may go above 1 -in case of exceeding a soft limit. - -- **time** - an instrument that measures passage of time should be called -`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user -| system | ...`. **time** measurements are not necessarily wall time and can -be less than or greater than the real wall time between measurements. - - **time** instruments are a special case of **usage** metrics, where the - **limit** can usually be calculated as the sum of **time** over all attribute - values. **utilization** for time instruments can be derived automatically - using metric event timestamps. For example, `system.cpu.utilization` is - defined as the difference in `system.cpu.time` measurements divided by the - elapsed time and number of CPUs. - -- **io** - an instrument that measures bidirectional data flow should be -called `entity.io` and have attributes for direction. For example, -`system.network.io`. - -- Other instruments that do not fit the above descriptions may be named more -freely. For example, `system.paging.faults` and `system.network.packets`. -Units do not need to be specified in the names since they are included during -instrument creation, but can be added if there is ambiguity. - ### Instrument Units **Status**: [Stable][DocumentStatus] diff --git a/docs/general/naming.md b/docs/general/naming.md new file mode 100644 index 0000000000..51b04cd7af --- /dev/null +++ b/docs/general/naming.md @@ -0,0 +1,312 @@ +# Naming + +**Status**: [Stable][DocumentStatus], Unless otherwise specified. + +
+Table of Contents + + + +- [General Naming Considerations](#general-naming-considerations) +- [Name Abbreviation Guidelines](#name-abbreviation-guidelines) +- [Name Reuse Prohibition](#name-reuse-prohibition) +- [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) +- [Recommendations for Application Developers](#recommendations-for-application-developers) +- [Attributes](#attributes) + - [otel.\* Namespace](#otel-namespace) + - [Attribute Name Pluralization Guidelines](#attribute-name-pluralization-guidelines) + - [Signal-specific Attributes](#signal-specific-attributes) +- [Metrics](#metrics) + - [Naming Rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters) + - [Pluralization](#pluralization) + - [Use `count` Instead of Pluralization for UpDownCounters](#use-count-instead-of-pluralization-for-updowncounters) + - [Do Not Use `total`](#do-not-use-total) + - [Instrument Naming](#instrument-naming) + + + +
+ +## General Naming Considerations + +_This section applies to attribute names (also +known as the "attribute keys"), as well as Metric and Event names. For brevity +within this section when we use the term "name" without an adjective it is +implied to mean all of these._ + +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: + +- Names SHOULD be lowercase. + +- Use namespacing. 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. + + Use namespaces (and dot separator) whenever it makes sense. For example + when introducing an attribute representing a property of some object, follow + `*{object}.{property}` pattern. Avoid using underscore (`*{object}_{property}`) + if this object could have other properties. + +- For each multi-word dot-delimited component of the 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. + + Use underscore only when using dot (namespacing) does not make sense or changes + the semantic meaning of the name. For example, use `rate_limiting` + instead of `rate.limiting`. + +- Be precise. Attribute, event, metric, and other names should be descriptive and + unambiguous. + - When introducing a name describing a certain property of the object, + include the property name. For example, use `file.owner.name` instead of `file.owner` + and `system.network.packet.dropped` instead of `system.network.dropped` + - Avoid introducing names and namespaces that would mean different things when + used by different conventions or instrumentations. For example, use `security_rule` + instead of `rule`. + +- Use shorter names when it does not compromise clarity. Drop namespace + components or words in multi-word components when they are not necessary. For example, + `vcs.change.id` describes pull request id as precisely as `vcs.repository.change.id` does. + +## Name Abbreviation Guidelines + +Abbreviations MAY be used when they are widely recognized and commonly used. + +Examples include common technical abbreviations such as `IP`, `DB`, `CPU`, +`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`. + +Abbreviations that are commonly recognized but only within a certain domain MAY +be used when qualified by the corresponding namespace. + +For example, use `container.csi.*` instead of `container.container_storage_interface` +or `container.oci.*` instead of `container.open_container_initiative.*` + +Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply +to multiple products or concepts. + +## Name Reuse Prohibition + +Two attributes, two metrics, or two events MUST NOT share the same name. +Different entities (attribute and metric, metric and event) MAY share the same name. + +Attributes, metrics, and events SHOULD NOT be removed from semantic +conventions regardless of their maturity level. When the convention is renamed or +no longer recommended, it SHOULD be deprecated. + +## Recommendations for OpenTelemetry Authors + +- When coming up with a new semantic convention make sure to check existing + namespaces ([Semantic Conventions](/docs/README.md)) to see if a similar namespace + already exists. + +- All names that are part of OpenTelemetry semantic conventions SHOULD be part + of a namespace. + +- 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 names to printable Basic Latin characters + (more precisely to + [U+0021 .. U+007E]() + 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). + +> Note: +> Semantic Conventions tooling limits names to lowercase +> Latin alphabet, Numeric, Underscore, Dot (as namespace delimiter). +> Names must start with a letter, end with an alphanumeric character, and must not +> contain two or more consecutive delimiters (Underscore or Dot). + +## Recommendations for Application Developers + +As an application developer when you need to record an attribute, metric, event, or +other signal first consult existing [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 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]() +subset of Unicode code points). + +## Attributes + +### 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. + +### Attribute Name Pluralization Guidelines + +- When an attribute represents a single entity, the attribute name SHOULD be + singular. Examples: `host.name`, `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.md#pluralization) SHOULD be + followed for the attribute name. + +### Signal-specific Attributes + +**Status**: [Experimental][DocumentStatus] + +Attributes are defined in semantic conventions in a signal-agnostic way. The same attribute +is expected to be used on multiple signals. + +When an attribute is defined, it is not always clear if it will be applicable outside +of a certain metric, event, or other convention. + +Attributes that are unlikely to have any usage beyond a specific convention, +SHOULD be added under that metric (event, etc) namespace. + +Examples: + +Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` +should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. + +Metrics, events, resources, and other signals are expected and encouraged to use +applicable attributes from multiple namespaces. + +Examples: + +Metric `http.server.request.duration` uses attributes from the registry such as +`server.port`, `error.type`. + +## Metrics + +**Status**: [Experimental][DocumentStatus] + +### Naming Rules for Counters and UpDownCounters + +#### Pluralization + +Metric namespaces SHOULD NOT be pluralized. + +Metric names SHOULD NOT be pluralized, unless the value being recorded +represents discrete instances of a +[countable quantity](https://wikipedia.org/wiki/Count_noun). +Generally, the name SHOULD be pluralized only if the unit of the metric in +question is a non-unit (like `{fault}` or `{operation}`). + +Examples: + +* `system.filesystem.utilization`, `http.server.request.duration`, and `system.cpu.time` +should not be pluralized, even if many data points are recorded. +* `system.paging.faults`, `system.disk.operations`, and `system.network.packets` +should be pluralized, even if only a single data point is recorded. + +#### Use `count` Instead of Pluralization for UpDownCounters + +If the value being recorded represents the count of concepts signified +by the namespace then the metric should be named `count` (within its namespace). + +For example if we have a namespace `system.process` which contains all metrics related +to the processes then to represent the count of the processes we can have a metric named +`system.process.count`. + +#### Do Not Use `total` + +UpDownCounters SHOULD NOT use `_total` because then they will look like +monotonic sums. + +Counters SHOULD NOT append `_total` either because then their meaning will +be confusing in delta backends. + +### Instrument Naming + +**Status**: [Experimental][DocumentStatus] + +- **limit** - an instrument that measures the constant, known total amount of +something should be called `entity.limit`. For example, `system.memory.limit` +for the total amount of memory on a system. + +- **usage** - an instrument that measures an amount used out of a known total +(**limit**) amount should be called `entity.usage`. For example, +`system.memory.usage` with attribute `state = used | cached | free | ...` for the +amount of memory in a each state. Where appropriate, the sum of **usage** +over all attribute values SHOULD be equal to the **limit**. + + A measure of the amount consumed of an unlimited resource, or of a resource + whose limit is unknowable, is differentiated from **usage**. For example, the + maximum possible amount of virtual memory that a process may consume may + fluctuate over time and is not typically known. + +- **utilization** - an instrument that measures the _fraction_ of **usage** +out of its **limit** should be called `entity.utilization`. For example, +`system.memory.utilization` for the fraction of memory in use. Utilization can +be with respect to a fixed limit or a soft limit. Utilization values are +represented as a ratio and are typically in the range `[0, 1]`, but may go above 1 +in case of exceeding a soft limit. + +- **time** - an instrument that measures passage of time should be called +`entity.time`. For example, `system.cpu.time` with attribute `state = idle | user +| system | ...`. **time** measurements are not necessarily wall time and can +be less than or greater than the real wall time between measurements. + + **time** instruments are a special case of **usage** metrics, where the + **limit** can usually be calculated as the sum of **time** over all attribute + values. **utilization** for time instruments can be derived automatically + using metric event timestamps. For example, `system.cpu.utilization` is + defined as the difference in `system.cpu.time` measurements divided by the + elapsed time and number of CPUs. + +- **io** - an instrument that measures bidirectional data flow should be +called `entity.io` and have attributes for direction. For example, +`system.network.io`. + +- Other instruments that do not fit the above descriptions may be named more +freely. For example, `system.paging.faults` and `system.network.packets`. +Units do not need to be specified in the names since they are included during +instrument creation, but can be added if there is ambiguity. + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/system/README.md b/docs/system/README.md index dc6b643b5d..61c332a22b 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -14,6 +14,8 @@ This document defines semantic conventions for systems (such as processes, runti System semantic conventions are defined for the following metrics: * [System](system-metrics.md): For standard system metrics. +* [Container](container-metrics.md): For container-related metrics. +* [K8s](k8s-metrics.md): For K8s-related metrics. * [Hardware](hardware-metrics.md): For hardware-related metrics. * [Process](process-metrics.md): For standard process metrics. * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. diff --git a/model/README.md b/model/README.md index ce6fb75e93..821423416e 100644 --- a/model/README.md +++ b/model/README.md @@ -10,7 +10,7 @@ the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions Semantic conventions for the spec MUST adhere to the -[attribute naming](../docs/general/attribute-naming.md), +[naming](../docs/general/naming.md), [attribute requirement level](../docs/general/attribute-requirement-level.md), and [metric requirement level](../docs/general/metric-requirement-level.md) conventions. diff --git a/templates/registry/markdown/readme.md.j2 b/templates/registry/markdown/readme.md.j2 index 14438da535..1767f38b2e 100644 --- a/templates/registry/markdown/readme.md.j2 +++ b/templates/registry/markdown/readme.md.j2 @@ -36,5 +36,5 @@ Currently, the following namespaces exist: {%- set my_file_name = bundle.id | kebab_case ~ ".md" -%} - [{{ bundle.id | title_case | acronym }}]({{ my_file_name }}) {% endfor %} -[developers recommendations]: ../general/attribute-naming.md#recommendations-for-application-developers +[developers recommendations]: ../general/naming.md#recommendations-for-application-developers