From 517633738ece6e74aabf976bfaeb968967604797 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Mon, 10 Feb 2025 12:15:20 +0100 Subject: [PATCH 01/23] Create installation.id, redefine device.id --- .github/CODEOWNERS | 1 + docs/attributes-registry/README.md | 1 + docs/attributes-registry/device.md | 17 ++++++++-- docs/attributes-registry/installation.md | 36 ++++++++++++++++++++ docs/resource/device.md | 29 +++++++++++----- model/device/registry.yaml | 31 +++++++++++------ model/device/resources.yaml | 3 +- model/installation/registry.yaml | 43 ++++++++++++++++++++++++ model/installation/resources.yaml | 9 +++++ 9 files changed, 148 insertions(+), 22 deletions(-) create mode 100644 docs/attributes-registry/installation.md create mode 100644 model/installation/registry.yaml create mode 100644 model/installation/resources.yaml diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index ff2381b5fd..8fdbbf4281 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -57,6 +57,7 @@ # Mobile semantic conventions /docs/mobile/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers /model/device/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers +/model/installation/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers # K8s semantic conventions /docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 629a46c242..faac759362 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -72,6 +72,7 @@ Currently, the following namespaces exist: - [Heroku](heroku.md) - [Host](host.md) - [HTTP](http.md) +- [Installation](installation.md) - [iOS](ios.md) - [JVM](jvm.md) - [K8s](k8s.md) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index ef05d41af1..3481152edf 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -9,12 +9,25 @@ Describes device attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `device.id` | string | A unique identifier representing the device [1] | `my_vendor:1234567890`; `imei:123456789012345`; `mac:01:23:45:67:89:AB` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `device.manufacturer` | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `device.model.identifier` | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | ![Experimental](https://img.shields.io/badge/-experimental-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 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. +The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). + +More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + +> [!WARNING] +> +> 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`](../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/attributes-registry/installation.md b/docs/attributes-registry/installation.md new file mode 100644 index 0000000000..34e2ff1a35 --- /dev/null +++ b/docs/attributes-registry/installation.md @@ -0,0 +1,36 @@ + + + +# Installation + +## Installation Attributes + +Describes installation attributes. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `identifier_for_vendor:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `firebase:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `guid:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `app_set_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `android_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `installation.id`:** Its value MUST remain the same between launches of the same installation of an application. +On a particular device it MIGHT be the same across different applications of the same vendor, however, it MUST be different across applications of different vendors. +It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. +Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. +The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). + +On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). + +On Android this value SHOULD be equal to either: + +- [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). +- A globally unique UUID which is persisted across sessions in your application. + +But it MAY be equal to other identifiers such as: + +- [App set ID](https://developer.android.com/identity/app-set-id). +- [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). + +More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + +> [!WARNING] +> +> Caution should be taken when storing personal data or anything which can identify a user. GDPR and laws may apply, ensure you do your own due diligence. diff --git a/docs/resource/device.md b/docs/resource/device.md index 1f5be497cd..c51977b5d5 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -16,18 +16,31 @@ | 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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`device.manufacturer`](/docs/attributes-registry/device.md) | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`device.manufacturer`](/docs/attributes-registry/device.md) | string | The name of the device manufacturer [1] | `Apple`; `Samsung` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`device.id`](/docs/attributes-registry/device.md) | string | A unique identifier representing the device [4] | `my_vendor:1234567890`; `imei:123456789012345`; `mac:01:23:45:67:89:AB` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-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 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. +The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). + +More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + +> [!WARNING] +> +> 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`](../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 6fc25d8f6f..9840931a89 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -3,23 +3,32 @@ groups: type: attribute_group display_name: Device Attributes brief: > - Describes device attributes. + Describes device attributes. attributes: - id: device.id type: string stability: experimental 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 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. + The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). + + More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + + > [!WARNING] + > + > 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`](../attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. + examples: + - my_vendor:1234567890 + - imei:123456789012345 + - mac:01:23:45:67:89:AB - id: device.manufacturer type: string stability: experimental diff --git a/model/device/resources.yaml b/model/device/resources.yaml index bc49bd51b7..a103967c9f 100644 --- a/model/device/resources.yaml +++ b/model/device/resources.yaml @@ -4,9 +4,10 @@ groups: stability: experimental 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 diff --git a/model/installation/registry.yaml b/model/installation/registry.yaml new file mode 100644 index 0000000000..3c7ea837cc --- /dev/null +++ b/model/installation/registry.yaml @@ -0,0 +1,43 @@ +groups: + - id: registry.installation + type: attribute_group + display_name: Installation Attributes + brief: > + Describes installation attributes. + stability: development + attributes: + - id: installation.id + type: string + stability: development + brief: > + A unique identifier representing the installation of an application on a specific device + note: | + Its value MUST remain the same between launches of the same installation of an application. + On a particular device it MIGHT be the same across different applications of the same vendor, however, it MUST be different across applications of different vendors. + It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. + Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. + The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). + + On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). + + On Android this value SHOULD be equal to either: + + - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). + - A globally unique UUID which is persisted across sessions in your application. + + But it MAY be equal to other identifiers such as: + + - [App set ID](https://developer.android.com/identity/app-set-id). + - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). + + More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). + + > [!WARNING] + > + > Caution should be taken when storing personal data or anything which can identify a user. GDPR and laws may apply, ensure you do your own due diligence. + examples: + - identifier_for_vendor:2ab2916d-a51f-4ac8-80ee-45ac31a28092 + - firebase:2ab2916d-a51f-4ac8-80ee-45ac31a28092 + - guid:2ab2916d-a51f-4ac8-80ee-45ac31a28092 + - app_set_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092 + - android_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092 diff --git a/model/installation/resources.yaml b/model/installation/resources.yaml new file mode 100644 index 0000000000..2187257393 --- /dev/null +++ b/model/installation/resources.yaml @@ -0,0 +1,9 @@ +groups: + - id: resource.installation + type: resource + stability: development + name: installation + brief: > + The installation of the application represented by this resource on a specific device. + attributes: + - ref: installation.id From 19974573a9df147115f9ef6dd817219207525185 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Mon, 10 Feb 2025 12:29:12 +0100 Subject: [PATCH 02/23] Add entry to schema-next --- schema-next.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/schema-next.yaml b/schema-next.yaml index 23675166b0..e35ab1a76e 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,6 +2,11 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: + all: + changes: + - rename_attributes: + attribute_map: + device.id: installation.id metrics: changes: - rename_metrics: From 606df0e978fbf29ad36dae83fd7a7c3801e22a38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Mon, 10 Feb 2025 12:32:43 +0100 Subject: [PATCH 03/23] Add changelog entry --- .chloggen/1897.yaml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 .chloggen/1897.yaml diff --git a/.chloggen/1897.yaml b/.chloggen/1897.yaml new file mode 100644 index 0000000000..342f0f8220 --- /dev/null +++ b/.chloggen/1897.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: enhancement + +# 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: Create `installation.id` and change the definition of `device.id` + +# 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, 1897] + +# (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 30f369b4066cd805dea7a2eb060253ab5b9cc95a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Mon, 10 Feb 2025 17:47:56 +0100 Subject: [PATCH 04/23] Update GH templates --- .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 585224e32b..ecd006cd59 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -60,6 +60,7 @@ body: - area:heroku - area:host - area:http + - area:installation - area:jvm - area:k8s - area:linux diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index a04b1977c2..6e2d0ca1b4 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -52,6 +52,7 @@ body: - area:heroku - area:host - area:http + - area:installation - area:jvm - area:k8s - area:linux From 01cb310be13d52169e28dbac995fb8f6c1fc899a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 16 Feb 2025 17:56:57 +0100 Subject: [PATCH 05/23] Improve language, remove same vendor comment --- docs/attributes-registry/device.md | 4 ++-- docs/attributes-registry/installation.md | 1 - docs/resource/device.md | 4 ++-- model/device/registry.yaml | 4 ++-- model/installation/registry.yaml | 1 - 5 files changed, 6 insertions(+), 8 deletions(-) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index 3481152edf..abe42c8fac 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -15,10 +15,10 @@ Describes device attributes. | `device.model.name` | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `device.id`:** **The `device.id` SHOULD NOT be used in most user-facing applications due to privacy regulations. -Consequently, instrumentations MUST provide it as an OPT-IN feature.** +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. +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. The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). diff --git a/docs/attributes-registry/installation.md b/docs/attributes-registry/installation.md index 34e2ff1a35..ee167a8058 100644 --- a/docs/attributes-registry/installation.md +++ b/docs/attributes-registry/installation.md @@ -12,7 +12,6 @@ Describes installation attributes. | `installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `identifier_for_vendor:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `firebase:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `guid:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `app_set_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `android_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1] `installation.id`:** Its value MUST remain the same between launches of the same installation of an application. -On a particular device it MIGHT be the same across different applications of the same vendor, however, it MUST be different across applications of different vendors. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). diff --git a/docs/resource/device.md b/docs/resource/device.md index c51977b5d5..9fd4a8f104 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -28,10 +28,10 @@ **[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 MUST provide it as an OPT-IN feature.** +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. +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. The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). diff --git a/model/device/registry.yaml b/model/device/registry.yaml index 9840931a89..9064f397ba 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -12,10 +12,10 @@ groups: 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 MUST provide it as an OPT-IN feature.** + 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. + 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. The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). diff --git a/model/installation/registry.yaml b/model/installation/registry.yaml index 3c7ea837cc..5e979d0eba 100644 --- a/model/installation/registry.yaml +++ b/model/installation/registry.yaml @@ -13,7 +13,6 @@ groups: A unique identifier representing the installation of an application on a specific device note: | Its value MUST remain the same between launches of the same installation of an application. - On a particular device it MIGHT be the same across different applications of the same vendor, however, it MUST be different across applications of different vendors. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). From be11f0656d2549b5ecf260cb2bac41d87fea4421 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 16 Feb 2025 17:59:38 +0100 Subject: [PATCH 06/23] Relax MUST to SHOULD --- docs/attributes-registry/installation.md | 2 +- model/installation/registry.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/attributes-registry/installation.md b/docs/attributes-registry/installation.md index ee167a8058..9c63edda7d 100644 --- a/docs/attributes-registry/installation.md +++ b/docs/attributes-registry/installation.md @@ -11,7 +11,7 @@ Describes installation attributes. |---|---|---|---|---| | `installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `identifier_for_vendor:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `firebase:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `guid:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `app_set_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `android_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1] `installation.id`:** Its value MUST remain the same between launches of the same installation of an application. +**[1] `installation.id`:** Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). diff --git a/model/installation/registry.yaml b/model/installation/registry.yaml index 5e979d0eba..a439abe6e8 100644 --- a/model/installation/registry.yaml +++ b/model/installation/registry.yaml @@ -12,7 +12,7 @@ groups: brief: > A unique identifier representing the installation of an application on a specific device note: | - Its value MUST remain the same between launches of the same installation of an application. + Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). From bdb3175e3fdb07177a77daade74afdcab661a9db Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 16 Feb 2025 18:17:19 +0100 Subject: [PATCH 07/23] Improve language --- docs/attributes-registry/installation.md | 2 +- model/installation/registry.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/attributes-registry/installation.md b/docs/attributes-registry/installation.md index 9c63edda7d..f8ee3e87f1 100644 --- a/docs/attributes-registry/installation.md +++ b/docs/attributes-registry/installation.md @@ -14,7 +14,7 @@ Describes installation attributes. **[1] `installation.id`:** Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. -The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). +The `installation.id` value SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). diff --git a/model/installation/registry.yaml b/model/installation/registry.yaml index a439abe6e8..7e538f00b6 100644 --- a/model/installation/registry.yaml +++ b/model/installation/registry.yaml @@ -15,7 +15,7 @@ groups: Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. - The `installation.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). + The `installation.id` value SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). From 9aa23c77791911ed658bbab8ba4d283c3cff746e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 16 Feb 2025 18:29:03 +0100 Subject: [PATCH 08/23] Remove PII notice from installation.id --- docs/attributes-registry/installation.md | 4 ---- model/installation/registry.yaml | 4 ---- 2 files changed, 8 deletions(-) diff --git a/docs/attributes-registry/installation.md b/docs/attributes-registry/installation.md index f8ee3e87f1..1c9d901fc6 100644 --- a/docs/attributes-registry/installation.md +++ b/docs/attributes-registry/installation.md @@ -29,7 +29,3 @@ But it MAY be equal to other identifiers such as: - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). - -> [!WARNING] -> -> Caution should be taken when storing personal data or anything which can identify a user. GDPR and laws may apply, ensure you do your own due diligence. diff --git a/model/installation/registry.yaml b/model/installation/registry.yaml index 7e538f00b6..4fb6df0229 100644 --- a/model/installation/registry.yaml +++ b/model/installation/registry.yaml @@ -30,10 +30,6 @@ groups: - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). - - > [!WARNING] - > - > Caution should be taken when storing personal data or anything which can identify a user. GDPR and laws may apply, ensure you do your own due diligence. examples: - identifier_for_vendor:2ab2916d-a51f-4ac8-80ee-45ac31a28092 - firebase:2ab2916d-a51f-4ac8-80ee-45ac31a28092 From 1661c606b446b922de6b0c548c09d13b472d203a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 16 Feb 2025 18:34:17 +0100 Subject: [PATCH 09/23] Revert schema-next.yaml change --- schema-next.yaml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/schema-next.yaml b/schema-next.yaml index e35ab1a76e..23675166b0 100644 --- a/schema-next.yaml +++ b/schema-next.yaml @@ -2,11 +2,6 @@ file_format: 1.1.0 schema_url: https://opentelemetry.io/schemas/next versions: next: - all: - changes: - - rename_attributes: - attribute_map: - device.id: installation.id metrics: changes: - rename_metrics: From be512a12f2756e3334c6e716c3c2745ab26f1095 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 16 Feb 2025 18:35:04 +0100 Subject: [PATCH 10/23] Explicitly point out PII information --- docs/attributes-registry/device.md | 2 +- docs/resource/device.md | 2 +- model/device/registry.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index abe42c8fac..e5e705d0be 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -26,7 +26,7 @@ More information about Android identifier best practices can be found [here](htt > [!WARNING] > -> 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 [`installation.id`](../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 9fd4a8f104..d4f36c6950 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -39,7 +39,7 @@ More information about Android identifier best practices can be found [here](htt > [!WARNING] > -> 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 [`installation.id`](../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 9064f397ba..b41f573cba 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -23,7 +23,7 @@ groups: > [!WARNING] > - > 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 [`installation.id`](../attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. examples: - my_vendor:1234567890 From 6e57e18e2bb9cd92b594bdfb5deaea03d4ee3927 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 16 Feb 2025 18:37:46 +0100 Subject: [PATCH 11/23] Change reference to absolute one --- docs/attributes-registry/device.md | 2 +- docs/resource/device.md | 2 +- model/device/registry.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index e5e705d0be..18a5eb0d12 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -27,7 +27,7 @@ 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`](../attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. +> 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 d4f36c6950..fbb7d8c5d9 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -40,7 +40,7 @@ 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`](../attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. +> 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 b41f573cba..5a9f95b98c 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -24,7 +24,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`](../attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. + > See [`installation.id`](/docs/attributes-registry/installation.md#installation-id) as a more privacy-preserving alternative. examples: - my_vendor:1234567890 - imei:123456789012345 From 0ac630834e223554ac1e58feae512df705e1b66b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 20:37:52 +0100 Subject: [PATCH 12/23] Add note about alternative installation.id implementations --- docs/attributes-registry/installation.md | 2 +- model/installation/registry.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/attributes-registry/installation.md b/docs/attributes-registry/installation.md index 0956762e91..8eb6cf8787 100644 --- a/docs/attributes-registry/installation.md +++ b/docs/attributes-registry/installation.md @@ -23,7 +23,7 @@ On Android this value SHOULD be equal to either: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. -But it MAY be equal to other identifiers such as: +But it MAY be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: - [App set ID](https://developer.android.com/identity/app-set-id). - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). diff --git a/model/installation/registry.yaml b/model/installation/registry.yaml index 4fb6df0229..db040420d4 100644 --- a/model/installation/registry.yaml +++ b/model/installation/registry.yaml @@ -24,7 +24,7 @@ groups: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. - But it MAY be equal to other identifiers such as: + But it MAY be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: - [App set ID](https://developer.android.com/identity/app-set-id). - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). From 7bf94ad92d8a01777e5ecacec70727358be897f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 20:40:21 +0100 Subject: [PATCH 13/23] Revert prefix idea --- docs/attributes-registry/device.md | 3 +-- docs/attributes-registry/installation.md | 3 +-- docs/resource/device.md | 3 +-- model/device/registry.yaml | 6 ++---- model/installation/registry.yaml | 7 +------ 5 files changed, 6 insertions(+), 16 deletions(-) diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index 0c09bf2bd2..de29a3ccd9 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -9,7 +9,7 @@ Describes device attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `device.id` | string | A unique identifier representing the device [1] | `my_vendor:1234567890`; `imei:123456789012345`; `mac:01:23:45:67:89:AB` | ![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) | @@ -20,7 +20,6 @@ Consequently, instrumentations that provide it MUST provide it as an opt-in feat 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. -The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). diff --git a/docs/attributes-registry/installation.md b/docs/attributes-registry/installation.md index 8eb6cf8787..832b4e4521 100644 --- a/docs/attributes-registry/installation.md +++ b/docs/attributes-registry/installation.md @@ -9,12 +9,11 @@ Describes installation attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `identifier_for_vendor:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `firebase:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `guid:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `app_set_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092`; `android_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Development](https://img.shields.io/badge/-development-blue) | +| `installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Development](https://img.shields.io/badge/-development-blue) | **[1] `installation.id`:** Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. -The `installation.id` value SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). diff --git a/docs/resource/device.md b/docs/resource/device.md index 2567240fc5..1be2c1bbbd 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -19,7 +19,7 @@ | [`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] | `my_vendor:1234567890`; `imei:123456789012345`; `mac:01:23:45:67:89:AB` | `Opt-In` | ![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.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`. @@ -33,7 +33,6 @@ Consequently, instrumentations that provide it MUST provide it as an opt-in feat 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. -The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). diff --git a/model/device/registry.yaml b/model/device/registry.yaml index 0faaaa67b4..f540a89b46 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -17,7 +17,6 @@ groups: 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. - The `device.id` SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `imei:`). More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). @@ -26,9 +25,8 @@ groups: > 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: - - my_vendor:1234567890 - - imei:123456789012345 - - mac:01:23:45:67:89:AB + - '123456789012345' + - 01:23:45:67:89:AB - id: device.manufacturer type: string stability: development diff --git a/model/installation/registry.yaml b/model/installation/registry.yaml index db040420d4..a3414b4416 100644 --- a/model/installation/registry.yaml +++ b/model/installation/registry.yaml @@ -15,7 +15,6 @@ groups: Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. - The `installation.id` value SHOULD be prefixed with the type of the identifier and a colon separator (e.g. `firebase:`). On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). @@ -31,8 +30,4 @@ groups: More information about Android identifier best practices can be found [here](https://developer.android.com/training/articles/user-data-ids). examples: - - identifier_for_vendor:2ab2916d-a51f-4ac8-80ee-45ac31a28092 - - firebase:2ab2916d-a51f-4ac8-80ee-45ac31a28092 - - guid:2ab2916d-a51f-4ac8-80ee-45ac31a28092 - - app_set_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092 - - android_id:2ab2916d-a51f-4ac8-80ee-45ac31a28092 + - 2ab2916d-a51f-4ac8-80ee-45ac31a28092 From 922bbfa7fe98f138031461b403f1b5350583ebc9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 20:48:32 +0100 Subject: [PATCH 14/23] Rename attribute to `app.installation.id` --- .chloggen/1897.yaml | 2 +- .github/ISSUE_TEMPLATE/bug_report.yaml | 2 +- .github/ISSUE_TEMPLATE/change_proposal.yaml | 2 +- docs/attributes-registry/README.md | 2 +- docs/attributes-registry/{installation.md => app.md} | 10 +++++----- model/{installation => app}/registry.yaml | 8 ++++---- model/app/resources.yaml | 9 +++++++++ model/installation/resources.yaml | 9 --------- 8 files changed, 22 insertions(+), 22 deletions(-) rename docs/attributes-registry/{installation.md => app.md} (70%) rename model/{installation => app}/registry.yaml (89%) create mode 100644 model/app/resources.yaml delete mode 100644 model/installation/resources.yaml diff --git a/.chloggen/1897.yaml b/.chloggen/1897.yaml index 342f0f8220..bca14f213f 100644 --- a/.chloggen/1897.yaml +++ b/.chloggen/1897.yaml @@ -10,7 +10,7 @@ change_type: enhancement component: device # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: Create `installation.id` and change the definition of `device.id` +note: Create `app.installation.id` and change the definition of `device.id` # 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. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index ecd006cd59..2328f06574 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -23,6 +23,7 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:app - area:artifact - area:aspnetcore - area:aws @@ -60,7 +61,6 @@ body: - area:heroku - area:host - area:http - - area:installation - area:jvm - area:k8s - area:linux diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 6e2d0ca1b4..4733423f6b 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -15,6 +15,7 @@ body: # DO NOT manually edit it. # Start semconv area list - area:android + - area:app - area:artifact - area:aspnetcore - area:aws @@ -52,7 +53,6 @@ body: - area:heroku - area:host - area:http - - area:installation - area:jvm - area:k8s - area:linux diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index faac759362..009deb0042 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -34,6 +34,7 @@ All registered attributes are listed by namespace in this registry. Currently, the following namespaces exist: - [Android](android.md) +- [App](app.md) - [Artifact](artifact.md) - [Aspnetcore](aspnetcore.md) - [AWS](aws.md) @@ -72,7 +73,6 @@ Currently, the following namespaces exist: - [Heroku](heroku.md) - [Host](host.md) - [HTTP](http.md) -- [Installation](installation.md) - [iOS](ios.md) - [JVM](jvm.md) - [K8s](k8s.md) diff --git a/docs/attributes-registry/installation.md b/docs/attributes-registry/app.md similarity index 70% rename from docs/attributes-registry/installation.md rename to docs/attributes-registry/app.md index 832b4e4521..49797bb0e1 100644 --- a/docs/attributes-registry/installation.md +++ b/docs/attributes-registry/app.md @@ -1,17 +1,17 @@ -# Installation +# App -## Installation Attributes +## App Attributes -Describes installation attributes. +Describes attributes related to client-side applications (e.g. web apps or mobile apps). | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Development](https://img.shields.io/badge/-development-blue) | +| `app.installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Development](https://img.shields.io/badge/-development-blue) | -**[1] `installation.id`:** Its value SHOULD remain the same between launches of the same installation of an application. +**[1] `app.installation.id`:** Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. diff --git a/model/installation/registry.yaml b/model/app/registry.yaml similarity index 89% rename from model/installation/registry.yaml rename to model/app/registry.yaml index a3414b4416..fd38954acb 100644 --- a/model/installation/registry.yaml +++ b/model/app/registry.yaml @@ -1,12 +1,12 @@ groups: - - id: registry.installation + - id: registry.app type: attribute_group - display_name: Installation Attributes + display_name: App Attributes brief: > - Describes installation attributes. + Describes attributes related to client-side applications (e.g. web apps or mobile apps). stability: development attributes: - - id: installation.id + - id: app.installation.id type: string stability: development brief: > diff --git a/model/app/resources.yaml b/model/app/resources.yaml new file mode 100644 index 0000000000..55d647218c --- /dev/null +++ b/model/app/resources.yaml @@ -0,0 +1,9 @@ +groups: + - id: resource.app + type: resource + stability: development + name: app + brief: > + A client-side application. + attributes: + - ref: app.installation.id diff --git a/model/installation/resources.yaml b/model/installation/resources.yaml deleted file mode 100644 index 2187257393..0000000000 --- a/model/installation/resources.yaml +++ /dev/null @@ -1,9 +0,0 @@ -groups: - - id: resource.installation - type: resource - stability: development - name: installation - brief: > - The installation of the application represented by this resource on a specific device. - attributes: - - ref: installation.id From b1ca8d510d1680f81171faf62591430372c5049b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 20:54:17 +0100 Subject: [PATCH 15/23] Move device.id changes to a separate PR --- .chloggen/1897.yaml | 2 +- docs/attributes-registry/device.md | 16 ++-------------- docs/resource/device.md | 28 ++++++++-------------------- model/device/registry.yaml | 29 +++++++++++------------------ model/device/resources.yaml | 3 +-- 5 files changed, 23 insertions(+), 55 deletions(-) diff --git a/.chloggen/1897.yaml b/.chloggen/1897.yaml index bca14f213f..7f19759e88 100644 --- a/.chloggen/1897.yaml +++ b/.chloggen/1897.yaml @@ -10,7 +10,7 @@ change_type: enhancement component: device # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). -note: Create `app.installation.id` and change the definition of `device.id` +note: Create `app.installation.id` attribute # 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. diff --git a/docs/attributes-registry/device.md b/docs/attributes-registry/device.md index de29a3ccd9..59d1d5cc92 100644 --- a/docs/attributes-registry/device.md +++ b/docs/attributes-registry/device.md @@ -9,24 +9,12 @@ Describes device attributes. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `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.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![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.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. +**[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. **[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..5e3d2cb2c8 100644 --- a/docs/resource/device.md +++ b/docs/resource/device.md @@ -16,30 +16,18 @@ | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`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) | +| [`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) | -**[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`. +**[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. -**[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. +**[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`. -**[3] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. +**[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. -**[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. +**[4] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative. diff --git a/model/device/registry.yaml b/model/device/registry.yaml index f540a89b46..bfd8795be8 100644 --- a/model/device/registry.yaml +++ b/model/device/registry.yaml @@ -3,30 +3,23 @@ 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.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 + 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'] - id: device.manufacturer type: string stability: development diff --git a/model/device/resources.yaml b/model/device/resources.yaml index b9f8621f3f..8f54124e54 100644 --- a/model/device/resources.yaml +++ b/model/device/resources.yaml @@ -4,10 +4,9 @@ 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 34207c337c901d2b05692455a00f1787e2d325c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 20:56:11 +0100 Subject: [PATCH 16/23] Rename directory in CODEOWNERS too --- .github/CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 77b87465d2..2a2c2f1611 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -56,8 +56,8 @@ # Mobile semantic conventions /docs/mobile/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers +/model/app/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers /model/device/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers -/model/installation/ @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-mobile-approvers # K8s semantic conventions /docs/resource/k8s.md @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-k8s-approvers From fd2e226e99a362fd85613f4281bd8244677f2905 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 21:09:00 +0100 Subject: [PATCH 17/23] Make adjustments based on @bidetofevil's comment --- docs/attributes-registry/app.md | 6 ++++-- model/app/registry.yaml | 6 ++++-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/attributes-registry/app.md b/docs/attributes-registry/app.md index 49797bb0e1..653d51a92d 100644 --- a/docs/attributes-registry/app.md +++ b/docs/attributes-registry/app.md @@ -13,7 +13,9 @@ Describes attributes related to client-side applications (e.g. web apps or mobil **[1] `app.installation.id`:** Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. -Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. +Additionally, users might be able to reset this value (e.g. by clearing application data). +If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. +Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). @@ -22,7 +24,7 @@ On Android this value SHOULD be equal to either: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. -But it MAY be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: +But it might be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: - [App set ID](https://developer.android.com/identity/app-set-id). - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). diff --git a/model/app/registry.yaml b/model/app/registry.yaml index fd38954acb..0082d5e89e 100644 --- a/model/app/registry.yaml +++ b/model/app/registry.yaml @@ -14,7 +14,9 @@ groups: note: | Its value SHOULD remain the same between launches of the same installation of an application. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. - Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the installation identifier. + Additionally, users might be able to reset this value (e.g. by clearing application data). + If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. + Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). @@ -23,7 +25,7 @@ groups: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. - But it MAY be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: + But it might be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: - [App set ID](https://developer.android.com/identity/app-set-id). - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). From 76ce4ba90c670799fe2c14a7be2312006e8259f1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Thu, 27 Feb 2025 21:25:18 +0100 Subject: [PATCH 18/23] Update changelog entry --- .chloggen/1897.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.chloggen/1897.yaml b/.chloggen/1897.yaml index 7f19759e88..8b123e24af 100644 --- a/.chloggen/1897.yaml +++ b/.chloggen/1897.yaml @@ -4,10 +4,10 @@ # your pull request title with [chore] or use the "Skip Changelog" label. # One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' -change_type: enhancement +change_type: new_component # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: device +component: app # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: Create `app.installation.id` attribute From 0d2f2b321214645f34a6b57ef991b9fb8281e2c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 23 Mar 2025 20:01:07 +0100 Subject: [PATCH 19/23] Add note about app upgrades --- docs/attributes-registry/app.md | 2 +- model/app/registry.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/attributes-registry/app.md b/docs/attributes-registry/app.md index 653d51a92d..ad66d810b7 100644 --- a/docs/attributes-registry/app.md +++ b/docs/attributes-registry/app.md @@ -11,7 +11,7 @@ Describes attributes related to client-side applications (e.g. web apps or mobil |---|---|---|---|---| | `app.installation.id` | string | A unique identifier representing the installation of an application on a specific device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Development](https://img.shields.io/badge/-development-blue) | -**[1] `app.installation.id`:** Its value SHOULD remain the same between launches of the same installation of an application. +**[1] `app.installation.id`:** Its value SHOULD persist across launches of the same application installation, including through application upgrades. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Additionally, users might be able to reset this value (e.g. by clearing application data). If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. diff --git a/model/app/registry.yaml b/model/app/registry.yaml index 0082d5e89e..f243b76783 100644 --- a/model/app/registry.yaml +++ b/model/app/registry.yaml @@ -12,7 +12,7 @@ groups: brief: > A unique identifier representing the installation of an application on a specific device note: | - Its value SHOULD remain the same between launches of the same installation of an application. + Its value SHOULD persist across launches of the same application installation, including through application upgrades. It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Additionally, users might be able to reset this value (e.g. by clearing application data). If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. From 79c88d55de1d22b460cf57350df2da6a7405ada1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 23 Mar 2025 20:04:22 +0100 Subject: [PATCH 20/23] Add note about multiple OTel SDKs in an app --- docs/attributes-registry/app.md | 1 + model/app/registry.yaml | 1 + 2 files changed, 2 insertions(+) diff --git a/docs/attributes-registry/app.md b/docs/attributes-registry/app.md index ad66d810b7..d0289d96bd 100644 --- a/docs/attributes-registry/app.md +++ b/docs/attributes-registry/app.md @@ -15,6 +15,7 @@ Describes attributes related to client-side applications (e.g. web apps or mobil It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Additionally, users might be able to reset this value (e.g. by clearing application data). If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. +If multiple OpenTelemetry SDKs are used within the same application, they SHOULD use the same value for `app.installation.id`. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). diff --git a/model/app/registry.yaml b/model/app/registry.yaml index f243b76783..972c4eed27 100644 --- a/model/app/registry.yaml +++ b/model/app/registry.yaml @@ -16,6 +16,7 @@ groups: It SHOULD change if the application is uninstalled or if all applications of the vendor are uninstalled. Additionally, users might be able to reset this value (e.g. by clearing application data). If an app is installed multiple times on the same device (e.g. in different accounts on Android), each `app.installation.id` SHOULD have a different value. + If multiple OpenTelemetry SDKs are used within the same application, they SHOULD use the same value for `app.installation.id`. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). From c93b2d69bbf780fa788b2950e9b6023af876942d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Sun, 23 Mar 2025 20:17:27 +0100 Subject: [PATCH 21/23] Change sentence to introduce Android examples --- docs/attributes-registry/app.md | 5 +---- model/app/registry.yaml | 5 +---- 2 files changed, 2 insertions(+), 8 deletions(-) diff --git a/docs/attributes-registry/app.md b/docs/attributes-registry/app.md index d0289d96bd..860e2b0756 100644 --- a/docs/attributes-registry/app.md +++ b/docs/attributes-registry/app.md @@ -20,13 +20,10 @@ Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `ap On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). -On Android this value SHOULD be equal to either: +For Android the following identifiers are examples for possible `app.installation.id` implementations: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. - -But it might be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: - - [App set ID](https://developer.android.com/identity/app-set-id). - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). diff --git a/model/app/registry.yaml b/model/app/registry.yaml index 972c4eed27..bc21dd2161 100644 --- a/model/app/registry.yaml +++ b/model/app/registry.yaml @@ -21,13 +21,10 @@ groups: On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). - On Android this value SHOULD be equal to either: + For Android examples of `app.installation.id` implementations include: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. - - But it might be equal to other identifiers as well, if the above implementations are not preferred for some reason, such as: - - [App set ID](https://developer.android.com/identity/app-set-id). - [`Settings.getString(Settings.Secure.ANDROID_ID)`](https://developer.android.com/reference/android/provider/Settings.Secure#ANDROID_ID). From 5792fcdc986e6af28a4d4079c9d79b4d207806c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Tue, 25 Mar 2025 09:56:24 +0100 Subject: [PATCH 22/23] Improve language --- docs/attributes-registry/app.md | 4 ++-- model/app/registry.yaml | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/attributes-registry/app.md b/docs/attributes-registry/app.md index 860e2b0756..bccb064caa 100644 --- a/docs/attributes-registry/app.md +++ b/docs/attributes-registry/app.md @@ -18,9 +18,9 @@ If an app is installed multiple times on the same device (e.g. in different acco If multiple OpenTelemetry SDKs are used within the same application, they SHOULD use the same value for `app.installation.id`. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. -On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). +For iOS, this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). -For Android the following identifiers are examples for possible `app.installation.id` implementations: +For Android, examples of `app.installation.id` implementations include: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. diff --git a/model/app/registry.yaml b/model/app/registry.yaml index bc21dd2161..c14877c751 100644 --- a/model/app/registry.yaml +++ b/model/app/registry.yaml @@ -19,9 +19,9 @@ groups: If multiple OpenTelemetry SDKs are used within the same application, they SHOULD use the same value for `app.installation.id`. Hardware IDs (e.g. serial number, IMEI, MAC address) MUST NOT be used as the `app.installation.id`. - On iOS this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). + For iOS, this value SHOULD be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/identifierforvendor). - For Android examples of `app.installation.id` implementations include: + For Android, examples of `app.installation.id` implementations include: - [Firebase Installation ID](https://firebase.google.com/docs/projects/manage-installations). - A globally unique UUID which is persisted across sessions in your application. From c5c583b284c6d62348a7502ce7c8242bf7506410 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bence=20Horn=C3=A1k?= Date: Tue, 25 Mar 2025 09:57:57 +0100 Subject: [PATCH 23/23] Improve description of app attributes --- docs/attributes-registry/app.md | 2 +- model/app/registry.yaml | 2 +- model/app/resources.yaml | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/attributes-registry/app.md b/docs/attributes-registry/app.md index bccb064caa..676329712a 100644 --- a/docs/attributes-registry/app.md +++ b/docs/attributes-registry/app.md @@ -3,7 +3,7 @@ # App -## App Attributes +## Application Attributes Describes attributes related to client-side applications (e.g. web apps or mobile apps). diff --git a/model/app/registry.yaml b/model/app/registry.yaml index c14877c751..4c3030b0ef 100644 --- a/model/app/registry.yaml +++ b/model/app/registry.yaml @@ -1,7 +1,7 @@ groups: - id: registry.app type: attribute_group - display_name: App Attributes + display_name: Application Attributes brief: > Describes attributes related to client-side applications (e.g. web apps or mobile apps). stability: development diff --git a/model/app/resources.yaml b/model/app/resources.yaml index 55d647218c..bd21fd82db 100644 --- a/model/app/resources.yaml +++ b/model/app/resources.yaml @@ -4,6 +4,6 @@ groups: stability: development name: app brief: > - A client-side application. + An app used directly by end users — like mobile, web, or desktop. attributes: - ref: app.installation.id