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.

Automatic tracking

BugSnag will automatically report a session each time the app is launched or enters the foreground after being in the background for at least 30 seconds.

For Android apps, this is each time an Activity is in the “Started” state and 30 seconds after all Activities have remained in the “Stopped” state.

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.

startSession

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

Bugsnag.startSession();

Bugsnag.startSession()

// There is no equivalent operation in C/C++

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.

pauseSession

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

Bugsnag.pauseSession();

Bugsnag.pauseSession()

// There is no equivalent operation in C/C++

This can be advantageous if, for example, you do not wish the stability score to include crashes in a background service.

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.

if (Bugsnag.resumeSession()) // ...

if (Bugsnag.resumeSession()) // ...

// There is no equivalent operation in C/C++

Sessions are stored in memory for the lifetime of the application process and are not persisted on disk. Therefore calling this method on app startup would start a new session, rather than continuing any previous session.

Discarding and amending sessions

The data captured in a session can be customized by adding an OnSessionCallback as part of your BugSnag configuration.

Configuration config = Configuration.load(this);
config.addOnSession(new OnSessionCallback() {
    @Override
    public boolean onSession(Session session) {
        String userId = getMyUserIdentifier(); // a custom user resolver
        session.setUser(userId, null, null);
        return true; // Return false to discard
    }
});
Bugsnag.start(this, config);

Bugsnag.start(this, Configuration.load(this).apply {
  addOnSession(OnSessionCallback { session ->
    val userId = getMyUserIdentifier() // a custom user resolver
    session.setUser(userId, null, null)
    true // Return false to discard
  }
})

// There is no equivalent operation in C/C++

As with an OnErrorCallback, 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 addOnSession 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:

OnSessionCallback cb = new OnSessionCallback() { /* ... */ };
Bugsnag.addOnSession(cb);
...
Bugsnag.removeOnSession(cb);

val cb = OnSessionCallback { /* ... */ }
Bugsnag.addOnSession(cb)
// ...
Bugsnag.removeOnSession(cb)

The Session class

The following information is available on the Session class, the representation of session information available in an OnSessionCallback. See the Session class for full documentation.