From 33ba1bd689135cfd2b397475d471400a490ade41 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 20 Dec 2024 16:47:20 -0800 Subject: [PATCH 1/8] Add system-specific naming guidance --- docs/general/naming.md | 68 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 65 insertions(+), 3 deletions(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index 62921a4ae9..1ef93bbb15 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -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) @@ -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 + 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. + + +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 @@ -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. @@ -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` + + +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 From a85fe7e0b032ef465a1d1cb363ca2224201388f9 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 8 Jan 2025 16:44:57 -0800 Subject: [PATCH 2/8] simplify guidance and cleanup --- docs/general/naming.md | 62 ++++++++++++++++++++++++------------------ 1 file changed, 35 insertions(+), 27 deletions(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index 1ef93bbb15..f098f2dc22 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -225,33 +225,41 @@ Examples: Metric `http.server.request.duration` uses attributes from the registry such as `server.port`, `error.type`. +### Attributes that describe system name + +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|etc.name`. + +For example, database conventions include the `db.system.name` attribute. + + ### 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. +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: -- `db.cassandra.consistency_level` - Describes the consistency level property +- `cassandra.consistency_level` - Describes the consistency level property 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. - + network protocol. -The name of the system used in the corresponding `*.system` (or similar) attribute should match -the name used inside system-specific attributes. +The value of the [`*.system.name`](#attributes-that-describe-system-name) (or similar) +attribute MUST match the root namespace used in the system specific attribute being defined. -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. +For example, both `cassandra.consistency_level` attribute name and `db.system.name=cassandra` + use the same system name (`cassandra`). ## Metrics @@ -340,12 +348,12 @@ 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 +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}`. +Metric names SHOULD follow the `{area}.{client|server}.{metric_name}` pattern. -For example: +Examples: - `http.client.request.duration` - `gen_ai.server.request.duration` - `messaging.client.sent.messages` @@ -356,19 +364,19 @@ For example: ### 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. +When a metric is specific to a system (project, provider, product) in a given area, +the system name should be included in the instrument name following the +`{system_name}.*.{metric_name}` pattern. -For example, `db.client.cosmosdb.operation.request_charge` +For example, `cosmosdb.client.operation.request_charge` + -The system name should match the value of the corresponding `{domain}.system` -attribute. -For additional details, refer to [system-specific attributes](#system-specific-attributes). +The value of the [`*.system.name`](#attributes-that-describe-system-name) (or similar) +attribute MUST match the root namespace used in system specific metric. -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`. +For example, both `cosmosdb.client.operation.request_charge` metric and `db.system.name=cosmosdb` +attribute use the same system name (`cosmosdb`). [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From e30d4b35a908bbe23d0dadae1d2d6dfb9d973062 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 16 Jan 2025 18:27:45 -0800 Subject: [PATCH 3/8] update system name guidance --- docs/general/naming.md | 132 ++++++++++++++++++++++++++--------------- 1 file changed, 84 insertions(+), 48 deletions(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index f098f2dc22..5e899f242a 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -16,15 +16,18 @@ - [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) + - [Client and Server Metrics](#client-and-server-metrics) +- [System-specific naming](#system-specific-naming) + - [System (project/product/provider) name](#system-projectproductprovider-name) + - [Choosing a System Name](#choosing-a-system-name) + - [System-specific Attributes](#system-specific-attributes) + - [System-specific Metrics](#system-specific-metrics) @@ -225,42 +228,6 @@ Examples: Metric `http.server.request.duration` uses attributes from the registry such as `server.port`, `error.type`. -### Attributes that describe system name - -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|etc.name`. - -For example, database conventions include the `db.system.name` attribute. - - -### System-specific attributes - -**Status**: [Development][DocumentStatus] - -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`](#attributes-that-describe-system-name) (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`). - ## Metrics **Status**: [Development][DocumentStatus] @@ -346,12 +313,15 @@ 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 +### 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. +Metrics that measure some aspect of a physical or logical network calls SHOULD include +an indication of the side metric being recorded. -Metric names SHOULD follow the `{area}.{client|server}.{metric_name}` pattern. +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` @@ -362,21 +332,87 @@ Examples: - `kestrel.connection.duration` - here, `kestrel` is the name of the web server, so no additional indication is necessary. -### System-specific metrics +## System-specific naming + +**Status**: [Development][DocumentStatus] + +### System (project/product/provider) name + +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 name, 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 lacks specificity. + +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 may have + their own top-level domain (e.g. `spring` or `mysql`). + +3. 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 prefix. For example, use `ibm.db2` or `aws.dynamodb`. + + The company (organization, division, or group) naming 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`](#attributes-that-describe-system-name) (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) in a given area, the system name should be included in the instrument name following the `{system_name}.*.{metric_name}` pattern. -For example, `cosmosdb.client.operation.request_charge` +For example, `azure.cosmosdb.client.operation.request_charge` The value of the [`*.system.name`](#attributes-that-describe-system-name) (or similar) -attribute MUST match the root namespace used in system specific metric. +attribute MUST match system specific metric namespace. -For example, both `cosmosdb.client.operation.request_charge` metric and `db.system.name=cosmosdb` -attribute use the same system name (`cosmosdb`). +For example, both `azure.cosmosdb.client.operation.request_charge` metric and `db.system.name=azure.cosmosdb` +attribute use the same system name (`azure.cosmosdb`). [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status From 057789f4d6ebc07fb6fc0bab8f1eb441da66d6d0 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 16 Jan 2025 18:34:15 -0800 Subject: [PATCH 4/8] nits --- docs/general/naming.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index 5e899f242a..41309b7721 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -24,7 +24,7 @@ - [Instrument Naming](#instrument-naming) - [Client and Server Metrics](#client-and-server-metrics) - [System-specific naming](#system-specific-naming) - - [System (project/product/provider) name](#system-projectproductprovider-name) + - [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) @@ -270,6 +270,8 @@ 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. @@ -336,7 +338,7 @@ Examples: **Status**: [Development][DocumentStatus] -### System (project/product/provider) name +### System (project/product/provider) name attribute Semantic conventions for a certain area are usually applicable to multiple systems (projects, providers, products). @@ -352,7 +354,7 @@ For example, database conventions include the `db.system.name` attribute. ### Choosing a System Name -When adding new system name, follow these principles in descending order of priority: +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). @@ -368,14 +370,14 @@ When adding new system name, follow these principles in descending order of prio `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 may have + These products often have trademarks without the company name and have their own top-level domain (e.g. `spring` or `mysql`). 3. 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 prefix. For example, use `ibm.db2` or `aws.dynamodb`. + corresponding cloud provider name. For example, use `ibm.db2` or `aws.dynamodb`. - The company (organization, division, or group) naming SHOULD remain consistent + The company (organization, division, or group) name SHOULD remain consistent across multiple product names in different semantic convention areas. ### System-specific Attributes From f97485c5de91504b5978c5e921c612521532c8ee Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 17 Jan 2025 10:43:51 -0800 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Trask Stalnaker --- docs/general/naming.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index 41309b7721..32a53a3267 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -317,7 +317,7 @@ 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 calls SHOULD include +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}` @@ -362,7 +362,8 @@ When adding new system to the semantic conventions, follow these principles in d 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 lacks specificity. + 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: @@ -375,7 +376,7 @@ When adding new system to the semantic conventions, follow these principles in d 3. 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 `ibm.db2` or `aws.dynamodb`. + 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. @@ -402,11 +403,11 @@ For example, both `cassandra.consistency.level` attribute name and `db.system.na ### System-specific Metrics -When a metric is specific to a system (project, provider, product) in a given area, +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` +For example, `azure.cosmosdb.client.operation.request.charge` @@ -414,7 +415,7 @@ For example, `azure.cosmosdb.client.operation.request_charge` The value of the [`*.system.name`](#attributes-that-describe-system-name) (or similar) attribute MUST match system specific metric namespace. -For example, both `azure.cosmosdb.client.operation.request_charge` metric and `db.system.name=azure.cosmosdb` +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 From e1a5c2879159b945371c3f5fc2c914c03639ece9 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 17 Jan 2025 11:19:32 -0800 Subject: [PATCH 6/8] lint --- .chloggen/1708.yaml | 4 ++++ docs/general/naming.md | 6 +++--- 2 files changed, 7 insertions(+), 3 deletions(-) create mode 100644 .chloggen/1708.yaml diff --git a/.chloggen/1708.yaml b/.chloggen/1708.yaml new file mode 100644 index 0000000000..f897baceb4 --- /dev/null +++ b/.chloggen/1708.yaml @@ -0,0 +1,4 @@ +change_type: enhancement +component: docs +note: Document system-specific naming conventions +issues: [608, 1494, 1708] diff --git a/docs/general/naming.md b/docs/general/naming.md index 32a53a3267..53af73e988 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -395,7 +395,7 @@ Examples: - `signalr.connection.status` – Indicates the connection status of the SignalR network protocol. -The value of the [`*.system.name`](#attributes-that-describe-system-name) (or similar) +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` @@ -412,10 +412,10 @@ For example, `azure.cosmosdb.client.operation.request.charge` -The value of the [`*.system.name`](#attributes-that-describe-system-name) (or similar) +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` +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 From eca5c5580b4379b98f1c83698ea2dd9e645476fe Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 17 Jan 2025 11:30:15 -0800 Subject: [PATCH 7/8] lint --- docs/general/naming.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index 53af73e988..46784bd33a 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -326,6 +326,7 @@ 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` @@ -374,7 +375,7 @@ When adding new system to the semantic conventions, follow these principles in d These products often have trademarks without the company name and have their own top-level domain (e.g. `spring` or `mysql`). -3. In other cases, the system name SHOULD be prefixed with the company (organization, +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`. From c4b43a6305f8432fb67e24c49ccc3b46218b577f Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 24 Jan 2025 15:15:48 -0800 Subject: [PATCH 8/8] remove todos --- docs/general/naming.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/docs/general/naming.md b/docs/general/naming.md index 46784bd33a..6cda817489 100644 --- a/docs/general/naming.md +++ b/docs/general/naming.md @@ -351,7 +351,6 @@ 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 @@ -408,15 +407,12 @@ 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` - - - +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` +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