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

Add Resource browser and app attributes, clarify device attributes as client-side only #2115

Closed
wants to merge 6 commits into from
Closed

Add Resource browser and app attributes, clarify device attributes as client-side only #2115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a07e596
added section for browsers, clarified device as client-side only
Nov 10, 2021
51b548f
added app attributes
Nov 13, 2021
31e3e4e
added browser.userAgent attribute
Nov 13, 2021
edad422
updated description of device and browser attributes
Nov 13, 2021
9801b85
added app.bundle and app.shortVersion
Nov 23, 2021
9085bce
updated attributes names to use underscores
Nov 23, 2021
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
29 changes: 27 additions & 2 deletions specification/resource/semantic_conventions/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,6 @@ This document defines standard attributes for resources. These attributes are ty
## TODOs

* Add more compute units: AppEngine unit, etc.
* 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).
Expand Down Expand Up @@ -91,6 +90,31 @@ namespace = Company
service.name = Shop.shoppingcart
```

## App
Copy link
Contributor

Choose a reason for hiding this comment

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

How is this different from existing service.* attributes?

Copy link
Contributor

Choose a reason for hiding this comment

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

An app is not a service. It has different qualitative properties and behaviors. Separating the namespaces will allow backends to account for these differences and treat RUM signals differently.


**type:** `app`

**Description:** A client application instance.

<!-- semconv service -->
| Attribute | Type | Description | Examples | Required |
|---|---|---|---|---|
| `app.name` | string | Logical name of the client application. [1] | `web storefront` | Yes |
| `app.namespace` | string | A namespace for `app.name`. [2] | `Shop` | No |
| `app.bundle` | string | Name of the bundle or package. [3] | `ShopApplication`, `com.example.ShopApplication` | No |
| `app.version` | string | The version string of the app build or implementation. This can include more verbose information, such as the build number. [4] | `2.0.0` | No |
| `app.short_version` | string | Human-readable version or version used to identify a release to end users. [5] | `10.14.1` | No |

**[1]:** MUST be the same for all instances of the application running on individual client devices. If the value was not specified, SDKs MUST fallback to `unknown_application`.

**[2]:** A string value having a meaning that helps to distinguish a group of client applications, for example the team name that owns a group of applications or web site name that consists of multiple components. `app.name` is expected to be unique within the same namespace. If `app.namespace` is not specified in the Resource then `app.name` is expected to be unique for all applications that have no explicit namespace defined (so the empty/unspecified namespace is simply one more valid namespace). Zero-length namespace string is assumed equal to unspecified namespace.
Copy link

Choose a reason for hiding this comment

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

Is it correct to say that one app can belong to only one app.namespace? In order words, a single app.namespace can have multiple apps, or app.name(s) but an app.name can only belong to one namespace?

Copy link
Contributor

Choose a reason for hiding this comment

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

What about the situation (real world asks from customers) who are capturing telemetry from browser applications with large surface area (hundreds of different screens), built and maintained by different teams but all packaged in one user-facing UI. These customers want to have different app.name to be set on different parts of the application, for example: everything under /users belongs into app.name=User management and everything under /invoice belongs into app.name=Billing

Considering that resources are immutable by the spec, we cannot change the app.name dynamically during runtime. Initializing multiple tracers could be an option, but different issues (such as SPAs in browser applications initializing only on pageloads and not on route changes) as well as issues with global method instrumentations (XHR/fetch in browser) where isolation is not guaranteed so in practice this also does not seem to work.

Wonder what is the recommended path forward to support such cases? Relaxing spec requirements on resource immutability maybe?

Copy link

Choose a reason for hiding this comment

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

Adding onto above, another case where updating resource would be useful when adding user identifiying attributes like enduser.* (while on server request model having them added per span is more useful as generally every request may be served to different users, in a stateful application it'd be simpler to put it into resource (as you'd generally have one user using it at a time) and update when application state changes (user logs in / out) as it happens less frequently)

If not mutating the resource then at least swapping out the currently attached Resource on TracerProvider / MeterProvider / ... so any new spans afterwards would use the new state / easily differentiated based on different Resource instance

Copy link
Contributor Author

Choose a reason for hiding this comment

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

@ivomagi @t2t2 Good point, I added this as a topic to the Client-side SIG agenda on 12/1.


**[3]:** For iOS bundles, this equates to the `CFBundleName` property, and for Android to the `android:package` attribute.

**[4]:** For iOS bundles, this equates to the `CFBundleVersion` property, and for Android to the `android:versionCode` attribute.

**[5]:** For iOS bundles, this equates to the `CFBundleShortVersionString` property, and for Android to the `android:versionName` attribute.

## Telemetry SDK

**type:** `telemetry.sdk`
Expand Down Expand Up @@ -151,11 +175,12 @@ 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)
- [Device](./device.md) (client-side)
- [Cloud](./cloud.md)
- Deployment:
- [Deployment Environment](./deployment_environment.md)
- [Kubernetes](./k8s.md)
- [Browser](./browser.md)

## Version attributes

Expand Down
18 changes: 18 additions & 0 deletions specification/resource/semantic_conventions/browser.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# Browser

**Status**: [Experimental](../../document-status.md)

**type:** `browser`

**Description**: The web browser in which the application represented by the resource is running. The `browser.*` attributes MUST be used only for resources that represent applications running in a web browser. The presence of these attributes is intended to identify client-side telemetry.

Copy link

Choose a reason for hiding this comment

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

Should spec have semconv for things that are currently mostly added during ingest? I don't think anyone parses useragent client side and there is currently no other way of getting the browser version etc.

Copy link
Contributor

Choose a reason for hiding this comment

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

Maybe indeed worth calling out the specific case for the browser telemetry, where the information in browser.* might be represented in User-Agent header in the exported telemetry and not in the payload itself?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

I can make the change. However, I wonder if that will make it unclear whether an SDK should implement collecting these values. I think if we assume that all browsers will send these headers, then the SDKs will not be sending any of these attributes, and we might as well not define them?

<!-- semconv device -->
| Attribute | Type | Description | Examples | Required |
|---|---|---|---|---|
| `browser.name` | string | The web browser name | `Chrome` | No |
| `browser.version` | string | The web browser version | `90` | No |
| `browser.platform` | string | The operating system | `Windows` | No |
| `browser.mobile` | boolean | Flag indicating a mobile device | | No |
| `browser.user_agent` | string | Full user-agent string provided by the browser [1] | `'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/95.0.4638.54 Safari/537.36'` | No |

**[1]:** The user-agent value should be provided only from browsers that do not have a mechanism to retrieve name, version, and platform individually (for example from the User-Agent Client Hints API).
Copy link
Contributor

Choose a reason for hiding this comment

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

Snake case is recommended for words in attribute names, so browser.userAgent should be browser.user_agent.
https://opentelemetry.io/docs/reference/specification/common/attribute-naming/

2 changes: 1 addition & 1 deletion specification/resource/semantic_conventions/device.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

**type:** `device`

**Description**: The device on which the process represented by this resource is running.
**Description**: The device on which the process represented by this resource is running. The `device.*` attributes MUST be used only for resources that are not part of a private infrastructure, for example a mobile or IoT device.

<!-- semconv device -->
| Attribute | Type | Description | Examples | Required |
Expand Down