From 6cd950c8bff70261bafcb8d5ed18469171ec2b48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 21:12:56 +0100 Subject: [PATCH 1/5] Change the definition of `device.id` --- docs/attributes-registry/device.md | 16 ++++++++++++++-- docs/resource/device.md | 28 ++++++++++++++++++++-------- model/device/registry.yaml | 29 ++++++++++++++++++----------- model/device/resources.yaml | 3 ++- 4 files changed, 54 insertions(+), 22 deletions(-) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index 59d1d5cc92..de29a3ccd9 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -9,12 +9,24 @@ Describes device attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Development](https://img.shields.io/badge/-development-blue) | +| `device.id` | string | A unique identifier representing the device [1] | `123456789012345`; `01:23:45:67:89:AB` | ![Development](https://img.shields.io/badge/-development-blue) | | `device.manufacturer` | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | ![Development](https://img.shields.io/badge/-development-blue) | | `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | ![Development](https://img.shields.io/badge/-development-blue) | | `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | ![Development](https://img.shields.io/badge/-development-blue) | -**[1] `device.id`:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. +**[1] `device.id`:** **The `device.id` SHOULD NOT be used in most user-facing applications due to privacy regulations. +Consequently, instrumentations that provide it MUST provide it as an opt-in feature.** + +Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. +However, it might be resettable by the user for all apps on a device. +Hardware IDs (e.g. vendor-specific serial number, IMEI or MAC address) MIGHT be used as values. + +More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + +> [!WARNING] +> +> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. +> See [`installation.id`](/docs/attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. **[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. diff --git a/docs/resource/device.md b/docs/resource/device.md index 5e3d2cb2c8..1be2c1bbbd 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -16,18 +16,30 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`device.id`](/docs/attributes-registry/device.md) | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`device.manufacturer`](/docs/attributes-registry/device.md) | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | -| [`device.model.name`](/docs/attributes-registry/device.md) | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`device.manufacturer`](/docs/attributes-registry/device.md) | string | The name of the device manufacturer [1] | `Apple`; `Samsung` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`device.model.name`](/docs/attributes-registry/device.md) | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| [`device.id`](/docs/attributes-registry/device.md) | string | A unique identifier representing the device [4] | `123456789012345`; `01:23:45:67:89:AB` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) | -**[1] `device.id`:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. +**[1] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. -**[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. +**[2] `device.model.identifier`:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device. -**[3] `device.model.identifier`:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device. +**[3] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. -**[4] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. +**[4] `device.id`:** **The `device.id` SHOULD NOT be used in most user-facing applications due to privacy regulations. +Consequently, instrumentations that provide it MUST provide it as an opt-in feature.** + +Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. +However, it might be resettable by the user for all apps on a device. +Hardware IDs (e.g. vendor-specific serial number, IMEI or MAC address) MIGHT be used as values. + +More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + +> [!WARNING] +> +> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. +> See [`installation.id`](/docs/attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. diff --git a/model/device/registry.yaml b/model/device/registry.yaml index bfd8795be8..f540a89b46 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -3,23 +3,30 @@ groups: type: attribute_group display_name: Device Attributes brief: > - Describes device attributes. + Describes device attributes. attributes: - id: device.id type: string stability: development brief: > A unique identifier representing the device - note: > - The device identifier MUST only be defined using the values outlined below. This value is not an advertising - identifier and MUST NOT be used as such. - On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). - On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique - UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) - on best practices and exact implementation details. - Caution should be taken when storing personal data or anything which can identify a user. GDPR and - data protection laws may apply, ensure you do your own due diligence. - examples: ['2ab2916d-a51f-4ac8-80ee-45ac31a28092'] + note: | + **The `device.id` SHOULD NOT be used in most user-facing applications due to privacy regulations. + Consequently, instrumentations that provide it MUST provide it as an opt-in feature.** + + Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. + However, it might be resettable by the user for all apps on a device. + Hardware IDs (e.g. vendor-specific serial number, IMEI or MAC address) MIGHT be used as values. + + More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + + > [!WARNING] + > + > This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. + > See [`installation.id`](/docs/attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. + examples: + - '123456789012345' + - 01:23:45:67:89:AB - id: device.manufacturer type: string stability: development diff --git a/model/device/resources.yaml b/model/device/resources.yaml index 8f54124e54..b9f8621f3f 100644 --- a/model/device/resources.yaml +++ b/model/device/resources.yaml @@ -4,9 +4,10 @@ groups: stability: development name: device brief: > - The device on which the process represented by this resource is running. + The device on which the process represented by this resource is running. attributes: - ref: device.id + requirement_level: opt_in - ref: device.manufacturer - ref: device.model.identifier - ref: device.model.name From b0ee7d3b16caa6b6710638dbf685f1f95705b04d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 21:23:57 +0100 Subject: [PATCH 2/5] Add changelog entry --- .chloggen/1951.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .chloggen/1951.yaml diff --git a/.chloggen/1951.yaml b/.chloggen/1951.yaml new file mode 100644 index 0000000000..1ad29aed93 --- /dev/null +++ b/.chloggen/1951.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: breaking + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: device + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Change the definition of `device.id` and make it opt-in. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1874, 1951] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: From f6f5fabcd161f5fe94775a3ca3b28a91ba029144 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 21:33:20 +0100 Subject: [PATCH 3/5] Fix reference to app.installation.id --- model/device/registry.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/model/device/registry.yaml b/model/device/registry.yaml index f540a89b46..1a89b910a0 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -23,7 +23,7 @@ groups: > [!WARNING] > > This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. - > See [`installation.id`](/docs/attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. + > See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) as a more privacy-preserving alternative. examples: - '123456789012345' - 01:23:45:67:89:AB From fc5e3b2bddfedd3f126b170d9867577b0009ce42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 21:42:32 +0100 Subject: [PATCH 4/5] Resolve CI issues --- docs/attributes-registry/device.md | 5 +++-- docs/resource/device.md | 5 +++-- model/device/registry.yaml | 3 ++- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index de29a3ccd9..1c3530666e 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -25,8 +25,9 @@ More information about Android identifier best practices can be found [here](htt > [!WARNING] > -> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. -> See [`installation.id`](/docs/attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. +> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, +> ensure you do your own due diligence. +> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) as a more privacy-preserving alternative. **[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. diff --git a/docs/resource/device.md b/docs/resource/device.md index 1be2c1bbbd..87f9437703 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -38,8 +38,9 @@ More information about Android identifier best practices can be found [here](htt > [!WARNING] > -> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. -> See [`installation.id`](/docs/attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. +> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, +> ensure you do your own due diligence. +> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) as a more privacy-preserving alternative. diff --git a/model/device/registry.yaml b/model/device/registry.yaml index 1a89b910a0..6622d0d788 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -22,7 +22,8 @@ groups: > [!WARNING] > - > This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence. + > This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, + > ensure you do your own due diligence. > See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) as a more privacy-preserving alternative. examples: - '123456789012345' From bd41e6641d16923bb171e3de9b5aac65cc77f4bf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Tue, 18 Mar 2025 21:40:08 +0100 Subject: [PATCH 5/5] Rephrase disclaimer --- docs/attributes-registry/device.md | 14 ++++++++------ docs/resource/device.md | 14 ++++++++------ model/device/registry.yaml | 12 +++++++----- 3 files changed, 23 insertions(+), 17 deletions(-) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index 1c3530666e..f91f2a1e98 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -14,10 +14,7 @@ Describes device attributes. | `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | ![Development](https://img.shields.io/badge/-development-blue) | | `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | ![Development](https://img.shields.io/badge/-development-blue) | -**[1] `device.id`:** **The `device.id` SHOULD NOT be used in most user-facing applications due to privacy regulations. -Consequently, instrumentations that provide it MUST provide it as an opt-in feature.** - -Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. +**[1] `device.id`:** Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. However, it might be resettable by the user for all apps on a device. Hardware IDs (e.g. vendor-specific serial number, IMEI or MAC address) MIGHT be used as values. @@ -25,9 +22,14 @@ More information about Android identifier best practices can be found [here](htt > [!WARNING] > -> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, +> This attribute may contain sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, > ensure you do your own due diligence. -> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) as a more privacy-preserving alternative. +> +> Due to these reasons, this identifier is not recommended for consumer applications and will likely result in rejection from both Google Play and App Store. +> However, it may be appropriate for specific enterprise scenarios, such as kiosk devices or enterprise-managed devices, with appropriate compliance clearance. +> Any instrumentation providing this identifier MUST implement it as an opt-in feature. +> +> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) for a more privacy-preserving alternative. **[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`. diff --git a/docs/resource/device.md b/docs/resource/device.md index 87f9437703..89c20e256d 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -27,10 +27,7 @@ **[3] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. -**[4] `device.id`:** **The `device.id` SHOULD NOT be used in most user-facing applications due to privacy regulations. -Consequently, instrumentations that provide it MUST provide it as an opt-in feature.** - -Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. +**[4] `device.id`:** Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. However, it might be resettable by the user for all apps on a device. Hardware IDs (e.g. vendor-specific serial number, IMEI or MAC address) MIGHT be used as values. @@ -38,9 +35,14 @@ More information about Android identifier best practices can be found [here](htt > [!WARNING] > -> This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, +> This attribute may contain sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, > ensure you do your own due diligence. -> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) as a more privacy-preserving alternative. +> +> Due to these reasons, this identifier is not recommended for consumer applications and will likely result in rejection from both Google Play and App Store. +> However, it may be appropriate for specific enterprise scenarios, such as kiosk devices or enterprise-managed devices, with appropriate compliance clearance. +> Any instrumentation providing this identifier MUST implement it as an opt-in feature. +> +> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) for a more privacy-preserving alternative. diff --git a/model/device/registry.yaml b/model/device/registry.yaml index 6622d0d788..33e543aa1f 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -11,9 +11,6 @@ groups: brief: > A unique identifier representing the device note: | - **The `device.id` SHOULD NOT be used in most user-facing applications due to privacy regulations. - Consequently, instrumentations that provide it MUST provide it as an opt-in feature.** - Its value SHOULD be identical for all apps on a device and it SHOULD NOT change if an app is uninstalled and re-installed. However, it might be resettable by the user for all apps on a device. Hardware IDs (e.g. vendor-specific serial number, IMEI or MAC address) MIGHT be used as values. @@ -22,9 +19,14 @@ groups: > [!WARNING] > - > This attribute contains sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, + > This attribute may contain sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, > ensure you do your own due diligence. - > See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) as a more privacy-preserving alternative. + > + > Due to these reasons, this identifier is not recommended for consumer applications and will likely result in rejection from both Google Play and App Store. + > However, it may be appropriate for specific enterprise scenarios, such as kiosk devices or enterprise-managed devices, with appropriate compliance clearance. + > Any instrumentation providing this identifier MUST implement it as an opt-in feature. + > + > See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) for a more privacy-preserving alternative. examples: - '123456789012345' - 01:23:45:67:89:AB