Handling mutable entities (sessions, page views)

[martinkuba]

Background

In browser (and mobile) applications, key entities change during the SDK's lifetime:

• Session: rotates on inactivity timeout or max duration (~30 min). Represented by session.id.
• Page view / route: changes on every soft navigation in SPAs. Represented by page URL or route.
• User: may change on login/logout.

These entities are contextual — they apply to all telemetry produced by the SDK, which makes Resource the semantically correct place for them. However, the OTel specification requires Resources to be immutable. This applies to all signals. In addition, for metrics, the spec also defines resources as part of metric stream identity.

This discussion explores how client SDKs should handle mutable entities across all signals, with particular attention to the impact on metrics.

The problem

When an entity changes in the browser, the new entity must replace the previous one for all telemetry generated by the SDK — all instrumentations and user code must start producing telemetry associated with the new entity, and the old entity is no longer valid.

However, replacing a resource is not possible per spec, and creating a new provider for each entity change has implications that differ by signal type.

logs and traces

Logs and traces are stateless emitters — each emit() or span creation is independent. A proxy pattern (like EntityAwareLoggerProvider) can handle entity replacement by swapping the underlying delegate provider when the entity changes. Instrumentation references remain valid, and each emission resolves to the current entity. We have a working prototype of this approach for logs.

metrics

A proxy pattern similar to logs/traces can work for metrics — proxy instruments delegate to the current real instruments, which are swapped when the entity changes. It's more involved (more proxy classes, flushing old aggregation state) but solvable.

The other (and more important) issue is that the OTel spec defines metric stream identity as (Resource, Scope, Name). Replacing the entity means the Resource changes, which means the metric stream's identity changes. In practice, the impact depends on the backend:

• In the SDK: Resource is not part of the aggregation key — aggregation is keyed only by instrument name and data point attributes. Swapping the Resource doesn't affect how counters or histograms work internally.
• In Prometheus (default): Most Resource attributes are not used as dimensions (service.name -> job and service.instance.id -> instance are the only ones promoted by default). Changing other Resource attributes like session.id is invisible to Prometheus.
• In OTLP-native backends: Some backends may use the full Resource for identity, routing, or deduplication. Changing it mid-stream is undefined behavior.

So the identity issue is a spec-level contract concern rather than a practical aggregation problem for most backends.

Possible approaches

Option 1: Clarify the spec

Define in the specification what consumers should do when Resource attributes change for a metric stream — e.g., by distinguishing "identifying" vs. "descriptive" Resource attributes (as proposed in OTEP 264). This would make entity replacement for metrics a supported pattern, but requires spec consensus and backend adoption.

Option 2: Exclude mutable attributes from the metrics Resource

Sidestep the identity problem by keeping mutable entity attributes off the metrics Resource entirely. Give the MeterProvider a static Resource containing only immutable attributes (service.name, telemetry.sdk.version, etc.). Session ID and other entity attributes would still be on the LoggerProvider and TracerProvider Resources, where entity replacement works with the proxy pattern.

For entity attributes that are useful as metric dimensions (e.g., page URL for "page views per route"), the SDK would inject them as data point attributes at record time rather than putting them on the Resource:

// Explicit — instrumentation passes the value
counter.add(1, { 'page.url': getCurrentRoute() });

// Or automatic injection — SDK resolves current entity values
counter.add(1); // SDK automatically attaches current page.url

This keeps the Resource immutable, avoids MeterProvider recreation, and lets aggregation work naturally (different attribute values = different series).

Option 3: Use events instead of metrics

Avoid the metrics identity problem altogether by not using the Metrics SDK for client-side telemetry. Instead, send measurements as log events and generate metrics downstream (e.g., in the Collector using connectors like signaltometrics). Entity attributes are simply event attributes — no Resource immutability constraints apply.

The downside is that this creates friction for teams without Collector access or who want to use familiar metric instruments (counters, histograms) in their application code.

Open questions

1. Automatic attribute injection mechanism: If using Option 2, what is the right mechanism for automatically injecting entity attributes as data point attributes?

2. Cross-signal correlation: If metrics exclude session ID from their Resource but logs/traces include it, how do you correlate metrics with logs/traces for the same session? Is there a use case for this?

3. Relationship to OTEP 4665: The entity proposal focuses on forEntity() which creates new providers. Option 2 proposes a different pattern (static Resource + data point attribute injection). Should the entity proposal account for this, or should this be a client SDK-specific solution?

[joaquin-diaz]

Automatic attribute injection mechanism: If using Option 2, what is the right mechanism for automatically injecting entity attributes as data point attributes?

Isn't that what we trying to avoid by grouping all common attributes in the entity? Or what you're saying is that we avoid using entities at all with option 2?

Relationship to open-telemetry/opentelemetry-specification#4665: The entity proposal focuses on forEntity() which creates new providers.

My concern in this pattern is how do we deal with having multiple entities? Let's say we have a session entity, page entity and user entity. All that contextual most likely applies to all events / metrics. Then:

1. How do we use forEntity or setEntity in this case when any attribute of session, page or user changes? Do we always merge them into a single entity?
2. For events each entity attribute creates a new dimension (group all web vitals by page, filter all clicks by session id, etc). In the case of metrics, can you decide what do you use to aggregate? For example, if we count clicks and we switch the provider entity every time there's a new page, would you be able count clicks by session or clicks by user besides clicks by page?

[martinkuba]

Or what you're saying is that we avoid using entities at all with option 2?

The idea with option 2 is that for metrics the resource would not include the mutable entity attributes. But then what if I want one of these attributes to be a metric dimension? The SDK could automatically add them to the measurement attributes - this does not break the immutable resource requirement, doesn't force us to create a new provider every time the entity changes. It just gets reflected in new measurements.

How do we use forEntity or setEntity in this case when any attribute of session, page or user changes?

There would have to be some mechanism that keeps track of all entities, and every time something changes, it re-creates the resource. Something like what I prototyped here.

In the case of metrics, can you decide what do you use to aggregate?

If we wanted to be explicit about this in the SDK, then we'd have to do something like option #2. Or the backend would have to do it by picking what it wants from the resource attributes.

[thompson-tomo]

So my cents if I was to implement a solution which includes ability to have spec changes.

• we capture atleast the identifying attributes of the page as scope attributes & have resource remain constant. This would be your page etc.
• we add entities to scopes via spec change.
• we potentially use a secondary channel to feed details of the entities to backends or add the data via the collector.
• for metrics we define attributes in the time-series model must/should include the identifying scope attributes in addition to the data point attributes.

That way we avoid the complexity of switching providers and we use the existing getMeter method passing in the scope attributes.

For session, I get the feeling it might be better to specify the session id as a field alongside span-id and use a strongly defined log record to transfer the details of the session to a back end. This way we can define the special handling of the session including creating links

[mquentin]

I'm a fan of the entity concept as a mutable resource: having a semantic for sharing properties between logs and spans is a neat feature for reducing payload size. And not all shared
properties are immutable — session.id is the perfect example — so we do need this notion of a mutable resource, i.e. an entity.

My only concern is the rate of mutation of some entities. If an entity changes too often — for instance browser.document.url.full, which mutates on every query-param update, every
pushState, etc. — you end up with a huge number of resource partitions. That's the opposite of the original goal of resources: have as few resource partitions as possible, with as many
records as possible sharing the same resource attributes.

I raised this as a problem statement in #269 (comment).

So I think we should document and clarify in the specs somehow what makes a good entity (like session.id) versus a bad one (like browser.document.url.full).