From c14d2d23587c6952a456239eb9808fad98b0b565 Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Sat, 15 Feb 2025 11:32:47 -0800 Subject: [PATCH 1/2] add browser.page_view event --- docs/browser/events.md | 51 ++++++++++++++++++++++++++++++++++++ model/browser/events.yaml | 55 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 docs/browser/events.md create mode 100644 model/browser/events.yaml diff --git a/docs/browser/events.md b/docs/browser/events.md new file mode 100644 index 0000000000..f762bd64f1 --- /dev/null +++ b/docs/browser/events.md @@ -0,0 +1,51 @@ + + +# Semantic conventions for Browser events + +**Status**: [Development][DocumentStatus] + +This document defines semantic conventions for browser (web) instrumentations +that emit events. + +## Page View Event + + + + + + + + +**Status:** ![Development](https://img.shields.io/badge/-development-blue) + +The event name MUST be `browser.page_view`. + +This event represents a browser page load/view. + +The primary use case is to capture metrics about the number of views of a page. Page view can be a hard page load in a browser as well as virtual navigation in a SPA (single-page application). The event should be collected as soon as possible without waiting for potentially delayed data such as the Navigation timing browser API. + +**Body fields:** + +| Body Field | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| `change_state` | string | Type of state change used for the virtual page navigation | `pushState`; `replaceState` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `referrer` | string | Referring Page URI (document.referrer) whenever available. | `https://en.wikipedia.org/wiki/Main_Page` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `title` | string | Page title DOM property | `Home`; `Checkout` | `Recommended` | ![Development](https://img.shields.io/badge/-development-blue) | +| `type` | enum | Type of navigation | `0`; `1` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | +| `url` | string | Full HTTP request URL in the form scheme://host[:port]/path?query[#fragment]. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. | `https://en.wikipedia.org/wiki/Main_Page`; `https://en.wikipedia.org/wiki/Main_Page#foo` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) | + +`type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. + +| Value | Description | Stability | +|---|---|---| +| `0` | Initial page load within the browser which will generally also precede a PageNavigationTiming event. | ![Development](https://img.shields.io/badge/-development-blue) | +| `1` | This is for Single Page Applications (SPA) where the framework provides the ability to perform client side only page "navigation", the exact definition of what a virtual page change is determined by the SPA and the framework it is using. | ![Development](https://img.shields.io/badge/-development-blue) | + + + + + + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/browser/events.yaml b/model/browser/events.yaml new file mode 100644 index 0000000000..f4be75f286 --- /dev/null +++ b/model/browser/events.yaml @@ -0,0 +1,55 @@ +groups: + - id: event.browser.page_view + stability: development + type: event + name: browser.page_view + brief: > + This event represents a browser page load/view. + note: > + The primary use case is to capture metrics about the number of views of a page. Page view can be a hard page load in a browser as well as virtual navigation in a SPA (single-page application). The event should be collected as soon as possible without waiting for potentially delayed data such as the Navigation timing browser API. + body: + id: browser.page_view + requirement_level: required + stability: development + type: map + fields: + - id: referrer + type: string + stability: development + brief: Referring Page URI (document.referrer) whenever available. + requirement_level: recommended + examples: ["https://en.wikipedia.org/wiki/Main_Page"] + - id: type + type: enum + members: + - id: physical_page + value: 0 + stability: development + brief: Initial page load within the browser which will generally also precede a PageNavigationTiming event. + - id: virtual_page + value: 1 + stability: development + brief: This is for Single Page Applications (SPA) where the framework provides the ability to perform client side only page "navigation", the exact definition of what a virtual page change is determined by the SPA and the framework it is using. + stability: development + requirement_level: required + brief: Type of navigation + examples: [0, 1] + - id: title + type: string + stability: development + requirement_level: recommended + brief: Page title DOM property + examples: ["Home", "Checkout"] + - id: url + type: string + stability: development + requirement_level: required + brief: > + Full HTTP request URL in the form scheme://host[:port]/path?query[#fragment]. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. + examples: ["https://en.wikipedia.org/wiki/Main_Page", "https://en.wikipedia.org/wiki/Main_Page#foo"] + - id: change_state + type: string + stability: development + requirement_level: recommended + brief: Type of state change used for the virtual page navigation + examples: ["pushState", "replaceState"] From 23003358584855d127e45e30deb7aa795fcf2dcd Mon Sep 17 00:00:00 2001 From: Martin Kuba Date: Mon, 17 Feb 2025 20:48:59 -0800 Subject: [PATCH 2/2] fix yaml lint --- model/browser/events.yaml | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/model/browser/events.yaml b/model/browser/events.yaml index f4be75f286..d8ba88bff8 100644 --- a/model/browser/events.yaml +++ b/model/browser/events.yaml @@ -6,7 +6,11 @@ groups: brief: > This event represents a browser page load/view. note: > - The primary use case is to capture metrics about the number of views of a page. Page view can be a hard page load in a browser as well as virtual navigation in a SPA (single-page application). The event should be collected as soon as possible without waiting for potentially delayed data such as the Navigation timing browser API. + The primary use case is to capture metrics about the number of views of + a page. Page view can be a hard page load in a browser as well as virtual + navigation in a SPA (single-page application). The event should be + collected as soon as possible without waiting for potentially delayed + data such as the Navigation timing browser API. body: id: browser.page_view requirement_level: required @@ -25,11 +29,17 @@ groups: - id: physical_page value: 0 stability: development - brief: Initial page load within the browser which will generally also precede a PageNavigationTiming event. + brief: > + Initial page load within the browser which will generally also + precede a PageNavigationTiming event. - id: virtual_page value: 1 stability: development - brief: This is for Single Page Applications (SPA) where the framework provides the ability to perform client side only page "navigation", the exact definition of what a virtual page change is determined by the SPA and the framework it is using. + brief: > + This is for Single Page Applications (SPA) where the framework + provides the ability to perform client side only page + "navigation", the exact definition of what a virtual page + change is determined by the SPA and the framework it is using. stability: development requirement_level: required brief: Type of navigation @@ -45,7 +55,9 @@ groups: stability: development requirement_level: required brief: > - Full HTTP request URL in the form scheme://host[:port]/path?query[#fragment]. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. + Full HTTP request URL in the form scheme://host[:port]/path?query[#fragment]. + Usually the fragment is not transmitted over HTTP, but if it is + known, it should be included nevertheless. examples: ["https://en.wikipedia.org/wiki/Main_Page", "https://en.wikipedia.org/wiki/Main_Page#foo"] - id: change_state type: string