Refactor and update naming guidance (#1694)
Co-authored-by: Trask Stalnaker <trask.stalnaker@gmail.com>
This commit is contained in:
Liudmila Molkova
GitHub
parent
0d843e4cb8
commit
56bec66129
|
|
@ -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]
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -1,177 +0,0 @@
|
|||
# Attribute Naming
|
||||
|
||||
**Status**: [Stable][DocumentStatus]
|
||||
|
||||
<details>
|
||||
<summary>Table of Contents</summary>
|
||||
|
||||
<!-- toc -->
|
||||
|
||||
- [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)
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
</details>
|
||||
|
||||
_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](<https://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).
|
||||
|
||||
> 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](<https://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.
|
||||
|
||||
[DocumentStatus]:
|
||||
https://opentelemetry.io/docs/specs/otel/document-status
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -10,15 +10,7 @@ aliases: [metrics-general]
|
|||
<!-- toc -->
|
||||
|
||||
- [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]
|
||||
|
|
|
|||
|
|
@ -0,0 +1,312 @@
|
|||
# Naming
|
||||
|
||||
**Status**: [Stable][DocumentStatus], Unless otherwise specified.
|
||||
|
||||
<details>
|
||||
<summary>Table of Contents</summary>
|
||||
|
||||
<!-- toc -->
|
||||
|
||||
- [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)
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
</details>
|
||||
|
||||
## 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](<https://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).
|
||||
|
||||
> 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](<https://wikipedia.org/wiki/Basic_Latin_(Unicode_block)#Table_of_characters>)
|
||||
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
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue