Add specification for managing sessions

[martinkuba]

Client instrumentations have a concept of a session that spans many traces and events/logs. Per semantic conventions, sessions are currently handled by adding a session.id attribute to all spans and logs.

Web and mobile instrumentations are in the process of implementing a mechanism for managing sessions.

• Session handling implementation opentelemetry-js-contrib#2358
• Refactor session handling opentelemetry-android#564

We would like for these implementations to be consistent, so that users have the same predictable interfaces for configuring and interacting with sessions.

Some concerns that the spec might describe:

• when is a session started and ended (e.g. max duration, inactivity)
• how is session ID generated
• how is session persisted across SDK instances
• how can user code interact with sessions

I am looking for guidance on whether something like this should be documented in the spec, and if yes, where it should go.

[lmolkova]

It seems to be semantic-convention concern to document session attributes and events including who/how/when they are reported.

E.g. https://github.com/open-telemetry/semantic-conventions/blob/main/docs/messaging/messaging-spans.md can be used as an example that gives an intro into the messaging domain and goes beyond formal attribute/span definition.

I can imagine a browser/client semconv that document overall session lifecycle and give guidance to instrumentations and users on how to emit telemetry.

Spec changes would be needed if there is something existing in the spec that needs changes/clarifications or if there is a new API/concept we need to add to the spec.

I'd start with semconv definition and follow up with specific spec changes if they are necessary.

[dyladan]

I assume that sessions will be defined as attributes on our existing data structures (events, resources, entities, etc). This seems to be asking if we need a convenience API on top of that in order to make it simpler to manage sessions, but I don't see that as any different than a convenience API on any other semconv (HTTP requests for example). I do think we should have a conversation about convenience APIs for semconv in general, but don't see this one as any different than any other. In any case, the semconv should be defined before any API like that is considered.

[martinkuba]

@lmolkova @dyladan Thanks for your feedback. This issue is in fact about an API that users would use to configure sessions behavior and interact with sessions. There are already semantic conventions for sessions (session IDs and start/end events).

@dyladan If I understand correctly, convenience APIs are not documented in the specification repo, even if it was desirable for different language SDKs to implement them the same way?

FWW, the design was discussed in this issue, but here is a quick summary:

In summary:

• session.id attribute is added by span/logrecord processors
• these processors have a dependency on SessionProvider interface in order to have access to the active session
• we provide a default implementation of SessionProvider (here called SessionManager)
• SessionManager allows users to configure how the session ID is generated and where it's stored
• SessionManager also implements SessionPublisher interface, which allows external components to be notified when a session starts/ends

If we want to follow this pattern in different client SDKs (web, Android, Swift), should this be documented somewhere?

[dyladan]

OK yeah I remember the JS issue thanks for the link and explanation

This issue is in fact about an API that users would use to configure sessions behavior and interact with sessions

It was my understanding that the session manager component would not be interacted with directly by users after initial configuration? Is this incorrect?

Instrumentations and end users should not directly interact with SDK components. If we need an API for end-users to call during the regular course of the application it should be in the API and therefore in the spec IMO.

[martinkuba]

It was my understanding that the session manager component would not be interacted with directly by users after initial configuration? Is this incorrect?

In this design, there is no need to interact with the session manager after it is configured. The only thing the user can do is attach an observer, which is notified when a session state changes. The observer methods give access to a Session object, which might need to be part of the API, I suppose.

With that said, it is possible that a user might want to start/end sessions manually. In this design, they could implement their own SessionProvider. The SessionManager is really just a default implementation of SessionProvider that we think would cover most use cases. We (client SIG) have not yet explored more complex use cases, but it is possible that it could evolve.

[lmolkova]

thanks for the context! btw do you expect it to be cross-language feature or JS-specific?

[martinkuba]

I expect it would be implemented by the Android and Swift SDKs in addition to JS.

[svrnm]

this issue has stalled, are there any updates? What is required to move it forward?

[martinkuba]

The intent of this issue was to determine whether we need specification for something like this (as suggested by @danielgblanco). I am happy to work on this in the future, but currently I do not have the capacity to move it forward. My primary goal is to implement this in the Javascript SDK for web, so I think I will focus on working on a prototype in JS first. After we get some feedback from users there, I can come back to help with this spec.

[danielgblanco]

I think I will focus on working on a prototype in JS first

This sounds reasonable. Thanks.

Elaborating on what @lmolkova mentioned above regarding semconv going beyond purely defining the "what" and also going into the "how". In this case, would it make sense as a next step (after prototype) to propose an addition to the session semconv doc to include aspects related to the desired behaviour of languages that implement this semconv? e.g. "users should be able to configure how session IDs are generated via...".

Would you envision the end-user interacting with a new SDK concept to configure sessions, or with existing concepts i.e. implementations of Log/SpanProcessor that allow to configure how sessions are generated? For instance (unrelated example), the Java implementations of SpanProcessor like the BaggageSpanProcessor to add specific fields from Baggage into spans.

[bidetofevil]

What @martinkuba has here is the beginning of what I think would be a more involved spec that I would most likely involve Entities somehow so that a session can have a lifecycle of its own, independent of related telemetry. The prototype-first approach would work if each of the platforms keep in lockstep, and we can come back and consolidate on a more thorough design once the other pieces are in place.

[danielgblanco]

Thanks @bidetofevil. I agree. Let's wait for the prototype for the Javascript SDK for web and we can compare with other approaches to get a consolidated design that applies to all.