Sign In

Sessions

For basic health tracking Sentry accepts envelopes containing session update events. These session update events can be used to inform Sentry about release and project associated project health.

Note: When working with Sessions locally, make sure that you update your configuration file ~/.sentry/sentry.config.py with a necessary environment variable:

Copied
SENTRY_EVENTSTREAM = 'sentry.eventstream.kafka.KafkaEventStream'

Basic Operation

  • Sessions are entirely client driven. The client determines when a session starts, ends or transitions into an unhealthy state.
    • The client can explicitly end a session to record time or exit condition (crash etc.)
    • Clients should explicitly end sessions on restart if needed but it is acceptable for a session not to end.
  • Sessions are updated through session change events that hold the entire session state.
  • Sessions are updated from events sent in. The most recent event holds the entire session state. The initial session event that is sent to the server is marked explicitly.
  • Session updates must not change the attributes or data corrupts when materialized. See the section below on Attribute Immutability.
  • Sessions can only be updated for a period of 5 days. If a session did not receive a second event in 5 days it's permanently good.
  • A session does not have to be started in order to crash. Just reporting a crash is sufficient.

Server Model

At present Sentry's session system is optimized towards ease of scalability and cost of operation. This means that the protocol is heavily geared towards achieving this goal. Some of these optimizations show in the protocol and it's important for the client to follow the protocol accurately to avoid creating bad data on the server.

The server has hourly buckets of pre-materialized session data. As a session update event comes in the server will immediately materialize the data into the correct bucket. This means that the protocol is restricted to being "additive". This also means that the client needs to store the entire state of the session on its side.

Session Update Payload

A session update is an item in an envelope called session. It consists of a JSON payload that looks roughly like this:

Copied
{
  "sid": "7c7b6585-f901-4351-bf8d-02711b721929",
  "did": "optional distinct user id",
  "init": true,
  "started": "2020-02-07T14:16:00Z",
  "duration": 60,
  "status": "exited",
  "attrs": {
    "release": "release name",
    "environment": "environment name",
    "ip_address": "optional user ip address for filtering",
    "user_agent": "optional user agent for filtering"
  }
}

Note that this must be enclosed in an envelope. So the full event looks something like this:

Copied
{}
{"type":"session"}
{"sid":"..."}

The following fields exist:

sid (optional)

Session ID (unique and client generated). Clients are allowed to skip it if the initial session state is exited.

did (optional, distinct ID)

The distinct ID. Should be a device or user ID. The system automatically hashes this ID before storing it.

seq (optional)

A logical clock. Defaults to the current UNIX timestamp in milliseconds during ingestion. The value 0 is reserved in the sense that a session with init set to true will automatically have seq forced to 0.

timestamp (optional)

The timestamp of when the session change event came in. Must be an ISO string for now. If not sent, the server will assume the current UTC timestamp. In the data model, this is called received.

started

Timestamp when the session started. Must be an ISO string for now.

init (optional, default is false)

If this is set to true it means that this was the first event of the session. This lets the server optimize the session counts because no deduplication is needed (client is authoritative anyways). Internally when this flag is set seq is changed to 0 on processing.

duration (optional)

An optional field that can transmit the session duration when the event was received. This can be client controlled so, for instance, inactive time can be subtracted (seconds as float).

status (optional, default = ok)

The current status of the session. A session can only be in two states effectively: ok which means the session is alive or one of the terminal states. When a session is moved away from ok it must not be updated anymore.

  • ok: session is currently in progress but healthy. This can be the terminal state of a session
  • exited: the session terminated normally
  • crashed: the session terminated in a crash
  • abnormal: the session encountered a non crash related abnormal exit

errors (optional, default = 0)

A running counter of errors encountered while this session was ongoing. It's important that this counter is also incremented when a session goes to crashed. (eg: the crash itself is always an error as well). Ingest should force errors to 1 if not set or 0.

attrs (all but release optional)

  • release: a sentry release ID (release)
  • environment: a sentry environment (environment)
  • ip_address: the primary IP address to be considered. This is normally the IP of the user. This data is not persisted but used for filtering. If not set the IP is filled in automatically.
  • user_agent: the user agent to be considered. This is normally the user agent of the user that caused the session. This data is not persisted but used for filtering.

Crashes vs Sessions

Sessions and error events are two distinct systems within Sentry. Session updates can be done without error events to be sent and likewise, errors can be sent without session updates.

This gives the client full control over how session updates should be performed. The motivating factor is that the server is free to reject error events in some situations where it would still be interesting to record session information. For instance, if a project has a rate limit applied on error events they session data can still be routed to the project bypassing this rate limit.

However, it's strongly recommended to send session updates in the same envelope as the crash event in case the session transitions to the crashed status. This will ensure that the events arrive at the same time in the system if the network is unreliable.

Important Client Behavior

These are important rules that the clients must follow:

Attribute Immutability

It's currently not allowed for a session to change any of the attributes in subsequent updates which includes the did, started or other attributes. The only attributes which are allowed to change are the session status, duration or error count. If a user is not known in the beginning then either the session start should be delayed or the session should be restarted once the user is known.

Session Counting / init

It's crucial that the initial session update sent to the system has init set to true. This is necessary because the server currently does not deduplicate the total session count as an optimization. If the initial init: true flag is missing, the session might not be ingested correctly by Sentry.

Terminal Session States

A session can exist in two states: in progress or terminated. A terminated session must not receive further updates. exited, crashed and abnormal are all terminal states. When a session reaches this state the client must not report any more session updates or start a new session.

SDKs are encouraged to distinguish between different ways of ending a session:

  • exited: this means the session ended cleanly. It's in no way different than the session staying in ok from the point of success reports. However only sessions ending in exited will be considered for session durations. A session is allowed to go to exited even if errors occurred.

  • crashed: a session should be reported as crashed under the following cases:

    • an unhandled error occurred and there is a natural session end (eg: end of HTTP request)
    • a complete crash of the application occurred (crash to desktop, termination)
    • a user feedback dialog is surfaced to the user. After this, the SDK must start a new session as if it fully crashed.;

  • abnormal: SDKs are encouraged to always transition a session to exited or crashed if they can do so. For SDKs that are capable of always ending sessions, they should end a session in abnormal if they could not detect the application shutting down correctly. Examples for abnormal sessions:

    • a computer was shut down / lost power
    • the user force closed an application through kill -9 or the task manager

    Abnormal session ends are normally to be recorded on application restart.

Crashed, Abnormal vs Errored

A session is supposed to transition to crashed when it encountered an unhandled error such as a full application crash. For applications that cannot fully crash such as a website, it's acceptable to transition to the crashed state if the user encountered an error dialog.

Abnormal are sessions of which their fate is unknown. For desktop applications, for instance, it makes sense to transition a session to abnormal if it was stored but the exit of the application was not observed but also did not crash. These are situations where the user forced the app to close via the task manager, the machine lost power or other situations. A session can be stored by persisting it to disk eagerly. This saved file can be detected on application restart to close the session as abnormal.

Errored sessions are determined by an errors counter greater than zero. The client is required to count events that are considered errors and send the count along with session updates. A session that is ok and has an error count of greater than zero is considered an errored session. All crashed and abnormal sessions are also at all times considered errored but subtracted from the final errored session count.

Exited

A session can transition to exited which is exactly the same state as ok with one difference: sessions transitioned to exited have their session duration averaged. This lets Sentry show you the duration of non crashed sessions over time.

SDK Considerations

Generally speaking, there are two separate modes for health reporting that SDKs can use. One is very short lived sessions, the other is user attended sessions.

Short lived sessions (server-mode / request-mode)

These sessions roughly correspond to HTTP requests or RPC calls in a server setting.

  • high in volume, typically one session for each request
  • the number of sessions is usually higher than the number of sentry events
  • sessions are attached to a single hub / concurrency unit
  • timing information is typically useless because session time in the milliseconds

User attended sessions (user-mode / application-mode)

These are sessions that are more corresponding to an actual user session or application run. This is what you would see in a web browser, mobile world, command line application or similar.

  • typically just a single session from application start to quit
  • there are usually fewer sessions than Sentry events
  • sessions span multiple hubs / threads
  • session duration typically in the minutes, timing information is useful

Both of those cases look similar from the API point of view but different recommendations apply for SDKs.

Choosing the Session Mode

While it is in theory possible to use both session modes in a single application, it is recommended that the SDK default to a single mode that is most appropriate to the main use case of the language ecosystem. This is similar to and can be used in the same way as a global Hub mode that certain SDKs support.

When the SDK is configured to use user-mode sessions or global Hub mode, a single session should be started at the start of the application and should persist through the application's runtime. Depending on the SDK internals, this single session can be shared among all application threads and thread-local Hubs.

When using server-mode sessions, no application-wide session will be started, and it is up to integrations or the user to start the session when the request is received and end it when a response is returned.

Unified API Implications

The Unified API that SDKs should adhere to defines the concepts of Hub, Scope and Client.

Conceptually speaking, the session is a concern of the Hub, and unlike scopes, sessions should not be nested. When any kind of event happens, there should be only one unambiguous session that keeps track of the error count.

When considering the flow of events through the SDK, from the static capture_event function, through the thread local Hub, and into the Client::capture_event(event, scope) method; depending on the internal implementation details of the SDK, it might make sense to attach the session to the Scope, which would make it possible for the Client to bundle an event and a session update into a single envelope to be sent to Sentry.

Session Updates and when to send Updates upstream

For all SDKs, the current session shall be automatically updated whenever data is captured at a similar place where apply_to_scope is called to increase the error count, or update the session based on the distinct ID / user ID.

SDKs should generally aim to decrease the number of envelopes sent upstream.

server-mode SDKs that track a great number of sessions should consider using a periodic session flusher (every 30/60 secs) that assembles envelopes of session items and forwards them to the transport as a single request.

user-mode SDKs may instead opt into sending session updates along with captured events in the same envelope. The final session update that closes the session may be batched similar to server-mode sessions.

In either case, the init flag must be set correctly for the first transmission of the session, and session metadata such as the distinct ID must be immutable after the initial transmission.

Exposed API

The most basic API exposed is on the hub level and lets you start and stop session recording:

API:

Hub.start_session()

Stores a session on the current scope and starts tracking it. This normally attaches a brand new session to the scope, and implicitly ends any already existing session.

Hub.end_session()

Ends the session, setting an appropriate status and duration, and enqueues it for sending to Sentry.

Hub.start_auto_session_tracking() / Hub.stop_auto_session_tracking()

Stops and reactivates automatic session tracking.

Init Options:

auto_session_tracking

This enables / disables automatic session tracking through integrations.

You can edit this page on GitHub.