breadcrumbs.ts

/* eslint-disable max-lines */

import type {
  Breadcrumb,
  Client,
  Event as SentryEvent,
  FetchBreadcrumbData,
  FetchBreadcrumbHint,
  HandlerDataFetch,
  IntegrationFn,
} from '@sentry/core';
import {
  addBreadcrumb,
  addFetchInstrumentationHandler,
  debug,
  defineIntegration,
  filterCollectedUrl,
  getBreadcrumbLogLevelFromHttpStatusCode,
  getClient,
  getEventDescription,
  parseUrl,
} from '@sentry/core';
import type { FetchHint, HandlerDataDom, HandlerDataHistory, HandlerDataXhr } from '@sentry/browser-utils';
import {
  addClickKeypressInstrumentationHandler,
  addHistoryInstrumentationHandler,
  addXhrInstrumentationHandler,
  htmlTreeAsString,
  getComponentName,
  SENTRY_XHR_DATA_KEY,
} from '@sentry/browser-utils';
import type { XhrBreadcrumbData, XhrBreadcrumbHint } from '@sentry/core/browser';
import { DEBUG_BUILD } from '../debug-build';
import { WINDOW } from '../helpers';

interface BreadcrumbsOptions {
  dom:
    | boolean
    | {
        serializeAttribute?: string | string[];
        maxStringLength?: number;
      };
  fetch: boolean;
  history: boolean;
  sentry: boolean;
  xhr: boolean;
}

/** maxStringLength gets capped to prevent 100 breadcrumbs exceeding 1MB event payload size */
const MAX_ALLOWED_STRING_LENGTH = 1024;

const INTEGRATION_NAME = 'Breadcrumbs' as const;

const _breadcrumbsIntegration = ((options: Partial<BreadcrumbsOptions> = {}) => {
  const _options = {
    dom: true,
    fetch: true,
    history: true,
    sentry: true,
    xhr: true,
    ...options,
  };

  return {
    name: INTEGRATION_NAME,
    setup(client) {
      if (_options.dom) {
        addClickKeypressInstrumentationHandler(_getDomBreadcrumbHandler(client, _options.dom));
      }
      if (_options.xhr) {
        addXhrInstrumentationHandler(_getXhrBreadcrumbHandler(client));
      }
      if (_options.fetch) {
        addFetchInstrumentationHandler(_getFetchBreadcrumbHandler(client));
      }
      if (_options.history) {
        addHistoryInstrumentationHandler(_getHistoryBreadcrumbHandler(client));
      }
      if (_options.sentry) {
        client.on('beforeSendEvent', _getSentryBreadcrumbHandler(client));
      }
    },
  };
}) satisfies IntegrationFn;

export const breadcrumbsIntegration = defineIntegration(_breadcrumbsIntegration);

/**
 * Adds a breadcrumb for Sentry events or transactions if this option is enabled.
 */
function _getSentryBreadcrumbHandler(client: Client): (event: SentryEvent) => void {
  return function addSentryBreadcrumb(event: SentryEvent): void {
    if (getClient() !== client) {
      return;
    }

    addBreadcrumb(
      {
        category: `sentry.${event.type === 'transaction' ? 'transaction' : 'event'}`,
        event_id: event.event_id,
        level: event.level,
        message: getEventDescription(event),
      },
      {
        event,
      },
    );
  };
}

/**
 * A HOC that creates a function that creates breadcrumbs from DOM API calls.
 * This is a HOC so that we get access to dom options in the closure.
 */
function _getDomBreadcrumbHandler(
  client: Client,
  dom: BreadcrumbsOptions['dom'],
): (handlerData: HandlerDataDom) => void {
  return function _innerDomBreadcrumb(handlerData: HandlerDataDom): void {
    if (getClient() !== client) {
      return;
    }

    let target;
    let componentName;
    let keyAttrs = typeof dom === 'object' ? dom.serializeAttribute : undefined;

    let maxStringLength =
      typeof dom === 'object' && typeof dom.maxStringLength === 'number' ? dom.maxStringLength : undefined;
    if (maxStringLength && maxStringLength > MAX_ALLOWED_STRING_LENGTH) {
      DEBUG_BUILD &&
        debug.warn(
          `\`dom.maxStringLength\` cannot exceed ${MAX_ALLOWED_STRING_LENGTH}, but a value of ${maxStringLength} was configured. Sentry will use ${MAX_ALLOWED_STRING_LENGTH} instead.`,
        );
      maxStringLength = MAX_ALLOWED_STRING_LENGTH;
    }

    if (typeof keyAttrs === 'string') {
      keyAttrs = [keyAttrs];
    }

    // Accessing event.target can throw (see getsentry/raven-js#838, #768)
    try {
      const event = handlerData.event as Event | Node;
      const element = _isEvent(event) ? event.target : event;

      target = htmlTreeAsString(element, { keyAttrs, maxStringLength });
      componentName = getComponentName(element);
    } catch {
      target = '<unknown>';
    }

    if (target.length === 0) {
      return;
    }

    const breadcrumb: Breadcrumb = {
      category: `ui.${handlerData.name}`,
      message: target,
    };

    if (componentName) {
      breadcrumb.data = { 'ui.component_name': componentName };
    }

    addBreadcrumb(breadcrumb, {
      event: handlerData.event,
      name: handlerData.name,
      global: handlerData.global,
    });
  };
}

/**
 * Creates breadcrumbs from XHR API calls
 */
function _getXhrBreadcrumbHandler(client: Client): (handlerData: HandlerDataXhr) => void {
  return function _xhrBreadcrumb(handlerData: HandlerDataXhr): void {
    if (getClient() !== client) {
      return;
    }

    const { startTimestamp, endTimestamp } = handlerData;

    const sentryXhrData = handlerData.xhr[SENTRY_XHR_DATA_KEY];

    // We only capture complete, non-sentry requests
    if (!startTimestamp || !endTimestamp || !sentryXhrData) {
      return;
    }

    const { method, url, status_code, body } = sentryXhrData;

    const data: XhrBreadcrumbData = {
      method,
      url: getBreadcrumbUrl(url, client),
      status_code,
    };

    const hint: XhrBreadcrumbHint = {
      xhr: handlerData.xhr,
      input: body,
      startTimestamp,
      endTimestamp,
    };

    const breadcrumb = {
      category: 'xhr',
      data,
      type: 'http',
      level: getBreadcrumbLogLevelFromHttpStatusCode(status_code),
    };

    client.emit('beforeOutgoingRequestBreadcrumb', breadcrumb, hint);

    addBreadcrumb(breadcrumb, hint);
  };
}

/**
 * Creates breadcrumbs from fetch API calls
 */
function _getFetchBreadcrumbHandler(client: Client): (handlerData: HandlerDataFetch) => void {
  return function _fetchBreadcrumb(handlerData: HandlerDataFetch): void {
    if (getClient() !== client) {
      return;
    }

    const { startTimestamp, endTimestamp } = handlerData;

    // We only capture complete fetch requests
    if (!endTimestamp) {
      return;
    }

    if (handlerData.fetchData.url.match(/sentry_key/) && handlerData.fetchData.method === 'POST') {
      // We will not create breadcrumbs for fetch requests that contain `sentry_key` (internal sentry requests)
      return;
    }

    if (handlerData.error) {
      const hint: FetchBreadcrumbHint = {
        data: handlerData.error,
        input: handlerData.args,
        startTimestamp,
        endTimestamp,
      };

      const breadcrumb = {
        category: 'fetch',
        data: { ...handlerData.fetchData, url: getBreadcrumbUrl(handlerData.fetchData.url, client) },
        level: 'error',
        type: 'http',
      } satisfies Breadcrumb;

      client.emit('beforeOutgoingRequestBreadcrumb', breadcrumb, hint as FetchHint);

      addBreadcrumb(breadcrumb, hint);
    } else {
      const response = handlerData.response as Response | undefined;
      const data: FetchBreadcrumbData = {
        ...handlerData.fetchData,
        url: getBreadcrumbUrl(handlerData.fetchData.url, client),
        status_code: response?.status,
      };

      const hint: FetchBreadcrumbHint = {
        input: handlerData.args,
        response,
        startTimestamp,
        endTimestamp,
      };

      const breadcrumb = {
        category: 'fetch',
        data,
        type: 'http',
        level: getBreadcrumbLogLevelFromHttpStatusCode(data.status_code),
      };

      client.emit('beforeOutgoingRequestBreadcrumb', breadcrumb, hint as FetchHint);

      addBreadcrumb(breadcrumb, hint);
    }
  };
}

/**
 * Creates breadcrumbs from history API calls
 */
function _getHistoryBreadcrumbHandler(client: Client): (handlerData: HandlerDataHistory) => void {
  return function _historyBreadcrumb(handlerData: HandlerDataHistory): void {
    if (getClient() !== client) {
      return;
    }

    let from: string | undefined = handlerData.from;
    let to: string | undefined = handlerData.to;
    const parsedLoc = parseUrl(WINDOW.location.href);
    let parsedFrom = from ? parseUrl(from) : undefined;
    const parsedTo = parseUrl(to);

    // Initial pushState doesn't provide `from` information
    if (!parsedFrom?.path) {
      parsedFrom = parsedLoc;
    }

    // Use only the path component of the URL if the URL matches the current
    // document (almost all the time when using pushState)
    if (parsedLoc.protocol === parsedTo.protocol && parsedLoc.host === parsedTo.host) {
      to = parsedTo.relative;
    }
    if (parsedLoc.protocol === parsedFrom.protocol && parsedLoc.host === parsedFrom.host) {
      from = parsedFrom.relative;
    }

    addBreadcrumb({
      category: 'navigation',
      data: {
        from: filterCollectedUrl(from),
        to: filterCollectedUrl(to),
      },
    });
  };
}

function getBreadcrumbUrl(url: string, client?: Client): string {
  const pageUrl = url === '' ? WINDOW.location?.href : undefined;
  return filterCollectedUrl(pageUrl ? (pageUrl.split('#')[0] ?? '') : url, client);
}

function _isEvent(event: unknown): event is Event {
  return !!event && !!(event as Record<string, unknown>).target;
}