Capturing sessions

Bugsnag tracks the number of “sessions” that happen within your application. This allows you to compare stability scores between releases and helps you to understand the quality of your releases.

Sessions are captured and reported by default. This behavior can be disabled using the autoTrackSessions configuration option.

This documentation is for version 7 of the Bugsnag JavaScript notifier. If you are using older versions, we recommend upgrading to the latest release using our Upgrade guide. Documentation for the previous release can be found on our legacy pages.

Automatic tracking

Browser

In the browser, Bugsnag will automatically report a session each time:

  • The page loads
  • The URL changes via history.pushState() or history.replaceState()

Node.js

Sessions are reported in Node.js every time a request is served if you are using one of the server integrations:

  • @bugsnag/plugin-express
  • @bugsnag/plugin-restify
  • @bugsnag/plugin-koa

A summary of sessions recorded will be periodically sent to Bugsnag.

Manual session handling

If you want control over what is deemed a session, you can switch off automatic session tracking with the autoTrackSessions option, and manage the session lifecycle using startSession(), pauseSession() and resumeSession() on the Bugsnag client.

You should call these methods at the appropriate time in your application’s lifecycle when you wish to have an active session. Any errors which occur in your application outside of a session will still be reported to Bugsnag but will not count towards your application’s stability score.

startSession

Starts a new session to which subsequent handled and unhandled events will be attributed to.

If there is already an active session, it will be replaced with a new one. Use resumeSession if you only want to start a session when one doesn’t already exist.

Depending on the platform, this method behaves slightly differently.

Single user processes

In single user processes (such as the browser and React Native) you can call this method and discard its return value. References to the original client get updated with the new session. In these processes, the session is enqueued to send as soon as possible.

Bugsnag.startSession()

Multi-user processes

In processes that can potentially handle multiple users (i.e. a web server in Node), it is important to hold on to the return value of this method because it returns a new client which is bound to the session that was created. To illustrate, see the following example:

// this starts a session
var sessionClient = Bugsnag.startSession()

// this error is reported with session information
sessionClient.notify(new Error('boom'))

// this error is not reported with session information
// because it uses the original client
Bugsnag.notify(new Error('bam'))

In these processes, sessions are created immediately, but they are buffered and sent in batches periodically.

pauseSession

Prevents further events being attributed to the current session until the session is resumed or a new session is started.

A client object is returned for use in multi-user processes, see notes in startSession.

Bugsnag.pauseSession()

resumeSession

Resumes tracking events against the current session, if it was previously paused. If there is was no previous session, a new session is started. This method returns true if there was a session to resume or false if a new session was created.

A client object is returned for use in multi-user processes, see notes in startSession.

Bugsnag.resumeSession()

Discarding and amending sessions

The data captured in a session can be customized by adding an onSession callback as part of your Bugsnag configuration.

Bugsnag.start({
  onSession: function (session) {
    var userId = getMyUserIdentifier() // a custom user resolver
    session.setUser(userId)
  }
})

As with an onError callback, the return value from onSession determines whether the session will be delivered to Bugsnag and so can be used to discard sessions if required.

Adding and removing callbacks

We recommend adding callbacks through the onSession configuration option to ensure that it is registered as soon as Bugsnag starts. However, the following methods are provided to allow callbacks to be added and removed whilst the application is running:

var cb = function(session) { /* ... */ };
Bugsnag.addOnSession(cb);
...
Bugsnag.removeOnSession(cb);

The Session object

The following information is available on a Session object, the representation of session information available in an onSession callback.

property type description
app Object A subset of the app data contained in error events.
device Object A subset of the device data contained in error events.
id String A unique ID for the session.
startedAt Date The timestamp that the session was started.
getUser/setUser Object The active user for the session