Add system-specific naming guidance

.chloggen/1708.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: docs
+note: Document system-specific naming conventions
+issues: [608, 1494, 1708]

docs/general/naming.md

@@ -22,6 +22,12 @@
     - [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)
+  - [System-specific Metrics](#system-specific-metrics)
 
 <!-- tocstop -->
 
@@ -224,7 +230,7 @@ Metric `http.server.request.duration` uses attributes from the registry such as
 
 ## Metrics
 
-**Status**: [Experimental][DocumentStatus]
+**Status**: [Development][DocumentStatus]
 
 ### Naming Rules for Counters and UpDownCounters
 
@@ -309,4 +315,104 @@ 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 the side metric being recorded.
+
+Such metrics SHOULD follow the `{area}.{client|server}.{metric_name}`
+pattern if communication side is ambiguous for given `{area}` and `{metric_name}`.
+Otherwise, when a specific communication side is implied by 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 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 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 system name should be included in the instrument 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`).
+
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status