feat: Sessions Health Tracking

Author: kamilogorek

packages/browser/src/backend.ts

@@ -29,6 +29,12 @@ export interface BrowserOptions extends Options {
 
   /** @deprecated use {@link Options.denyUrls} instead. */
   blacklistUrls?: Array<string | RegExp>;
+
+  /**
+   * A flag enabling Sessions Tracking feature.
+   * By default Sessions Tracking is disabled.
+   */
+  autoSessionTracking?: boolean;
 }
 
 /**

packages/browser/src/sdk.ts

@@ -1,5 +1,5 @@
 import { getCurrentHub, initAndBind, Integrations as CoreIntegrations } from '@sentry/core';
-import { getGlobalObject, SyncPromise } from '@sentry/utils';
+import { getGlobalObject, logger, SyncPromise } from '@sentry/utils';
 
 import { BrowserOptions } from './backend';
 import { BrowserClient } from './client';
@@ -84,7 +84,15 @@ export function init(options: BrowserOptions = {}): void {
       options.release = window.SENTRY_RELEASE.id;
     }
   }
+  if (options.autoSessionTracking === undefined) {
+    options.autoSessionTracking = false;
+  }
+
   initAndBind(BrowserClient, options);
+
+  if (options.autoSessionTracking) {
+    startSessionTracking();
+  }
 }
 
 /**
@@ -166,3 +174,54 @@ export function close(timeout?: number): PromiseLike<boolean> {
 export function wrap(fn: (...args: any) => any): any {
   return internalWrap(fn)();
 }
+
+/**
+ * Enable automatic Session Tracking for the initial page load.
+ */
+function startSessionTracking(): void {
+  const window = getGlobalObject<Window>();
+  const hub = getCurrentHub();
+  let fcpResolved = false;
+  let loadResolved = false;
+  const possiblyEndSession = (): void => {
+    if (fcpResolved && loadResolved) {
+      hub.endSession();
+    }
+  };
+
+  hub.startSession();
+
+  window.addEventListener('load', () => {
+    loadResolved = true;
+    possiblyEndSession();
+  });
+
+  try {
+    let firstHiddenTime = document.visibilityState === 'hidden' ? 0 : Infinity;
+    document.addEventListener(
+      'visibilitychange',
+      event => {
+        firstHiddenTime = Math.min(firstHiddenTime, event.timeStamp);
+      },
+      { once: true },
+    );
+
+    const po = new PerformanceObserver((entryList, po) => {
+      entryList.getEntries().forEach(entry => {
+        if (entry.name === 'first-contentful-paint' && entry.startTime < firstHiddenTime) {
+          po.disconnect();
+          fcpResolved = true;
+          possiblyEndSession();
+        }
+      });
+    });
+
+    po.observe({
+      type: 'paint',
+      buffered: true,
+    });
+  } catch (e) {
+    fcpResolved = true;
+    possiblyEndSession();
+  }
+}

packages/browser/src/transports/base.ts

@@ -1,5 +1,5 @@
 import { API } from '@sentry/core';
-import { Event, Response, Status, Transport, TransportOptions } from '@sentry/types';
+import { Event, Response, SentryRequestType, Status, Transport, TransportOptions } from '@sentry/types';
 import { logger, parseRetryAfterHeader, PromiseBuffer, SentryError } from '@sentry/utils';
 
 /** Base Transport class implementation */
@@ -42,13 +42,13 @@ export abstract class BaseTransport implements Transport {
    * Handle Sentry repsonse for promise-based transports.
    */
   protected _handleResponse({
-    eventType,
+    requestType,
     response,
     headers,
     resolve,
     reject,
   }: {
-    eventType: string;
+    requestType: SentryRequestType;
     response: globalThis.Response | XMLHttpRequest;
     headers: Record<string, string | null>;
     resolve: (value?: Response | PromiseLike<Response> | null | undefined) => void;
@@ -60,7 +60,7 @@ export abstract class BaseTransport implements Transport {
      * https://developer.mozilla.org/en-US/docs/Web/API/Headers/get
      */
     const limited = this._handleRateLimit(headers);
-    if (limited) logger.warn(`Too many requests, backing off till: ${this._disabledUntil(eventType)}`);
+    if (limited) logger.warn(`Too many requests, backing off till: ${this._disabledUntil(requestType)}`);
 
     if (status === Status.Success) {
       resolve({ status });

packages/browser/src/transports/fetch.ts

@@ -1,5 +1,5 @@
-import { eventToSentryRequest } from '@sentry/core';
-import { Event, Response } from '@sentry/types';
+import { eventToSentryRequest, sessionToSentryRequest } from '@sentry/core';
+import { Event, Response, SentryRequest, Session } from '@sentry/types';
 import { getGlobalObject, supportsReferrerPolicy, SyncPromise } from '@sentry/utils';
 
 import { BaseTransport } from './base';
@@ -12,19 +12,31 @@ export class FetchTransport extends BaseTransport {
    * @inheritDoc
    */
   public sendEvent(event: Event): PromiseLike<Response> {
-    const eventType = event.type || 'event';
+    return this._sendRequest(eventToSentryRequest(event, this._api), event);
+  }
+
+  /**
+   * @inheritDoc
+   */
+  public sendSession(session: Session): PromiseLike<Response> {
+    return this._sendRequest(sessionToSentryRequest(session, this._api), session);
+  }
 
-    if (this._isRateLimited(eventType)) {
+  /**
+   * @param sentryRequest Prepared SentryRequest to be delivered
+   * @param event original payload used to create SentryRequest
+   */
+  private _sendRequest(sentryRequest: SentryRequest, event: Event | Session): PromiseLike<Response> {
+    if (this._isRateLimited(sentryRequest.type)) {
       return Promise.reject({
         event,
-        reason: `Transport locked till ${this._disabledUntil(eventType)} due to too many requests.`,
+        reason: `Transport locked till ${this._disabledUntil(sentryRequest.type)} due to too many requests.`,
         status: 429,
       });
     }
 
-    const sentryReq = eventToSentryRequest(event, this._api);
     const options: RequestInit = {
-      body: sentryReq.body,
+      body: sentryRequest.body,
       method: 'POST',
       // Despite all stars in the sky saying that Edge supports old draft syntax, aka 'never', 'always', 'origin' and 'default
       // https://caniuse.com/#feat=referrer-policy
@@ -42,13 +54,13 @@ export class FetchTransport extends BaseTransport {
     return this._buffer.add(
       new SyncPromise<Response>((resolve, reject) => {
         global
-          .fetch(sentryReq.url, options)
+          .fetch(sentryRequest.url, options)
           .then(response => {
             const headers = {
               'x-sentry-rate-limits': response.headers.get('X-Sentry-Rate-Limits'),
               'retry-after': response.headers.get('Retry-After'),
             };
-            this._handleResponse({ eventType, response, headers, resolve, reject });
+            this._handleResponse({ requestType: sentryRequest.type, response, headers, resolve, reject });
           })
           .catch(reject);
       }),

packages/browser/src/transports/xhr.ts

@@ -1,5 +1,5 @@
-import { eventToSentryRequest } from '@sentry/core';
-import { Event, Response } from '@sentry/types';
+import { eventToSentryRequest, sessionToSentryRequest } from '@sentry/core';
+import { Event, Response, SentryRequest, Session } from '@sentry/types';
 import { SyncPromise } from '@sentry/utils';
 
 import { BaseTransport } from './base';
@@ -10,18 +10,29 @@ export class XHRTransport extends BaseTransport {
    * @inheritDoc
    */
   public sendEvent(event: Event): PromiseLike<Response> {
-    const eventType = event.type || 'event';
+    return this._sendRequest(eventToSentryRequest(event, this._api), event);
+  }
 
-    if (this._isRateLimited(eventType)) {
+  /**
+   * @inheritDoc
+   */
+  public sendSession(session: Session): PromiseLike<Response> {
+    return this._sendRequest(sessionToSentryRequest(session, this._api), session);
+  }
+
+  /**
+   * @param sentryRequest Prepared SentryRequest to be delivered
+   * @param event original payload used to create SentryRequest
+   */
+  private _sendRequest(sentryRequest: SentryRequest, event: Event | Session): PromiseLike<Response> {
+    if (this._isRateLimited(sentryRequest.type)) {
       return Promise.reject({
         event,
-        reason: `Transport locked till ${this._disabledUntil(eventType)} due to too many requests.`,
+        reason: `Transport locked till ${this._disabledUntil(sentryRequest.type)} due to too many requests.`,
         status: 429,
       });
     }
 
-    const sentryReq = eventToSentryRequest(event, this._api);
-
     return this._buffer.add(
       new SyncPromise<Response>((resolve, reject) => {
         const request = new XMLHttpRequest();
@@ -32,17 +43,17 @@ export class XHRTransport extends BaseTransport {
               'x-sentry-rate-limits': request.getResponseHeader('X-Sentry-Rate-Limits'),
               'retry-after': request.getResponseHeader('Retry-After'),
             };
-            this._handleResponse({ eventType, response: request, headers, resolve, reject });
+            this._handleResponse({ requestType: sentryRequest.type, response: request, headers, resolve, reject });
           }
         };
 
-        request.open('POST', sentryReq.url);
+        request.open('POST', sentryRequest.url);
         for (const header in this.options.headers) {
           if (this.options.headers.hasOwnProperty(header)) {
             request.setRequestHeader(header, this.options.headers[header]);
           }
         }
-        request.send(sentryReq.body);
+        request.send(sentryRequest.body);
       }),
     );
   }

packages/core/src/basebackend.ts

@@ -1,4 +1,4 @@
-import { Event, EventHint, Options, Severity, Transport } from '@sentry/types';
+import { Event, EventHint, Options, Session, Severity, Transport } from '@sentry/types';
 import { logger, SentryError } from '@sentry/utils';
 
 import { NoopTransport } from './transports/noop';
@@ -34,6 +34,9 @@ export interface Backend {
   /** Submits the event to Sentry */
   sendEvent(event: Event): void;
 
+  /** Submits the session to Sentry */
+  sendSession(session: Session): void;
+
   /**
    * Returns the transport that is used by the backend.
    * Please note that the transport gets lazy initialized so it will only be there once the first event has been sent.
@@ -93,6 +96,20 @@ export abstract class BaseBackend<O extends Options> implements Backend {
     });
   }
 
+  /**
+   * @inheritDoc
+   */
+  public sendSession(session: Session): void {
+    if (!this._transport.sendSession) {
+      logger.warn('sendSession not implemented for a transport used');
+      return;
+    }
+
+    this._transport.sendSession(session).then(null, reason => {
+      logger.error(`Error while sending session: ${reason}`);
+    });
+  }
+
   /**
    * @inheritDoc
    */

packages/core/src/baseclient.ts

@@ -1,6 +1,15 @@
 /* eslint-disable max-lines */
-import { Scope } from '@sentry/hub';
-import { Client, Event, EventHint, Integration, IntegrationClass, Options, Severity } from '@sentry/types';
+import { Scope, Session } from '@sentry/hub';
+import {
+  Client,
+  Event,
+  EventHint,
+  Integration,
+  IntegrationClass,
+  Options,
+  SessionStatus,
+  Severity,
+} from '@sentry/types';
 import {
   dateTimestampInSeconds,
   Dsn,
@@ -141,6 +150,17 @@ export abstract class BaseClient<B extends Backend, O extends Options> implement
     return eventId;
   }
 
+  /**
+   * @inheritDoc
+   */
+  public captureSession(session: Session): void {
+    if (!session.release) {
+      logger.warn('Discarded session because of missing release');
+    } else {
+      this._sendSession(session);
+    }
+  }
+
   /**
    * @inheritDoc
    */
@@ -199,6 +219,49 @@ export abstract class BaseClient<B extends Backend, O extends Options> implement
     }
   }
 
+  /** Updates existing session based on the provided event */
+  protected _updateSessionFromEvent(session: Session, event: Event): void {
+    let crashed = false;
+    let errored = false;
+    let userAgent;
+    const exceptions = event.exception && event.exception.values;
+
+    if (exceptions) {
+      errored = true;
+
+      for (const ex of exceptions) {
+        const mechanism = ex.mechanism;
+        if (mechanism && mechanism.handled === false) {
+          crashed = true;
+          break;
+        }
+      }
+    }
+
+    const user = event.user;
+    if (!session.userAgent) {
+      const headers = event.request ? event.request.headers : {};
+      for (const key in headers) {
+        if (key.toLowerCase() === 'user-agent') {
+          userAgent = headers[key];
+          break;
+        }
+      }
+    }
+
+    session.update({
+      ...(crashed && { status: SessionStatus.Crashed }),
+      user,
+      userAgent,
+      errors: session.errors + Number(errored || crashed),
+    });
+  }
+
+  /** Deliver captured session to Sentry */
+  protected _sendSession(session: Session): void {
+    this._getBackend().sendSession(session);
+  }
+
   /** Waits for the client to be done with processing. */
   protected _isClientProcessing(timeout?: number): PromiseLike<{ ready: boolean; interval: number }> {
     return new SyncPromise<{ ready: boolean; interval: number }>(resolve => {
@@ -434,7 +497,15 @@ export abstract class BaseClient<B extends Backend, O extends Options> implement
           const isInternalException =
             hint && hint.data && (hint.data as { [key: string]: unknown }).__sentry__ === true;
           // We skip beforeSend in case of transactions
+
           if (isInternalException || !beforeSend || isTransaction) {
+            if (!isTransaction) {
+              const session = scope && scope.getSession();
+              if (session) {
+                this._updateSessionFromEvent(session, finalEvent);
+              }
+            }
+
             this._sendEvent(finalEvent);
             resolve(finalEvent);
             return;
@@ -454,6 +525,11 @@ export abstract class BaseClient<B extends Backend, O extends Options> implement
               return;
             }
 
+            const session = scope && scope.getSession();
+            if (session) {
+              this._updateSessionFromEvent(session, finalEvent);
+            }
+
             // From here on we are really async
             this._sendEvent(finalEvent);
             resolve(finalEvent);