Add system-specific naming guidance (#1708)
Co-authored-by: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com>
This commit is contained in:
Liudmila Molkova
GitHub
parent
607a441b25
commit
7d8f29d80e
|
|
@ -0,0 +1,4 @@
|
|||
change_type: enhancement
|
||||
component: docs
|
||||
note: Document system-specific naming conventions
|
||||
issues: [608, 1494, 1708]
|
||||
|
|
@ -12,20 +12,28 @@ aliases: [attribute-naming]
|
|||
<!-- 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)
|
||||
- [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)
|
||||
- [otel.\* namespace](#otel-namespace)
|
||||
- [Attribute name pluralization guidelines](#attribute-name-pluralization-guidelines)
|
||||
- [Signal-specific attributes](#signal-specific-attributes)
|
||||
- [System-specific attributes](#system-specific-attributes)
|
||||
- [Metrics](#metrics)
|
||||
- [Naming Rules for Counters and UpDownCounters](#naming-rules-for-counters-and-updowncounters)
|
||||
- [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)
|
||||
- [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)
|
||||
- [Client and server metrics](#client-and-server-metrics)
|
||||
- [System-specific naming](#system-specific-naming)
|
||||
- [System (project/product/provider) name attribute](#system-projectproductprovider-name-attribute)
|
||||
- [Choosing a system name](#choosing-a-system-name)
|
||||
- [System-specific attributes](#system-specific-attributes-1)
|
||||
- [System-specific metrics](#system-specific-metrics)
|
||||
- [Known exceptions](#known-exceptions)
|
||||
|
||||
<!-- tocstop -->
|
||||
|
||||
|
|
@ -84,7 +92,7 @@ Names SHOULD follow these rules:
|
|||
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
|
||||
## Name abbreviation guidelines
|
||||
|
||||
Abbreviations MAY be used when they are widely recognized and commonly used.
|
||||
|
||||
|
|
@ -100,7 +108,7 @@ 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
|
||||
## 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.
|
||||
|
|
@ -109,7 +117,7 @@ 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
|
||||
## 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
|
||||
|
|
@ -134,7 +142,7 @@ no longer recommended, it SHOULD be deprecated.
|
|||
> 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
|
||||
## 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).
|
||||
|
|
@ -173,7 +181,7 @@ subset of Unicode code points).
|
|||
|
||||
## Attributes
|
||||
|
||||
### otel.\* Namespace
|
||||
### otel.\* namespace
|
||||
|
||||
Attribute names that start with `otel.` are reserved to be defined by
|
||||
OpenTelemetry specification. These are typically used to express OpenTelemetry
|
||||
|
|
@ -187,7 +195,7 @@ and protocols.
|
|||
Any additions to the `otel.*` namespace MUST be approved as part of
|
||||
OpenTelemetry specification.
|
||||
|
||||
### Attribute Name Pluralization Guidelines
|
||||
### Attribute name pluralization guidelines
|
||||
|
||||
- When an attribute represents a single entity, the attribute name SHOULD be
|
||||
singular. Examples: `host.name`, `container.id`.
|
||||
|
|
@ -200,7 +208,7 @@ OpenTelemetry specification.
|
|||
[Name Pluralization Guidelines](./naming.md#pluralization) SHOULD be
|
||||
followed for the attribute name.
|
||||
|
||||
### Signal-specific Attributes
|
||||
### Signal-specific attributes
|
||||
|
||||
**Status**: [Development][DocumentStatus]
|
||||
|
||||
|
|
@ -226,11 +234,37 @@ Examples:
|
|||
Metric `http.server.request.duration` uses attributes from the registry such as
|
||||
`server.port`, `error.type`.
|
||||
|
||||
### System-specific attributes
|
||||
|
||||
**Status**: [Development][DocumentStatus]
|
||||
|
||||
When an attribute is specific to a particular system (e.g., project, provider, product),
|
||||
the system name should be used in the attribute name, following the pattern:
|
||||
`{optional domain}.{system}.*.{property}` pattern.
|
||||
|
||||
Examples:
|
||||
|
||||
- `db.cassandra.consistency_level` - Describes the consistency level property
|
||||
specific to the Cassandra database.
|
||||
- `aws.s3.key` - Refers to the `key` property of the AWS S3 product.
|
||||
- `signalr.connection.status` – Indicates the connection status of the SignalR
|
||||
network protocol. In this case, no domain is included.
|
||||
|
||||
Semantic conventions for a specific domain are generally applicable to multiple systems.
|
||||
These conventions should define an attribute to represent the name of the system.
|
||||
For example, database conventions include the `db.system.name` attribute.
|
||||
|
||||
The name of the system used in the corresponding attribute should match the name
|
||||
used inside system-specific attributes.
|
||||
|
||||
For example, if the database name specified in `db.system.name` is `foo.bar`, system-specific
|
||||
attributes for this database should follow the `db.foo.bar.*` pattern.
|
||||
|
||||
## Metrics
|
||||
|
||||
**Status**: [Development][DocumentStatus]
|
||||
|
||||
### Naming Rules for Counters and UpDownCounters
|
||||
### Naming rules for counters and UpDownCounters
|
||||
|
||||
#### Pluralization
|
||||
|
||||
|
|
@ -249,7 +283,7 @@ 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
|
||||
#### 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).
|
||||
|
|
@ -258,7 +292,7 @@ For example if we have a namespace `system.process` which contains all metrics r
|
|||
to the processes then to represent the count of the processes we can have a metric named
|
||||
`system.process.count`.
|
||||
|
||||
#### Do Not Use `total`
|
||||
#### Do not use `total`
|
||||
|
||||
UpDownCounters SHOULD NOT use `_total` because then they will look like
|
||||
monotonic sums.
|
||||
|
|
@ -266,7 +300,7 @@ monotonic sums.
|
|||
Counters SHOULD NOT append `_total` either because then their meaning will
|
||||
be confusing in delta backends.
|
||||
|
||||
### Instrument Naming
|
||||
### Instrument naming
|
||||
|
||||
**Status**: [Development][DocumentStatus]
|
||||
|
||||
|
|
@ -313,4 +347,114 @@ 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.
|
||||
|
||||
### Client and server metrics
|
||||
|
||||
Metrics that measure some aspect of a physical or logical network call SHOULD include
|
||||
an indication of which side the metric is being recorded from.
|
||||
|
||||
Such metrics SHOULD follow the `{area}.{client|server}.{metric_name}`
|
||||
pattern if the communication side is ambiguous for a given `{area}` and `{metric_name}`.
|
||||
Otherwise, when the communication side can be inferred from the given `{area}` or
|
||||
`{metric_name}`, the `{area}.{metric_name}` pattern SHOULD be used.
|
||||
|
||||
Examples:
|
||||
|
||||
- `http.client.request.duration`
|
||||
- `gen_ai.server.request.duration`
|
||||
- `messaging.client.sent.messages`
|
||||
- `messaging.process.duration` - the term `process` clearly indicates that
|
||||
the metric is reported by the consumer.
|
||||
- `kestrel.connection.duration` - here, `kestrel` is the name of the web server,
|
||||
so no additional indication is necessary.
|
||||
|
||||
## System-specific naming
|
||||
|
||||
**Status**: [Development][DocumentStatus]
|
||||
|
||||
### System (project/product/provider) name attribute
|
||||
|
||||
Semantic conventions for a certain area are usually applicable to multiple systems
|
||||
(projects, providers, products).
|
||||
|
||||
For example, database semantic conventions can be used to describe telemetry for a
|
||||
broad range of database systems.
|
||||
|
||||
Such conventions SHOULD define an attribute to represent the system name following
|
||||
`{area}.system|provider|protocol.name` pattern.
|
||||
|
||||
For example, database conventions include the `db.system.name` attribute.
|
||||
|
||||
### Choosing a system name
|
||||
|
||||
When adding new a system to the semantic conventions, follow these principles in descending order of priority:
|
||||
|
||||
1. The system name SHOULD adhere to the general attribute naming guidelines outlined in this document,
|
||||
as it will be used as a namespace in [system-specific attribute names](#system-specific-attributes).
|
||||
|
||||
2. The system name SHOULD unambiguously identify this specific product or project.
|
||||
|
||||
For example, use `gcp.pubsub` or `oracle.db`. Avoid generic names like `pubsub`,
|
||||
which could refer to multiple messaging products, or `oracle` which could refer to
|
||||
multiple Oracle products.
|
||||
|
||||
3. The system name SHOULD match the corresponding project or product name in the following cases:
|
||||
|
||||
- Independent projects that do not belong to a specific company, such as Apache Foundation projects like
|
||||
`kafka` or `cassandra`.
|
||||
- Products with names similar to the owning company, such as `mongodb` or `elasticsearch`
|
||||
- Widely recognized products that are popular outside their company's ecosystem.
|
||||
These products often have trademarks without the company name and have
|
||||
their own top-level domain (e.g. `spring` or `mysql`).
|
||||
|
||||
4. In other cases, the system name SHOULD be prefixed with the company (organization,
|
||||
division, or group) name. For cloud services, the name SHOULD use the
|
||||
corresponding cloud provider name. For example, use `aws.dynamodb` or `azure.cosmosdb`.
|
||||
|
||||
The company (organization, division, or group) name SHOULD remain consistent
|
||||
across multiple product names in different semantic convention areas.
|
||||
|
||||
### System-specific attributes
|
||||
|
||||
When an attribute is specific to a particular system (project, provider, product),
|
||||
the corresponding attribute name SHOULD start with the system name following the
|
||||
`{system_name}.*.{property}` pattern.
|
||||
|
||||
Examples:
|
||||
|
||||
- `cassandra.consistency.level` - Describes the consistency level property
|
||||
specific to the Cassandra database.
|
||||
- `aws.s3.key` - Refers to the `key` property of the AWS S3 product.
|
||||
- `signalr.connection.status` – Indicates the connection status of the SignalR
|
||||
network protocol.
|
||||
|
||||
The value of the [`*.system.name`](#system-projectproductprovider-name-attribute) (or similar)
|
||||
attribute MUST match the root namespace used in the system specific attribute being defined.
|
||||
|
||||
For example, both `cassandra.consistency.level` attribute name and `db.system.name=cassandra`
|
||||
use the same system name (`cassandra`).
|
||||
|
||||
### System-specific metrics
|
||||
|
||||
When a metric is specific to a system (project, provider, product),
|
||||
the corresponding instrument name SHOULD start with the system name following the
|
||||
`{system_name}.*.{metric_name}` pattern.
|
||||
|
||||
For example, `azure.cosmosdb.client.operation.request_charge`
|
||||
|
||||
The value of the [`*.system.name`](#system-projectproductprovider-name-attribute) (or similar)
|
||||
attribute MUST match system specific metric namespace.
|
||||
|
||||
For example, both the `azure.cosmosdb.client.operation.request_charge` metric and the `db.system.name=azure.cosmosdb`
|
||||
attribute use the same system name (`azure.cosmosdb`).
|
||||
|
||||
### Known exceptions
|
||||
|
||||
- Operational system and process-related attributes and metrics [follow a
|
||||
pattern](/docs/system/system-metrics.md#systemos---os-specific-system-metrics)
|
||||
of `system.{os}` and `process.{os}`. <!-- TODO: document why-->
|
||||
|
||||
- [RPC](/docs/rpc/README.md), [messaging](/docs/messaging/README.md), and
|
||||
[GenAI](/docs/gen-ai/README.md) semantic conventions don't follow the
|
||||
system-specific naming guidance yet, and will be updated one-by-one.
|
||||
|
||||
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
|
||||
|
|
|
|||
Loading…
Reference in New Issue