diff --git a/CHANGELOG.md b/CHANGELOG.md index 172c3722e0c..298a2f6b4f9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,9 @@ release. ### Resource +- Clarify how to collect `host.id` for non-containerized systems. + ([#0]()) + ### Semantic Conventions - Enable semantic convention tooling for metrics in spec diff --git a/semantic_conventions/resource/host.yaml b/semantic_conventions/resource/host.yaml index cdf361a4e5f..c5bfa4399bf 100644 --- a/semantic_conventions/resource/host.yaml +++ b/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 diff --git a/specification/resource/semantic_conventions/host.md b/specification/resource/semantic_conventions/host.md index c993d099148..26bccee22eb 100644 --- a/specification/resource/semantic_conventions/host.md +++ b/specification/resource/semantic_conventions/host.md @@ -9,7 +9,7 @@ | 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 | + +## 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 `/var/lib/dbus/machine-id` | contents of `/etc/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 such as the output of +`dmidecode -t system`, `dmidecode -t baseboard`, `dmidecode -t chassis`, or +reading 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. \ No newline at end of file