Implementing Session Updates in Sentry SDKs: A Developer Guide

Overview

Sentry accepts session‑update events wrapped in envelopes to report release and project health. SDKs must construct these events correctly, respect attribute immutability, and send them at appropriate times.

Basic Operations

A Session is entirely client‑driven; the client decides when a session starts, ends, or becomes unhealthy.

The client may explicitly end a session to record a timestamp or exit condition (e.g., a crash).

When restarting, the client should end the previous session, though leaving it open is acceptable.

Session state is updated via session‑change events that contain the full session state .

Only five days of updates are retained; if no event arrives within five days the session is considered permanently healthy.

A session does not need to start before it crashes; a single crash report is sufficient.

Server Model

The Sentry session system is optimized for scalability and low operational cost. The server pre‑materializes session data each hour; when a session‑update arrives, the server immediately materializes the data into the correct bucket, making the protocol effectively “append‑only”. The client must therefore store the entire session state on its side.

Session‑Update Payload

A session‑update is a JSON object inside an envelope. Example:

{
  "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": "[email protected]",
    "environment": "environment name",
    "ip_address": "optional user ip address for filtering",
    "user_agent": "optional user agent for filtering"
  }
}

The envelope must contain the type header and the JSON payload, e.g.:

{}
{"type":"session"}
{...payload...}

Session Aggregates Payload (request‑mode)

For high‑throughput request‑mode sessions, the SDK aggregates closed sessions before sending. The aggregated payload looks like:

{
  "aggregates": [
    {"started":"2020-02-07T14:16:00Z","exited":123},
    {"started":"2020-02-07T14:16:00Z","did":"optional distinct user id","exited":12,"errored":3}
  ],
  "attrs": {
    "release": "[email protected]",
    "environment": "development"
  }
}

Crash and Session Interaction

Sessions and error events are separate systems. A session can end without an error event, and an error can be sent without a session update. This separation lets the client decide whether to send a session update alongside a crash‑related error, ensuring that rate‑limited error events do not hide session health information.

Important Client Behavior

Attribute Immutability

After a session is created, attributes such as did, started, or any custom fields cannot change. Only the session status, duration, and errors may be updated.

Session Counting / Initialization

The first event must have init": true. This flag enables the server to deduplicate total session counts; missing the flag may cause incorrect ingestion.

Termination States

Sessions can be in ok (active) or a terminal state ( exited, crashed, abnormal). Once a terminal state is set, no further updates are allowed.

Ending Modes

exited

: clean end; counted as normal duration. crashed: used when an unhandled error or full application crash occurs. abnormal: used when the application terminates without a clear crash (e.g., power loss, kill‑9).

Session Modes

Two modes exist:

Short‑lived (server‑mode / request‑mode) : each HTTP request or RPC call creates a session. Sessions are numerous and often have no useful duration.

User‑mode (application‑mode) : a session spans the entire user interaction with the app, lasting minutes or longer.

The SDK should default to the mode that best matches the language ecosystem’s typical use case.

Unified API

At the hub level, the public API includes: Hub.start_session() – stores a new session in the current scope and implicitly ends any existing session. Hub.end_session() – sets status and duration, queues the session for sending. Hub.start_auto_session_tracking() / Hub.stop_auto_session_tracking() – toggle automatic tracking.

The auto_session_tracking option enables or disables this feature.

When to Send Updates

All SDKs should update the session whenever they capture an error, modify the distinct ID, or otherwise affect session state. Updates are batched to reduce envelope traffic. For server‑mode SDKs, a periodic (≈60 s) flush sends aggregated session data.

Session Aggregation Details

Started timestamps are rounded to the minute and used as bucket keys.

Within a bucket, sessions are grouped by started and did. The bucket stores counts of exited, crashed, abnormal, and errored sessions.

Only sessions with init": true are eligible for aggregation.

Public API Summary

Use Hub.start_session() to begin tracking and Hub.end_session() to finalize a session with proper status and duration.

Implementation Guidelines

SDKs should create a session at initialization (or on first request for server‑mode) and respect the lifecycle rules above. Short‑lived programs may delay sending the initial envelope for a few seconds to avoid unnecessary network traffic.

For Node.js, the SDK can detect a request‑handler integration and automatically switch to server‑mode session tracking.

All configuration defaults enable session tracking; developers may disable it via the auto_session_tracking option.