Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add system-specific naming guidance #1708

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+65 −3
Open

Add system-specific naming guidance #1708

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 65 additions & 3 deletions docs/general/naming.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,15 @@
- [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)
- [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)
- [Client and server metrics](#client-and-server-metrics)
- [System-specific metrics](#system-specific-metrics)

<!-- tocstop -->

Expand Down Expand Up @@ -222,9 +225,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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to https://github.com/open-telemetry/semantic-conventions/pull/1708/files#r1894523030

what's the benefit of having db in front of cassandra here? why not cassandra.consistency_level?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's say we have some redis-specific attributes (and redis can be used as a DB and as a messaging system), would we define db.redis and messaging.redis ? probably not, it should be just redis.

specific to the Cassandra database.
Cassandra DB.
- `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` attribute.
<!-- update when https://github.com/open-telemetry/semantic-conventions/pull/1613 is merged -->

The name of the system used in the corresponding `*.system` (or similar) attribute should match
the name used inside system-specific attributes.

For example, if the database name specified in `db.system` is `foo.bar`, system-specific
attributes for this database should follow the `db.foo.bar.*` pattern.

## Metrics

**Status**: [Experimental][DocumentStatus]
**Status**: [Development][DocumentStatus]

### Naming Rules for Counters and UpDownCounters

Expand Down Expand Up @@ -264,8 +295,6 @@ 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.
Expand Down Expand Up @@ -309,4 +338,37 @@ 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 aspects of a physical or logical network call should include
an indication of the side being measured when ambiguity exists.

In such cases, the metric name should follow the pattern: `{domain}.{client|server}.{metric_name}`.

For example:
- `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 metrics

When a metric is specific to a system (e.g., project, provider, product) in a given domain,
the system name should be included in the instrument name using the pattern:
`{domain}.{client|server}.{system}.*.{property}` pattern.

For example, `db.client.cosmosdb.operation.request_charge`
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the difference with signalr.server.connection.duration below makes me think if we should simplify it and do cosmosdb.client.operation.request_charge. What's the benefit of having db in front of it?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

summoning @open-telemetry/semconv-system-approvers

It's the same question as for system.linux vs linux metrics in #1403 or #1618


<!-- update when https://github.com/open-telemetry/semantic-conventions/pull/1613 is merged -->
The system name should match the value of the corresponding `{domain}.system`
attribute.

For additional details, refer to [system-specific attributes](#system-specific-attributes).

If a metric does not belong to any domain, use the system name at the start of the instrument name.
For example, `signalr.server.connection.duration`.

[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
Loading