Skip to content

Proposal: browser lifecycle events doc #4

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

Closed
wants to merge 1 commit into from
Closed

Proposal: browser lifecycle events doc #4

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
1 change: 1 addition & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
.idea
74 changes: 74 additions & 0 deletions docs/browser-lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Browser Lifecycle Events

This document defines a set of browser events organized into three high-level lifecycle phases.

It focuses on the **purpose and relationships of events within the browser lifecycle**, rather than defining their individual attributes (which are specified in their respective semantic convention documents).

---

## Goals

The purpose of this document is to:

- Provide a **conceptual lifecycle model** for browser telemetry.
- Define **which events are expected in each phase** of a page lifecycle.
- Help instrumentation authors and data consumers **reason about browser behavior from load to unload**.
- Clarify the **purpose and relationships of events without defining their individual attributes**, which are specified in their respective semantic convention documents.

This structure ensures that browser-related events can be consistently interpreted across implementations.

---

## Lifecycle

The browser lifecycle is divided into the following phases:

1. **Load phase** – from navigation start to Largest Contentful Paint (LCP)
2. **User interaction phase** – from LCP until the page begins unloading
3. **Unload phase** – when the page begins unloading

---

## Lifecycle Phases

### Load Phase

**Starts at navigation start → Ends at Largest Contentful Paint (LCP)**
Copy link
Contributor

@BenoitZugmeyer BenoitZugmeyer Sep 16, 2025

Choose a reason for hiding this comment

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

suggestion: I would avoid using the LCP as a structuring part of the model:

  • it's not supported in all browsers (ex: Safari)
  • It implies that we actually wait for a user interaction before going to the next phase, since LCP entries are notified until a user interaction happens (the Core Web Vital LCP is the time until the latest LCP). This could be problematic on pages that don't have user interactions (ex: a page opened in background).
  • LCP can happen before the page actually finishes to load (before the load event), so correlating to the "Load" phase could be confusing.

Captures the loading behavior and performance of the page.

| Event | Description | Semantic Conventions Status | Instrumentation Status |
|---|---|---|------------------------------------------------------------------------------------------------------------------------------------------------------|
| `browser.page_view` | Signals the start of a **hard** page navigation. Occurs once per page load. | In review [PR1910](https://github.com/open-telemetry/semantic-conventions/pull/1910) | In review [PR2386](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2386) |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

I would be in favor of calling this navigation event (as proposed here). It would make it clear that it is based on a foundational browser event and aligns with the Web APIs terminology (Navigation timing, Navigate event).

Page view seems more like a derived concept. It is not a term used in the browser spec/terminology. I do concede that it is used in various analytics products, but I am not sure if it has exactly the same meaning everywhere. The name also implies that the user actually saw the page, but that may not always be the case. For example, if the page is loading in a hidden tab, is it still a page view?

| `browser.navigation_timing` | Captures detailed technical milestones from the [PerformanceNavigationTiming](https://developer.mozilla.org/docs/Web/API/PerformanceNavigationTiming) API. Occurs once per page load. | In review [PR1919](https://github.com/open-telemetry/semantic-conventions/pull/1919) | Not created |
| `browser.page_load` | Summarizes the user-visible page load experience from navigation start until LCP (includes total duration, paint timings, resource counts, transfer size). Occurs once per page load. | Not created | Not created |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025

Choose a reason for hiding this comment

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

Is the main intent of this event to summarize all the other events that happen during page load to make it easier for backends?

Alternatively

  • duration is part of navigation timing (if based on the window load event)
  • FCP and LCP are part of web vitals
  • resource counts could be determined from resource timing data
  • transfer size is available in resource timing data

| `browser.performance_resource_timing` | Captures information about individual resources loaded during the initial page load, from the [PerformanceResourceTiming](https://developer.mozilla.org/docs/Web/API/PerformanceResourceTiming) API. May occur multiple times per page load. | Not created | Merged (similar) [instrumentation-document-load](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-document-load) |

---

### User Interaction Phase

**Starts after LCP → Ends when the page begins unloading**
Captures user-centric metrics, runtime behavior, and late resource loading.
Comment on lines +50 to +51
Copy link
Contributor

@BenoitZugmeyer BenoitZugmeyer Sep 16, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

suggestion: some events listed in this phase could also belong to the Loading phase, ex: logs, errors... (I'd say also 'user interaction', as a user can interact with a loading page, but it depends on how we determine when the "load" phase ends)


**All events in this phase may occur multiple times.**

| Event | Description | Semantic Conventions Status | Instrumentation Status |
|---|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `browser.page_view` | Represents a **soft navigation** (SPA virtual page change). | In review [PR1910](https://github.com/open-telemetry/semantic-conventions/pull/1910) | In review [PR2386](https://github.com/open-telemetry/opentelemetry-js-contrib/pull/2386) |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Would this be used only for navigations that follow the soft navigation heuristics? Or, would it be used for any URL change? Or, would it be used for logical page views that may or may not have a URL change?

| `browser.web_vital` | Captures Web Vitals metrics such as CLS, INP, and FID that occur after page load. | Merged [WebVitals](https://opentelemetry.io/docs/specs/semconv/browser/events/#webvital-event) | Not created |
| `browser.error` | Captures unhandled JavaScript errors. | Not created | Not created |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025

Choose a reason for hiding this comment

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

There is an existing PR for instrumentation here that @wolfgangcodes is taking over (I think). It uses the existing exception.* semantic conventions.

| `browser.console` | Captures browser console messages such as warnings and logs. | Not created | Not created |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025

Choose a reason for hiding this comment

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

Instrumentation to capture console logs as OTel logs · Issue #1560 · open-telemetry/opentelemetry-js-contrib

| `browser.user_interaction` | Captures user input events (clicks, scrolls, keypresses) and their latency. | Not created | Not created |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025

Choose a reason for hiding this comment

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

There is an existing PR here (also from @Karlie-777).

| `browser.performance_resource_timing` | Captures late-loaded assets (ads, analytics, lazy images, etc.). | Not created | Merged (similar) [instrumentation-document-load](https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-document-load) |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025

Choose a reason for hiding this comment

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

@Karlie-777 has an existing PR for semantic conventions here.


---

### Unload Phase

**Starts when the user initiates a navigation away, closes the tab, or reloads**
Captures the start of the unload process.

| Event | Description | Semantic Conventions Status | Instrumentation Status |
|---|---|---|---|
| `browser.page_unload` | Signals the start of the page unload process. Occurs once per page unload. | Not created | Not created |
Copy link
Contributor

@martinkuba martinkuba Sep 15, 2025

Choose a reason for hiding this comment

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

I am not sure if this event is necessary. What value would it provide?

Copy link
Contributor

@BenoitZugmeyer BenoitZugmeyer Sep 16, 2025

Choose a reason for hiding this comment

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

It could help to determine when the active "Page View" ends, to spend the time spent each view. I think it could be a good thing in theory, but I'm questioning about the reliability of such event, where browsers are not always emitting unload or pagehide events. Users might not understand why this event isn't always present.

Copy link
Contributor

@martinkuba martinkuba Sep 16, 2025

Choose a reason for hiding this comment

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

The unload event is basically deprecated and should not be used due to bfcache. The pagehide event fires also when a document is put into bfcache, which means that the same document can be restored. This implies that it can have a more complex lifecycle than just unload.

Copy link
Contributor

@martinkuba martinkuba Sep 16, 2025

Choose a reason for hiding this comment

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

There is also the visibilitychanged event. This does not indicate the end of a document lifecycle (page view?), but could be useful to understand when the user is actually on the page.