diff --git a/.chloggen/browser-resource-timing.yaml b/.chloggen/browser-resource-timing.yaml new file mode 100644 index 0000000000..3ef7c23833 --- /dev/null +++ b/.chloggen/browser-resource-timing.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: new_component + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: browser + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Add `browser.resource_timing` event. + +# 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: [3069] + +# (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: diff --git a/docs/browser/browser-events.md b/docs/browser/browser-events.md index c25a76fd3d..cf2dcfc049 100644 --- a/docs/browser/browser-events.md +++ b/docs/browser/browser-events.md @@ -22,7 +22,7 @@ that emit events. The event name MUST be `browser.web_vital`. -This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). +This event describes the website performance metrics introduced by Google. See [web vitals](https://web.dev/vitals). **Body fields:** @@ -43,7 +43,7 @@ semantic convention tooling supports complex attributes |---|---|---| | `cls` | Cumulative Layout Shift. See [cls](https://web.dev/articles/cls). | ![Development](https://img.shields.io/badge/-development-blue) | | `fid` | First Input Delay. See [fid](https://web.dev/articles/fid). | ![Development](https://img.shields.io/badge/-development-blue) | -| `inp` | Interation to Next Paint. See [inp](https://web.dev/articles/inp). | ![Development](https://img.shields.io/badge/-development-blue) | +| `inp` | Interaction to Next Paint. See [inp](https://web.dev/articles/inp). | ![Development](https://img.shields.io/badge/-development-blue) | | `lcp` | Largest Contentful Paint. See [lcp](https://web.dev/articles/lcp). | ![Development](https://img.shields.io/badge/-development-blue) | @@ -51,4 +51,61 @@ semantic convention tooling supports complex attributes +## Resource Timing Event + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `browser.resource_timing`. + +This event describes the timing metrics as provided by PerformanceResourceTiming Performance API. These metrics are related to fetching a resource, such as XMLHttpRequest, Fetch, sendBeacon APIs, SVG, image or script. + +This event captures data from the [ResourceTiming](https://www.w3.org/TR/resource-timing/). It is recommended to be captured by using the PerformanceResourceTiming API. If the page starts unloading before the page loads, then the partial data can be captured by calling the [performance.getEntriesByType](https://developer.mozilla.org/en-US/docs/Web/API/Performance/getEntriesByType) method. + +**Attributes:** + +| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | +|---|---|---|---|---|---| +| [`browser.resource_timing.url`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [1] | `https://www.example.com/path`; `https://cdn.example.com/styles/main.css` | +| [`browser.resource_timing.connect_end`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately after the browser completes establishing the connection to the server [2] | `145.7`; `275.2` | +| [`browser.resource_timing.connect_start`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately before the browser starts to establish the connection to the server [3] | `131.0`; `261.3` | +| [`browser.resource_timing.domain_lookup_end`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately after the browser completes the domain name lookup for the resource [4] | `130.2`; `260.5` | +| [`browser.resource_timing.domain_lookup_start`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately before the browser starts the domain name lookup for the resource [5] | `125.3`; `255.8` | +| [`browser.resource_timing.fetch_start`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately before the browser starts to fetch the resource [6] | `120.5`; `250.75` | +| [`browser.resource_timing.request_start`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately before the browser starts requesting the resource from the server [7] | `146.0`; `276.0` | +| [`browser.resource_timing.response_end`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately after the browser receives the last byte of the resource [8] | `220.3`; `350.5` | +| [`browser.resource_timing.response_start`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately after the browser receives the first byte of the response from the server [9] | `180.5`; `310.8` | +| [`browser.resource_timing.secure_connection_start`](/docs/registry/attributes/browser.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | double | Time immediately before the browser starts the handshake process to secure the connection [10] | `132.5`; `262.8` | + +**[1] `browser.resource_timing.url`:** Generally the url doesn't include any query strings or any leading credentials, and it's formatted as scheme://full domain/path only, for example `https://www.example.com/path?a=b&c=d` would be sent as `https://www.example.com/path` by both removing any potential PII and reducing the cardinality of the name. + +**[2] `browser.resource_timing.connect_end`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-connectend). + +**[3] `browser.resource_timing.connect_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-connectstart). + +**[4] `browser.resource_timing.domain_lookup_end`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-domainlookupend). + +**[5] `browser.resource_timing.domain_lookup_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-domainlookupstart). + +**[6] `browser.resource_timing.fetch_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-fetchstart). + +**[7] `browser.resource_timing.request_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-requeststart). + +**[8] `browser.resource_timing.response_end`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-responseend). + +**[9] `browser.resource_timing.response_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-responsestart). + +**[10] `browser.resource_timing.secure_connection_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. If the scheme is not HTTPS, this value is 0. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-secureconnectionstart). + + + + + + [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/registry/attributes/browser.md b/docs/registry/attributes/browser.md index cc8d235f4e..75f9ff3744 100644 --- a/docs/registry/attributes/browser.md +++ b/docs/registry/attributes/browser.md @@ -3,6 +3,9 @@ # Browser +- [Browser Attributes](#browser-attributes) +- [Browser Resource Timing Attributes](#browser-resource-timing-attributes) + ## Browser Attributes The web browser attributes @@ -24,3 +27,42 @@ The web browser attributes **[4] `browser.platform`:** This value is intended to be taken from the [UA client hints API](https://wicg.github.io/ua-client-hints/#interface) (`navigator.userAgentData.platform`). If unavailable, the legacy `navigator.platform` API SHOULD NOT be used instead and this attribute SHOULD be left unset in order for the values to be consistent. The list of possible values is defined in the [W3C User-Agent Client Hints specification](https://wicg.github.io/ua-client-hints/#sec-ch-ua-platform). Note that some (but not all) of these values can overlap with values in the [`os.type` and `os.name` attributes](./os.md). However, for consistency, the values in the `browser.platform` attribute should capture the exact value that the user agent provides. + +## Browser Resource Timing Attributes + +Attributes for browser resource timing events + +**Attributes:** + +| Key | Stability | Value Type | Description | Example Values | +|---|---|---|---|---| +| `browser.resource_timing.connect_end` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately after the browser completes establishing the connection to the server [5] | `145.7`; `275.2` | +| `browser.resource_timing.connect_start` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately before the browser starts to establish the connection to the server [6] | `131.0`; `261.3` | +| `browser.resource_timing.domain_lookup_end` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately after the browser completes the domain name lookup for the resource [7] | `130.2`; `260.5` | +| `browser.resource_timing.domain_lookup_start` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately before the browser starts the domain name lookup for the resource [8] | `125.3`; `255.8` | +| `browser.resource_timing.fetch_start` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately before the browser starts to fetch the resource [9] | `120.5`; `250.75` | +| `browser.resource_timing.request_start` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately before the browser starts requesting the resource from the server [10] | `146.0`; `276.0` | +| `browser.resource_timing.response_end` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately after the browser receives the last byte of the resource [11] | `220.3`; `350.5` | +| `browser.resource_timing.response_start` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately after the browser receives the first byte of the response from the server [12] | `180.5`; `310.8` | +| `browser.resource_timing.secure_connection_start` | ![Development](https://img.shields.io/badge/-development-blue) | double | Time immediately before the browser starts the handshake process to secure the connection [13] | `132.5`; `262.8` | +| `browser.resource_timing.url` | ![Development](https://img.shields.io/badge/-development-blue) | string | Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986) [14] | `https://www.example.com/path`; `https://cdn.example.com/styles/main.css` | + +**[5] `browser.resource_timing.connect_end`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-connectend). + +**[6] `browser.resource_timing.connect_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-connectstart). + +**[7] `browser.resource_timing.domain_lookup_end`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-domainlookupend). + +**[8] `browser.resource_timing.domain_lookup_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-domainlookupstart). + +**[9] `browser.resource_timing.fetch_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-fetchstart). + +**[10] `browser.resource_timing.request_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-requeststart). + +**[11] `browser.resource_timing.response_end`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-responseend). + +**[12] `browser.resource_timing.response_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-responsestart). + +**[13] `browser.resource_timing.secure_connection_start`:** Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. If the scheme is not HTTPS, this value is 0. See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-secureconnectionstart). + +**[14] `browser.resource_timing.url`:** Generally the url doesn't include any query strings or any leading credentials, and it's formatted as scheme://full domain/path only, for example `https://www.example.com/path?a=b&c=d` would be sent as `https://www.example.com/path` by both removing any potential PII and reducing the cardinality of the name. diff --git a/model/browser/events.yaml b/model/browser/events.yaml index 00fedf7ee2..d0af96cea6 100644 --- a/model/browser/events.yaml +++ b/model/browser/events.yaml @@ -4,7 +4,7 @@ groups: type: event name: browser.web_vital brief: > - This event describes the website performance metrics introduced by Google, See [web vitals](https://web.dev/vitals). + This event describes the website performance metrics introduced by Google. See [web vitals](https://web.dev/vitals). body: id: browser.web_vital requirement_level: required @@ -28,7 +28,7 @@ groups: stability: development - id: inp value: 'inp' - brief: Interation to Next Paint. See [inp](https://web.dev/articles/inp). + brief: Interaction to Next Paint. See [inp](https://web.dev/articles/inp). stability: development stability: development brief: Name of the web vital. @@ -52,3 +52,37 @@ groups: brief: A unique ID representing this particular metric instance. requirement_level: required examples: ["v3-1677874579383-6381583661209"] + - id: event.browser.resource_timing + stability: development + type: event + name: browser.resource_timing + brief: > + This event describes the timing metrics as provided by PerformanceResourceTiming Performance API. + These metrics are related to fetching a resource, such as + XMLHttpRequest, Fetch, sendBeacon APIs, SVG, image or script. + note: > + This event captures data from the [ResourceTiming](https://www.w3.org/TR/resource-timing/). + It is recommended to be captured by using the PerformanceResourceTiming API. + If the page starts unloading before the page loads, + then the partial data can be captured by calling the [performance.getEntriesByType](https://developer.mozilla.org/en-US/docs/Web/API/Performance/getEntriesByType) method. + attributes: + - ref: browser.resource_timing.url + requirement_level: required + - ref: browser.resource_timing.fetch_start + requirement_level: recommended + - ref: browser.resource_timing.domain_lookup_start + requirement_level: recommended + - ref: browser.resource_timing.domain_lookup_end + requirement_level: recommended + - ref: browser.resource_timing.connect_start + requirement_level: recommended + - ref: browser.resource_timing.secure_connection_start + requirement_level: recommended + - ref: browser.resource_timing.connect_end + requirement_level: recommended + - ref: browser.resource_timing.request_start + requirement_level: recommended + - ref: browser.resource_timing.response_start + requirement_level: recommended + - ref: browser.resource_timing.response_end + requirement_level: recommended diff --git a/model/browser/registry.yaml b/model/browser/registry.yaml index 040f2d6838..ac9d593e8b 100644 --- a/model/browser/registry.yaml +++ b/model/browser/registry.yaml @@ -50,3 +50,94 @@ groups: This value is intended to be taken from the Navigator API `navigator.language`. examples: ["en", "en-US", "fr", "fr-FR"] + + - id: registry.browser.resource_timing + type: attribute_group + display_name: Browser Resource Timing Attributes + brief: > + Attributes for browser resource timing events + attributes: + - id: browser.resource_timing.url + type: string + stability: development + brief: 'Absolute URL describing a network resource according to [RFC3986](https://www.rfc-editor.org/rfc/rfc3986)' + note: > + Generally the url doesn't include any query strings or any leading credentials, + and it's formatted as scheme://full domain/path only, for example + `https://www.example.com/path?a=b&c=d` would be sent as + `https://www.example.com/path` by both removing any potential PII and + reducing the cardinality of the name. + examples: ['https://www.example.com/path', 'https://cdn.example.com/styles/main.css'] + - id: browser.resource_timing.fetch_start + type: double + stability: development + brief: 'Time immediately before the browser starts to fetch the resource' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-fetchstart). + examples: [120.5, 250.75] + - id: browser.resource_timing.domain_lookup_start + type: double + stability: development + brief: 'Time immediately before the browser starts the domain name lookup for the resource' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-domainlookupstart). + examples: [125.3, 255.8] + - id: browser.resource_timing.domain_lookup_end + type: double + stability: development + brief: 'Time immediately after the browser completes the domain name lookup for the resource' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-domainlookupend). + examples: [130.2, 260.5] + - id: browser.resource_timing.connect_start + type: double + stability: development + brief: 'Time immediately before the browser starts to establish the connection to the server' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-connectstart). + examples: [131.0, 261.3] + - id: browser.resource_timing.secure_connection_start + type: double + stability: development + brief: 'Time immediately before the browser starts the handshake process to secure the connection' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + If the scheme is not HTTPS, this value is 0. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-secureconnectionstart). + examples: [132.5, 262.8] + - id: browser.resource_timing.connect_end + type: double + stability: development + brief: 'Time immediately after the browser completes establishing the connection to the server' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-connectend). + examples: [145.7, 275.2] + - id: browser.resource_timing.request_start + type: double + stability: development + brief: 'Time immediately before the browser starts requesting the resource from the server' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-requeststart). + examples: [146.0, 276.0] + - id: browser.resource_timing.response_start + type: double + stability: development + brief: 'Time immediately after the browser receives the first byte of the response from the server' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-responsestart). + examples: [180.5, 310.8] + - id: browser.resource_timing.response_end + type: double + stability: development + brief: 'Time immediately after the browser receives the last byte of the resource' + note: > + Measured in milliseconds as a DOMHighResTimeStamp relative to the time origin. + See the [Performance Resource Timing API](https://www.w3.org/TR/resource-timing-2/#dom-performanceresourcetiming-responseend). + examples: [220.3, 350.5]