Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Change the definition of device.id #1951

Open
wants to merge 6 commits into
base: main
Choose a base branch
from
+85 −22
Open

Change the definition of device.id #1951

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6cd950c
Change the definition of `device.id`
bencehornak Feb 27, 2025
b0ee7d3
Add changelog entry
bencehornak Feb 27, 2025
f6f5fab
Fix reference to app.installation.id
bencehornak Feb 27, 2025
fc5e3b2
Resolve CI issues
bencehornak Feb 27, 2025
bd41e66
Rephrase disclaimer
bencehornak Mar 18, 2025
ce2040a
Merge branch 'main' into device-id
bencehornak Mar 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .chloggen/1951.yaml
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
# Use this changelog template to create an entry for release notes.
#
# If your change doesn't affect end users you should instead start
# your pull request title with [chore] or use the "Skip Changelog" label.

# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
change_type: breaking

# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
component: device

# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
note: Change the definition of `device.id` and make it opt-in.

# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
# The values here must be integers.
issues: [1874, 1951]

# (Optional) One or more lines of additional information to render under the primary note.
# These lines will be padded with 2 spaces and then inserted directly into the document.
# Use pipe (|) for multiline entries.
subtext:
19 changes: 17 additions & 2 deletions docs/attributes-registry/device.md
View file
Original file line number Diff line number Diff line change
@@ -9,12 +9,27 @@ 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` | ![Development](https://img.shields.io/badge/-development-blue) |
| <a id="device-id" href="#device-id">`device.id`</a> | string | A unique identifier representing the device [1] | `123456789012345`; `01:23:45:67:89:AB` | ![Development](https://img.shields.io/badge/-development-blue) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As trask requested feedback via the Client Sig this morning, for current SDK's we support the sending / population of this either as

  • By default for a browser as the word "browser", so as with the "example" value of "123456789012345". "browser" is another "possible" value.
  • Other internal SDK's allow the setting of this value based on any supporting hardware lookup (like when running from react-native), in which case it matches the description as specified.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@MSNev do you think the browser value is desired? To me it doesn't really sound like an 'identifier', as it's not trying to provide uniqueness.

| <a id="device-manufacturer" href="#device-manufacturer">`device.manufacturer`</a> | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | ![Development](https://img.shields.io/badge/-development-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` | ![Development](https://img.shields.io/badge/-development-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` | ![Development](https://img.shields.io/badge/-development-blue) |

**[1] `device.id`:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.
**[1] `device.id`:** 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 may contain sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply,
> ensure you do your own due diligence.
>
> Due to these reasons, this identifier is not recommended for consumer applications and will likely result in rejection from both Google Play and App Store.
> However, it may be appropriate for specific enterprise scenarios, such as kiosk devices or enterprise-managed devices, with appropriate compliance clearance.
> Any instrumentation providing this identifier MUST implement it as an opt-in feature.
>
> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) for a more privacy-preserving alternative.
**[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.

31 changes: 23 additions & 8 deletions docs/resource/device.md
View file
Original file line number Diff line number Diff line change
@@ -16,18 +16,33 @@

| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
|---|---|---|---|---|---|
| [`device.id`](/docs/attributes-registry/device.md) | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`device.manufacturer`](/docs/attributes-registry/device.md) | string | The name of the device manufacturer [2] | `Apple`; `Samsung` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [3] | `iPhone3,4`; `SM-G920F` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`device.model.name`](/docs/attributes-registry/device.md) | string | The marketing name for the device model [4] | `iPhone 6s Plus`; `Samsung Galaxy S6` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`device.manufacturer`](/docs/attributes-registry/device.md) | string | The name of the device manufacturer [1] | `Apple`; `Samsung` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion: As a generic "namespace" for devices, its probably also worth considering an additional device.class which describes the type of device in a more generic form with possible values like

  • Mobile
  • Desktop
  • Android
  • Windows
  • XBox
  • iOS
  • Browser
  • etc

Although, there may be a collection of other attributes which could be used by backends to derive some of this information.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds reasonable to me, I would keep this suggestion to a separate PR though, if you don't mind.

| [`device.model.identifier`](/docs/attributes-registry/device.md) | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`device.model.name`](/docs/attributes-registry/device.md) | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) |
| [`device.id`](/docs/attributes-registry/device.md) | string | A unique identifier representing the device [4] | `123456789012345`; `01:23:45:67:89:AB` | `Opt-In` | ![Development](https://img.shields.io/badge/-development-blue) |

**[1] `device.id`:** The device identifier MUST only be defined using the values outlined below. This value is not an advertising identifier and MUST NOT be used as such. On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor). On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids) on best practices and exact implementation details. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply, ensure you do your own due diligence.
**[1] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.

**[2] `device.manufacturer`:** The Android OS provides this field via [Build](https://developer.android.com/reference/android/os/Build#MANUFACTURER). iOS apps SHOULD hardcode the value `Apple`.
**[2] `device.model.identifier`:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device.

**[3] `device.model.identifier`:** It's recommended this value represents a machine-readable version of the model identifier rather than the market or consumer-friendly name of the device.
**[3] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative.

**[4] `device.model.name`:** It's recommended this value represents a human-readable version of the device model rather than a machine-readable alternative.
**[4] `device.id`:** 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 may contain sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply,
> ensure you do your own due diligence.
>
> Due to these reasons, this identifier is not recommended for consumer applications and will likely result in rejection from both Google Play and App Store.
> However, it may be appropriate for specific enterprise scenarios, such as kiosk devices or enterprise-managed devices, with appropriate compliance clearance.
> Any instrumentation providing this identifier MUST implement it as an opt-in feature.
>
> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) for a more privacy-preserving alternative.
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
32 changes: 21 additions & 11 deletions model/device/registry.yaml
View file
Original file line number Diff line number Diff line change
@@ -3,23 +3,33 @@ groups:
type: attribute_group
display_name: Device Attributes
brief: >
Describes device attributes.
Describes device attributes.
attributes:
- id: device.id
type: string
stability: development
brief: >
A unique identifier representing the device
note: >
The device identifier MUST only be defined using the values outlined below. This value is not an advertising
identifier and MUST NOT be used as such.
On iOS (Swift or Objective-C), this value MUST be equal to the [vendor identifier](https://developer.apple.com/documentation/uikit/uidevice/1620059-identifierforvendor).
On Android (Java or Kotlin), this value MUST be equal to the Firebase Installation ID or a globally unique
UUID which is persisted across sessions in your application. More information can be found [here](https://developer.android.com/training/articles/user-data-ids)
on best practices and exact implementation details.
Caution should be taken when storing personal data or anything which can identify a user. GDPR and
data protection laws may apply, ensure you do your own due diligence.
examples: ['2ab2916d-a51f-4ac8-80ee-45ac31a28092']
note: |
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 may contain sensitive (PII) information. Caution should be taken when storing personal data or anything which can identify a user. GDPR and data protection laws may apply,
> ensure you do your own due diligence.
>
> Due to these reasons, this identifier is not recommended for consumer applications and will likely result in rejection from both Google Play and App Store.
> However, it may be appropriate for specific enterprise scenarios, such as kiosk devices or enterprise-managed devices, with appropriate compliance clearance.
> Any instrumentation providing this identifier MUST implement it as an opt-in feature.
>
> See [`app.installation.id`](/docs/attributes-registry/app.md#app-installation-id) for a more privacy-preserving alternative.
examples:
- '123456789012345'
- 01:23:45:67:89:AB
- id: device.manufacturer
type: string
stability: development
3 changes: 2 additions & 1 deletion model/device/resources.yaml
View file
Original file line number Diff line number Diff line change
@@ -4,9 +4,10 @@ groups:
stability: development
name: device
brief: >
The device on which the process represented by this resource is running.
The device on which the process represented by this resource is running.
attributes:
- ref: device.id
requirement_level: opt_in
- ref: device.manufacturer
- ref: device.model.identifier
- ref: device.model.name