Document the difference between a host and a system metric

[frzifus]

This issue is intended to discuss the difference between the host and system namespace. The outcome should be a clear description of when which ns is used.

This question was raised during the Aug 2, 2023, 08:30 PT SIG MTG and needs to be answered to continue on this PR.

[mx-psi]

cc @ChrsMark

[trask]

just in case it helps, there was a somewhat related prior discussion here: open-telemetry/opentelemetry-specification#2388

[ChrsMark]

Thanks for filing this @frzifus @mx-psi !

I think that we need to decide to only use one namespace for all the related metrics coming from the system/host. Either it is host.* or system.*.

Based on the discussion that @trask indicated, I think that it makes sense to use the system.* namespace in general for everything that is collected from the system level directly. This means that either I report metrics from within a bare metal host or a container/vm, from the collection point of view that's the observed system level.

[ChrsMark]

We had a discussion about this during the August 30th System Semantic Convention WG meeting. The main points were the following:

1. Keep using host.* namespace for resource attributes like host.id, host.name etc. This means that the PR which only adds "static" host's resource attributes is good to go from this perspective.
2. For metrics we can keep using the system.* namespace whenever we collect metrics from the system directly.
3. For centralized metrics that are collected from outside of the resource's scope (ie container metrics collected centrally for a k8s cluster) we can use resource specific namespace like for example container.*, pod.*, vm.*, instance.* etc. Containers, VMs etc are actually processes for a bare metal host similarly to what a jvm process is. This is also explained at Add container metrics fields from ECS #87 (comment) and aligns with Add system metrics clarification around containers opentelemetry-specification#2388 (comment).

@mx-psi @dmitryax @kaiyan-sheng @AlexanderWert feel free to correct me if I miss anything here from what we discussed. If we agree on this we can maybe transfer this conclusion somewhere for future reference (and then close this issue).

cc: @trask

[mx-psi]

Thanks for the summary @ChrsMark! I think there is agreement within the System semantic conventions WG. Given there has not been any disagreement voiced on this issue, I think we can open a PR to put this in writing somewhere: for (1) and (2) maybe on the README.md of the relevant folders on this repository, while I am not sure as to where to put (3)

[ChrsMark]

Thanks @mx-psi ! I can try to consolidate (1) and (2) in https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/host.md and then (2) and (3) (rephrased) in https://github.com/open-telemetry/semantic-conventions/blob/main/docs/system/system-metrics.md.

For (2) and (3) we want something similar to https://github.com/open-telemetry/opentelemetry-specification/pull/2388/files#diff-48ed2e166c485f6f64a1a78251b07248e74e9c2a41cfe24e2950b07a5db196b2R10-R13 which was closed. Actually what we propose here is exactly the opposite with the content of that PR but aligns with open-telemetry/opentelemetry-specification#2388 (comment).

@trask if you have any suggestions or thoughts on this please let us know :).

[ChrsMark]

@frzifus @mx-psi since #324 was merged I guess we can close this one?