diff --git a/CHANGELOG.md b/CHANGELOG.md index eebf96d37d1..f5df7eabb78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,8 +29,8 @@ release. ### Semantic Conventions - Add JSON RPC specific conventions ([#1643](https://github.com/open-telemetry/opentelemetry-specification/pull/1643)). - - Add Memcached to Database specific conventions ([#1689](https://github.com/open-telemetry/opentelemetry-specification/pull/1689)). +- Add semantic convention attributes for the host device and added OS name and version ([#1596](https://github.com/open-telemetry/opentelemetry-specification/pull/1596)). ### Compatibility diff --git a/semantic_conventions/resource/device.yaml b/semantic_conventions/resource/device.yaml new file mode 100644 index 00000000000..6035a4b2da9 --- /dev/null +++ b/semantic_conventions/resource/device.yaml @@ -0,0 +1,34 @@ +groups: + - id: device + prefix: device + brief: > + The device on which the process represented by this resource is running. + attributes: + - id: id + type: string + 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'] + - id: model.identifier + type: string + brief: 'The model identifier for the device' + note: > + 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. + examples: ['iPhone3,4', 'SM-G920F'] + - id: model.name + type: string + brief: 'The marketing name for the device model' + note: > + It's recommended this value represents a human readable version of the + device model rather than a machine readable alternative. + examples: ['iPhone 6s Plus', 'Samsung Galaxy S6'] diff --git a/semantic_conventions/resource/os.yaml b/semantic_conventions/resource/os.yaml index b0004129b1b..388b2aa0b28 100644 --- a/semantic_conventions/resource/os.yaml +++ b/semantic_conventions/resource/os.yaml @@ -49,6 +49,16 @@ groups: - id: description type: string brief: > - Human readable (not intended to be parsed) OS version information, - like e.g. reported by `ver` or `lsb_release -a` commands. + Human readable (not intended to be parsed) OS version information, + like e.g. reported by `ver` or `lsb_release -a` commands. examples: ['Microsoft Windows [Version 10.0.18363.778]', 'Ubuntu 18.04.1 LTS'] + - id: name + type: string + brief: 'Human readable operating system name.' + examples: ['iOS', 'Android', 'Ubuntu'] + - id: version + type: string + brief: > + The version string of the operating system as defined in + [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). + examples: ['14.2.1', '18.04.1'] diff --git a/specification/resource/semantic_conventions/README.md b/specification/resource/semantic_conventions/README.md index 95ac724977e..8a329775cc2 100644 --- a/specification/resource/semantic_conventions/README.md +++ b/specification/resource/semantic_conventions/README.md @@ -25,7 +25,7 @@ This document defines standard attributes for resources. These attributes are ty ## TODOs * Add more compute units: AppEngine unit, etc. -* Add Device (mobile) and Web Browser. +* Add Web Browser. * Decide if lower case strings only. * Consider to add optional/required for each attribute and combination of attributes (e.g when supplying a k8s resource all k8s may be required). @@ -137,6 +137,7 @@ Attributes defining a computing instance (e.g. host): Attributes defining a running environment (e.g. Operating System, Cloud, Data Center, Deployment Service): - [Operating System](./os.md) +- [Device](./device.md) - [Cloud](./cloud.md) - Deployment: - [Deployment Environment](./deployment_environment.md) diff --git a/specification/resource/semantic_conventions/device.md b/specification/resource/semantic_conventions/device.md new file mode 100644 index 00000000000..c0f936959b6 --- /dev/null +++ b/specification/resource/semantic_conventions/device.md @@ -0,0 +1,21 @@ +# Device + +**Status**: [Experimental](../../document-status.md) + +**type:** `device` + +**Description**: The device on which the process represented by this resource is running. + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| `device.id` | string | A unique identifier representing the device [1] | `2ab2916d-a51f-4ac8-80ee-45ac31a28092` | No | +| `device.model.identifier` | string | The model identifier for the device [2] | `iPhone3,4`; `SM-G920F` | No | +| `device.model.name` | string | The marketing name for the device model [3] | `iPhone 6s Plus`; `Samsung Galaxy S6` | No | + +**[1]:** 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]:** 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]:** It's recommended this value represents a human readable version of the device model rather than a machine readable alternative. + \ No newline at end of file diff --git a/specification/resource/semantic_conventions/os.md b/specification/resource/semantic_conventions/os.md index f0163f7b351..0303c3d0cd7 100644 --- a/specification/resource/semantic_conventions/os.md +++ b/specification/resource/semantic_conventions/os.md @@ -13,6 +13,8 @@ In case of virtualized environments, this is the operating system as it is obser |---|---|---|---|---| | `os.type` | string | The operating system type. | `windows` | Yes | | `os.description` | string | Human readable (not intended to be parsed) OS version information, like e.g. reported by `ver` or `lsb_release -a` commands. | `Microsoft Windows [Version 10.0.18363.778]`; `Ubuntu 18.04.1 LTS` | No | +| `os.name` | string | Human readable operating system name. | `iOS`; `Android`; `Ubuntu` | No | +| `os.version` | string | The version string of the operating system as defined in [Version Attributes](../../resource/semantic_conventions/README.md#version-attributes). | `14.2.1`; `18.04.1` | No | `os.type` MUST be one of the following or, if none of the listed values apply, a custom value: