Events breadcrumbs: introduce a context identifier

[BenoitZugmeyer]

Overview

The existing session.id attribute allows grouping all events generated by the same end user during a single session. This is useful for correlating telemetry associated with a specific instance of an error or performance issue.

However, the session.id is often not granular enough. A web application can be opened in multiple tabs or windows, or may contain iframes. In those cases, all documents share the same session.id, and telemetry coming from these different browser contexts becomes intertwined. This makes difficult to debug issues that occur in a specific document (for example, understanding why one particular page load was slow when multiple pages were open simultaneously).

To address this, I propose to introduce a new attribute to group events emitted within the same browser context. This attribute would initially be defined as an event attribute until entities are stabilized, similarly to session.id.

Goals

• Provide a stable identifier that groups all events belonging to a single browser document or navigation.

• Avoid conflating telemetry from separate tabs, windows, or iframes.

• Remain consistent with existing OTel concepts where possible.

Proposals

I have three different suggestions, with slightly different implications:

• app.screen.id: this attribute is already standardized and could be a good fit for abstracting the concept across multiple platforms. We could consider that each navigation leads to a different 'screen'. We would create a new random id on each browser.navigation event and assign it to all subsequent events.

• browser.navigation.id: following the same idea, that attribute could have a name closer to the browser concept. However, we would miss cross-platform consistency.

• browser.document.id: this attribute would be scoped to the lifetime of a document (the document concept is being introduced by the browser.navigation event). This id would be less granular, as we wouldn't be able to list events happening between navigations.

Follow ups

Some thoughts that are out of the scope of this proposal:

• We could imagine having xxx.previous_id and/or xxx.parent_id properties to link contexts together

• It's sometimes interesting for users to name those contexts (ex: "Login page", "Checkout"...). Something similar to app.screen.name could be interesting.

[thompson-tomo]

Not sure if it has been discussed previously but

This makes difficult to debug issues that occur in a specific document (for example, understanding why one particular page load was slow when multiple pages were open simultaneously).

Would it make sense to have a navigation span which enables the events to be linked to the span? There has been in the past some attempts to define these navigation spans.

Provide a stable identifier that groups all events belonging to a single browser document or navigation.

These seem to be different & contradictory. If a user opens the same url twice or more during a session should the new id be the same? If id changes then it would be describing the navigation and not document. But if the same id then it is the opposite.

I think app.page.id would be more fitting then app.screen.id and aligns with existing web terminology. It could also be used in apps.

For browser.navigation.id we could go with app.navigation.id but still wonder if we shouldn't have a navigation span and link it that way.

---

I think a key objective is to have an explainer showing what the definition of a screen, widget & page is and how they are used.

[BenoitZugmeyer]

Would it make sense to have a navigation span which enables the events to be linked to the span? There has been in the past some attempts to define these navigation spans.

From a model perspective, yes I think it could make sense. But from my understanding the client library sends the span at the end, after it finishes. This could be challenging in the browser as sending data when the page is unloading is unreliable by nature.

These seem to be different & contradictory. If a user opens the same url twice or more during a session should the new id be the same? If id changes then it would be describing the navigation and not document. But if the same id then it is the opposite.

The id would change. The document refers to the Document instance, as mentioned here. Loading the same URL twice leads to two document instances, so two distinct id.

app.page.id app.navigation.id

I'm not against it! Let's wait for more feedback.

[martinkuba]

navigation.id -
I don't think we should use navigation.id for this because navigation represents the transition between documents or URL states. Is there a real use case for changing this ID when URL changes in the same document?

page.id -
I think page.id would be acceptable since it is a widely used term. But IMO, there is a slight difference between page and document in that page represents the whole tab, which could have multiple documents in it (with iframes). Page is the more logical and user-centric concept, and document is more specific and technical.

document.id -
IMO, this is most accurate - document is a term used in the browser/web APIs terminology (e.g. Document interface, same-document navigation). It might not be clear whether it represents the resource or the document instance that the browser creates. So, maybe we could consider document.instance.id?

[thompson-tomo]

From a model perspective, yes I think it could make sense. But from my understanding the client library sends the span at the end, after it finishes. This could be challenging in the browser as sending data when the page is unloading is unreliable by nature.

Correct for span events but I don't think that is the case for log events as the linkage to trace/span is just fields rather than being nested objects.

Agree app.document.instance.id might be the better attribute name of the current suggestions, but other options we could go with would be app.fragment.instance.id or app.partial.instance.id.

If we need/want to be able to link events generated outside of the navigation period, the attribute would be the solution rather than span.

[BenoitZugmeyer]

@martinkuba

I don't think we should use navigation.id for this because navigation represents the transition between documents or URL states. Is there a real use case for changing this ID when URL changes in the same document?

I suggested navigation.id because "navigation" superseded the "page_view" concept. At Datadog we visualize RUM data grouped by "page_view", which is essentially what's happening between two hard/soft navigations. This is useful, because it gives a "scope" to the user: they can visualize all telemetry (errors, logs, resources, web vitals...) that happen on a page_view instance, between two navigations.

IMO, this is most accurate - document is a term used in the browser/web APIs terminology (e.g. Document interface, same-document navigation). It might not be clear whether it represents the resource or the document instance that the browser creates. So, maybe we could consider document.instance.id?

I'd be fine with document.instance.id. This is the minimal information we need to link related telemetry.

---

@thompson-tomo

Correct for span events but I don't think that is the case for log events as the linkage to trace/span is just fields rather than being nested objects.

If we need/want to be able to link events generated outside of the navigation period, the attribute would be the solution rather than span.

I see! Yes, we want to link events generated outside of the "navigation period". Essentially all events would have this identifier. So I agree that an event attribute would be a better fit than a span.

[thompson-tomo]

In that case attribute it is.

Thinking about it some more, I like app.partial.id as we could have a mapping like so:

term	Description	app	web
window	represent what is currently being shown including the menus	the window	the browser
page	a collection of partials which shows content to a user	activity	page hard navigated to
partial	a reusable collection of html elements which has a life cycle	fragment	component/iframe
widget	an element which can be interacted with	ui element	html element

This would mean that the app sig would need to agree to renaming their screen events to app.window.*, add the app.page.attributes & rename app.screen.id/name to app.window.id/name.

But I think this gives us a good model of what makes up the content being shown.

[andydavies]

navigation.id -
I don't think we should use navigation.id for this because navigation represents the transition between documents or URL states.

Chrome is moving towards including navigationId as an identifier for both hard or soft navigations and then using it to associate other performance timeline entries with the navigation.

You'll need to enable experiments in Canary to see it, but this is an example using example.com:

ATM it's not clear yet whether navigationId will also be exposed via the NavigationAPI though

Is there a real use case for changing this ID when URL changes in the same document?

From a decade of building RUM products (but only recently having an interest in OTel) I'd agree with @BenoitZugmeyer that the RUM mental model is about capturing what happens between two navigations regardless of whether their are hard or soft