Create app.installation.id attribute

.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:

.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

.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

.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

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)

docs/attributes-registry/device.md

@@ -9,12 +9,25 @@ Describes device attributes.
 
 | Attribute | Type | Description | Examples | Stability |
 |---|---|---|---|---|
-| <a id="device-id" href="#device-id">`device.id`</a> | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| <a id="device-id" href="#device-id">`device.id`</a> | 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) |
 | <a id="device-manufacturer" href="#device-manufacturer">`device.manufacturer`</a> | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="device-model-identifier" href="#device-model-identifier">`device.model.identifier`</a> | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="device-model-name" href="#device-model-name">`device.model.name`</a> | 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`.
 

docs/attributes-registry/installation.md

@@ -0,0 +1,36 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Installation
+
+## Installation Attributes
+
+Describes installation attributes.
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| <a id="installation-id" href="#installation-id">`installation.id`</a> | 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.

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.
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->

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

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

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

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

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: