clarify how to collect host.id for non-containerized systems (open-te…

…lemetry#3173)

CHANGELOG.md

@@ -25,6 +25,9 @@ release.
 
 ### Resource
 
+- Clarify how to collect `host.id` for non-containerized systems.
+  ([#3173](https://github.com/open-telemetry/opentelemetry-specification/pull/3173))
+
 ### Semantic Conventions
 
 - Move X-Ray Env Variable propagation to span link instead of parent for AWS Lambda.

semantic_conventions/resource/host.yaml

@@ -9,7 +9,8 @@ groups:
         type: string
         brief: >
           Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider.
-          For non-containerized Linux systems, the `machine-id` located in `/etc/machine-id` or `/var/lib/dbus/machine-id` may be used.
+          For non-containerized systems, this should be the `machine-id`. See the table below for
+          the sources to use to determine the `machine-id` based on operating system.
         examples: ['fdbf79e8af94cb7f9e8df36789187052']
       - id: name
         type: string

specification/resource/semantic_conventions/host.md

@@ -9,7 +9,7 @@
 <!-- semconv host -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
-| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized Linux systems, the `machine-id` located in `/etc/machine-id` or `/var/lib/dbus/machine-id` may be used. | `fdbf79e8af94cb7f9e8df36789187052` | Recommended |
+| `host.id` | string | Unique host ID. For Cloud, this must be the instance_id assigned by the cloud provider. For non-containerized systems, this should be the `machine-id`. See the table below for the sources to use to determine the `machine-id` based on operating system. | `fdbf79e8af94cb7f9e8df36789187052` | Recommended |
 | `host.name` | string | Name of the host. On Unix systems, it may contain what the hostname command returns, or the fully qualified hostname, or another name specified by the user. | `opentelemetry-test` | Recommended |
 | `host.type` | string | Type of host. For Cloud, this must be the machine type. | `n1-standard-1` | Recommended |
 | `host.arch` | string | The CPU architecture the host system is running on. | `amd64` | Recommended |
@@ -30,3 +30,29 @@
 | `s390x` | IBM z/Architecture |
 | `x86` | 32-bit x86 |
 <!-- endsemconv -->
+
+## Collecting host.id from non-containerized systems
+
+### Non-privileged Machine ID Lookup
+
+When collecting `host.id` for non-containerized systems non-privileged lookups
+of the machine id are preferred. SDK detector implementations MUST use the
+sources listed below to obtain the machine id.
+
+| OS      | Primary                                                                             | Fallback                               |
+|---------|-------------------------------------------------------------------------------------|----------------------------------------|
+| Linux   | contents of `/etc/machine-id`                                                       | contents of `/var/lib/dbus/machine-id` |
+| BSD     | contents of `/etc/hostid`                                                           | output of `kenv -q smbios.system.uuid` |
+| MacOS   | `IOPlatformUUID` line from the output of `ioreg -rd1 -c "IOPlatformExpertDevice"`   | -                                      |
+| Windows | `MachineGuid` from registry `HKEY_LOCAL_MACHINE\\SOFTWARE\\Microsoft\\Cryptography` | -                                      |
+
+### Privileged Machine ID Lookup
+
+The `host.id` can be looked up using privileged sources. For example, Linux
+systems can use the output of `dmidecode -t system`, `dmidecode -t baseboard`,
+`dmidecode -t chassis`, or read the corresponding data from the filesystem
+(e.g. `cat /sys/devices/virtual/dmi/id/product_id`,
+`cat /sys/devices/virtual/dmi/id/product_uuid`, etc), however, SDK resource
+detector implementations MUST not collect `host.id` from privileged sources. If
+privileged lookup of `host.id` is required, the value should be injected via the
+`OTEL_RESOURCE_ATTRIBUTES` environment variable.