From 770d3b580d15079eb2aafd9c6a04649c84e3faed Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 29 Feb 2024 13:17:40 +0100 Subject: [PATCH 1/8] Clarify metric attribute must be namespaced --- docs/general/metrics.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 74699fbad0..f2bcbfc5a2 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -89,6 +89,28 @@ 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 MUST follow the general [attribute naming rules](attribute-naming.md). +In particular, metric attributes MUST have a namespace. + +Metric attributes SHOULD be added under the metric namespace when their usage and +semantics are exclusive to the metric. + +Examples: + +Metric `system.filesystem.usage` with attributes `mode` and `mountpoint` +should be namespace as: `system.filesystem.mode` and `system.filesystem.mountpoint`. + +When metric attributes apply to other signals, these do not need +to be namespace under the metric and SHOULD be added to the +[attributes registry](../attributes-registry/README.md). + +Examples: + +Metric `http.server.request.duration` uses attributes from the registry such as +`server.port`, `error.type` + ### Units Conventional metrics or metrics that have their units included in From 168b7e1e17852484dea4e7fa847963e71e6ff1da Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 29 Feb 2024 13:54:16 +0100 Subject: [PATCH 2/8] Fix toc --- docs/general/metrics.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index f2bcbfc5a2..4ffd2631a1 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -11,6 +11,7 @@ aliases: [docs/specs/semconv/general/metrics-general] - [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) From da813601b45bae6d585ecd24552ed31a7fc204ea Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Fri, 1 Mar 2024 11:39:22 +0100 Subject: [PATCH 3/8] PR suggestions --- .chloggen/clarify-metric-namespace.yaml | 5 +++++ docs/general/metrics.md | 8 ++++---- 2 files changed, 9 insertions(+), 4 deletions(-) create mode 100755 .chloggen/clarify-metric-namespace.yaml diff --git a/.chloggen/clarify-metric-namespace.yaml b/.chloggen/clarify-metric-namespace.yaml new file mode 100755 index 0000000000..7fffee1683 --- /dev/null +++ b/.chloggen/clarify-metric-namespace.yaml @@ -0,0 +1,5 @@ +change_type: 'enhancement' +component: metrics +note: Clarify metric attributes should be namespaced. +issues: [394] +subtext: diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 4ffd2631a1..5afda24451 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -92,7 +92,7 @@ old metric names in rename operations). ### Metric attributes -Metric attributes MUST follow the general [attribute naming rules](attribute-naming.md). +Metric attributes SHOULD follow the general [attribute naming rules](attribute-naming.md). In particular, metric attributes MUST have a namespace. Metric attributes SHOULD be added under the metric namespace when their usage and @@ -100,8 +100,8 @@ semantics are exclusive to the metric. Examples: -Metric `system.filesystem.usage` with attributes `mode` and `mountpoint` -should be namespace as: `system.filesystem.mode` and `system.filesystem.mountpoint`. +Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` +should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. When metric attributes apply to other signals, these do not need to be namespace under the metric and SHOULD be added to the @@ -110,7 +110,7 @@ to be namespace under the metric and SHOULD be added to the Examples: Metric `http.server.request.duration` uses attributes from the registry such as -`server.port`, `error.type` +`server.port`, `error.type`. ### Units From ea85b40d4e0bb0bc8fac7ebb53be6077c5ac35cd Mon Sep 17 00:00:00 2001 From: Armin Ruech <7052238+arminru@users.noreply.github.com> Date: Mon, 4 Mar 2024 18:42:20 +0100 Subject: [PATCH 4/8] Fix typo Co-authored-by: Chris Mark --- docs/general/metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 5afda24451..a1281fbf6f 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -104,7 +104,7 @@ Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. When metric attributes apply to other signals, these do not need -to be namespace under the metric and SHOULD be added to the +to be namespaced under the metric and SHOULD be added to the [attributes registry](../attributes-registry/README.md). Examples: From e8c31c011c0a4c90651d86494b2b30f5f4b60d10 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Wed, 6 Mar 2024 11:37:37 +0100 Subject: [PATCH 5/8] Remove paragraph about attributes should be in the registry --- docs/general/metrics.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 9597ce396b..5763ff4d89 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -103,9 +103,8 @@ Examples: Attributes `mode` and `mountpoint` for metric `system.filesystem.usage` should be namespaced as `system.filesystem.mode` and `system.filesystem.mountpoint`. -When metric attributes apply to other signals, these do not need -to be namespaced under the metric and SHOULD be added to the -[attributes registry](../attributes-registry/README.md). +Metrics can also have attributes outside the metric namespace when these come +from the attributes registry. Examples: From 6152a9ed192ecbb622286620c2d9c5364abea519 Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 7 Mar 2024 09:42:06 +0100 Subject: [PATCH 6/8] Update docs/general/metrics.md Co-authored-by: Liudmila Molkova --- docs/general/metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 5763ff4d89..2843fc1cb3 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -93,7 +93,7 @@ old metric names in rename operations). ### Metric attributes Metric attributes SHOULD follow the general [attribute naming rules](attribute-naming.md). -In particular, metric attributes MUST have a namespace. +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. From a48f8585b0edf5be1c7022bd2c801b581fb3fedb Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 7 Mar 2024 09:47:01 +0100 Subject: [PATCH 7/8] PR suggestions --- docs/general/metrics.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 2843fc1cb3..1033744a9e 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -103,8 +103,7 @@ 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 the metric namespace when these come -from the attributes registry. +Metrics can also have attributes outside of its namespace. Examples: From 6f0390e2e517bf7c51d24da0ae0b3b8e7ad649ee Mon Sep 17 00:00:00 2001 From: Joao Grassi <5938087+joaopgrassi@users.noreply.github.com> Date: Thu, 7 Mar 2024 13:04:05 +0100 Subject: [PATCH 8/8] Update docs/general/metrics.md Co-authored-by: Chris Mark --- docs/general/metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 1033744a9e..d76440f253 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -103,7 +103,7 @@ 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 its namespace. +Metrics can also have attributes outside of their namespace. Examples: