From 76cf4ab23ba08d0e1828387ef7fee2b04943218f Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Wed, 13 Sep 2023 14:34:12 +0300 Subject: [PATCH 1/6] Document the difference between host and system metrics Signed-off-by: ChrsMark --- docs/resource/host.md | 2 ++ docs/system/system-metrics.md | 5 +++++ 2 files changed, 7 insertions(+) diff --git a/docs/resource/host.md b/docs/resource/host.md index 150755dc19..d9bfb655e2 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -6,6 +6,8 @@ **Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. +Note that `host.*` namespace should only be used for resource attributes. For hosts' metrics the `system.*` namespace should be used. + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index f17b799050..6a9a859bdc 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -11,6 +11,11 @@ metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. +Note that `system.*` namespace should only be used for hosts' metrics. +For resource attributes related to a host the `host.*` namespace should be used. +The `system.*` namespace for metrics should be used only when the metrics are collected from within the target system. +For metrics collected centrally which are related to known entities like containers the respective namespace should be used. + From 2a84cda88d87a3229d920b4e589d977b7e863cd1 Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Tue, 19 Sep 2023 13:27:22 +0300 Subject: [PATCH 2/6] Update docs/resource/host.md Co-authored-by: Joao Grassi --- docs/resource/host.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/resource/host.md b/docs/resource/host.md index d9bfb655e2..bdba59a2d2 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -6,7 +6,7 @@ **Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. -Note that `host.*` namespace should only be used for resource attributes. For hosts' metrics the `system.*` namespace should be used. +The `host.*` namespace should be exclusively used to capture resource attributes. To report host metrics, use the `system.*` namespace should be used. | Attribute | Type | Description | Examples | Requirement Level | From ac139c761172feb96cc002be58cced40352867cd Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Tue, 19 Sep 2023 13:27:30 +0300 Subject: [PATCH 3/6] Update docs/system/system-metrics.md Co-authored-by: Joao Grassi --- docs/system/system-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 6a9a859bdc..09e87127b9 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -11,7 +11,7 @@ metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. -Note that `system.*` namespace should only be used for hosts' metrics. +The `system.*` namespace should be exclusively used to report hosts' metrics. For resource attributes related to a host the `host.*` namespace should be used. The `system.*` namespace for metrics should be used only when the metrics are collected from within the target system. For metrics collected centrally which are related to known entities like containers the respective namespace should be used. From 88ebceff14276f848313106e57e2ea8fb059631b Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Tue, 19 Sep 2023 13:42:07 +0300 Subject: [PATCH 4/6] Review changes Signed-off-by: ChrsMark --- docs/resource/host.md | 3 ++- docs/system/system-metrics.md | 6 +++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/resource/host.md b/docs/resource/host.md index bdba59a2d2..52bf401eea 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -6,7 +6,8 @@ **Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. -The `host.*` namespace should be exclusively used to capture resource attributes. To report host metrics, use the `system.*` namespace should be used. +The `host.*` namespace SHOULD be exclusively used to capture resource attributes. +To report host metrics, the `system.*` namespace SHOULD be used. | Attribute | Type | Description | Examples | Requirement Level | diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 09e87127b9..755e559e4b 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -11,10 +11,10 @@ metrics in OpenTelemetry. Consider the [general metric semantic conventions](/docs/general/metrics.md#general-metric-semantic-conventions) when creating instruments not explicitly defined in the specification. -The `system.*` namespace should be exclusively used to report hosts' metrics. +The `system.*` namespace SHOULD be exclusively used to report hosts' metrics. +The `system.*` namespace SHOULD only be used when the metrics are collected from within the target system. (physical servers, virtual machines etc). +For metrics collected specifically for known entities (e.g., containers, pods etc), the metrics should be reported in the entity's respective namespace (container.*). For resource attributes related to a host the `host.*` namespace should be used. -The `system.*` namespace for metrics should be used only when the metrics are collected from within the target system. -For metrics collected centrally which are related to known entities like containers the respective namespace should be used. From 12ad001c18c71b3a2c8dfd8f8a808662151584c2 Mon Sep 17 00:00:00 2001 From: ChrsMark Date: Wed, 20 Sep 2023 13:41:51 +0300 Subject: [PATCH 5/6] Improve wording about tech specific metrics Signed-off-by: ChrsMark --- docs/resource/host.md | 2 +- docs/system/system-metrics.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/resource/host.md b/docs/resource/host.md index 52bf401eea..7469f8f40f 100644 --- a/docs/resource/host.md +++ b/docs/resource/host.md @@ -6,7 +6,7 @@ **Description:** A host is defined as a computing instance. For example, physical servers, virtual machines, switches or disk array. -The `host.*` namespace SHOULD be exclusively used to capture resource attributes. +The `host.*` namespace SHOULD be exclusively used to capture resource attributes. To report host metrics, the `system.*` namespace SHOULD be used. diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 755e559e4b..111e8a4715 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -13,7 +13,8 @@ instruments not explicitly defined in the specification. The `system.*` namespace SHOULD be exclusively used to report hosts' metrics. The `system.*` namespace SHOULD only be used when the metrics are collected from within the target system. (physical servers, virtual machines etc). -For metrics collected specifically for known entities (e.g., containers, pods etc), the metrics should be reported in the entity's respective namespace (container.*). +Metrics collected from technology-specific, well-defined APIs (e.g. Kubelet's API or container runtimes) +should be reported under their respective namespace (e.g. k8s.*, container.*). For resource attributes related to a host the `host.*` namespace should be used. From de28506b02deb276085a5baacd017cae1fbec57c Mon Sep 17 00:00:00 2001 From: Chris Mark Date: Wed, 20 Sep 2023 17:30:44 +0300 Subject: [PATCH 6/6] Update docs/system/system-metrics.md Co-authored-by: Joao Grassi --- docs/system/system-metrics.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md index 111e8a4715..72acc1091e 100644 --- a/docs/system/system-metrics.md +++ b/docs/system/system-metrics.md @@ -15,7 +15,7 @@ The `system.*` namespace SHOULD be exclusively used to report hosts' metrics. The `system.*` namespace SHOULD only be used when the metrics are collected from within the target system. (physical servers, virtual machines etc). Metrics collected from technology-specific, well-defined APIs (e.g. Kubelet's API or container runtimes) should be reported under their respective namespace (e.g. k8s.*, container.*). -For resource attributes related to a host the `host.*` namespace should be used. +Resource attributes related to a host, SHOULD be reported under the `host.*` namespace.