Skip to content

Proposal: add initial proposal for browser observability model events#6

Merged
joaquin-diaz merged 6 commits into
open-telemetry:mainfrom
embrace-io:joaquin-diaz/chore/docs-browser-observability
Oct 16, 2025
Merged

Proposal: add initial proposal for browser observability model events#6
joaquin-diaz merged 6 commits into
open-telemetry:mainfrom
embrace-io:joaquin-diaz/chore/docs-browser-observability

Conversation

@joaquin-diaz
Copy link
Copy Markdown
Contributor

Proposal: Browser Lifecycle Events

Adds a conceptual model for browser lifecycle events, organized into Load, User Interaction, and Unload phases. Includes an event list with purpose, frequency, and status for both semantic conventions and instrumentation.

Goal

Standardize browser telemetry interpretation and guide instrumentation authors.

@joaquin-diaz joaquin-diaz requested a review from a team as a code owner September 18, 2025 13:32
Copy link
Copy Markdown
Contributor Author

@joaquin-diaz joaquin-diaz left a comment

Choose a reason for hiding this comment

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

@martinkuba

Should we include sessions in this document as well? By lifecycle, do we mean only lifecycle of an HTML document/page, or all the things that happen while the user is using a browser app?


@martinkuba, @BenoitZugmeyer I manually copied all the comments from the other PR so I can answer here, sorry for the mess!

Comment thread docs/browser-observability-model.md Outdated
Comment thread docs/browser-observability-model.md Outdated
Comment thread docs/browser-observability-model.md Outdated
Comment thread docs/browser-observability-model.md Outdated
Comment thread docs/browser-observability-model.md Outdated

### Load Phase

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

Choose a reason for hiding this comment

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

@BenoitZugmeyer

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.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Yeah, probably best to keep it simple for now. I still believe that LCP is important for page load but we can have that conversation later

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Sounds great!

Comment thread docs/browser-observability-model.md Outdated

### User Interaction Phase

**Starts after LCP → Ends when the page begins unloading**
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

@BenoitZugmeyer

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)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I tried to organize the model in phases thinking that it would be easier to have a clear distinction on what's going on but now I see that it probably generates more confusion than clarity. I'll go back to just having a list of events

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks good!

@joaquin-diaz joaquin-diaz changed the title Proposal: add initial proposal for browser observability model Proposal: add initial proposal for browser observability model events Sep 18, 2025
Comment thread docs/browser-observability-model.md Outdated
Comment thread docs/browser-observability-model.md Outdated
Comment thread docs/browser-observability-model.md Outdated

### Load Phase

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

Choose a reason for hiding this comment

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

Sounds great!

Comment thread docs/browser-observability-model.md Outdated

### User Interaction Phase

**Starts after LCP → Ends when the page begins unloading**
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks good!

Comment thread docs/browser-observability-model.md Outdated
Comment thread docs/browser-observability-model.md Outdated
@martinkuba
Copy link
Copy Markdown
Contributor

This PR is related to issue #7

Copy link
Copy Markdown
Contributor

@martinkuba martinkuba left a comment

Choose a reason for hiding this comment

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

This looks good to me to merge. We can continue to revise it if needed later on.

Comment thread docs/browser-observability-model.md
@joaquin-diaz joaquin-diaz force-pushed the joaquin-diaz/chore/docs-browser-observability branch from c3a8546 to 0e1d9fd Compare October 16, 2025 14:52
joaquin-diaz and others added 6 commits October 16, 2025 11:54
… derivated events and keep events that can be mapped to browser events
Co-authored-by: Benoît <bzugmeyer@gmail.com>
Co-authored-by: Benoît <bzugmeyer@gmail.com>
…_timing, rename browser.visibility_changed to browser.page.visibility_state
@joaquin-diaz joaquin-diaz force-pushed the joaquin-diaz/chore/docs-browser-observability branch from 0e1d9fd to 9c568ab Compare October 16, 2025 14:55
@joaquin-diaz joaquin-diaz merged commit a8642a7 into open-telemetry:main Oct 16, 2025
1 check passed
@joaquin-diaz joaquin-diaz deleted the joaquin-diaz/chore/docs-browser-observability branch October 16, 2025 14:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants