feat(tracing): Add hook for trace sampling function to SDK options

packages/gatsby/README.md

@@ -40,7 +40,7 @@ To automatically capture the `release` value on Vercel you will need to register
 
 ## Sentry Performance
 
-To enable Tracing support, supply the `tracesSampleRate` to the options and make sure you have installed the `@sentry/tracing` package. This will also turn on the `BrowserTracing` integration for automatic instrumentation of the browser.
+To enable tracing, supply either `tracesSampleRate` or `tracesSampler` to the options and make sure you have installed the `@sentry/tracing` package. This will also turn on the `BrowserTracing` integration for automatic instrumentation of pageloads and navigations.
 
 ```javascript
 {
@@ -49,8 +49,31 @@ To enable Tracing support, supply the `tracesSampleRate` to the options and make
     {
       resolve: "@sentry/gatsby",
       options: {
-          dsn: process.env.SENTRY_DSN, // this is the default
-          tracesSampleRate: 1, // this is just to test, you should lower this in production
+        dsn: process.env.SENTRY_DSN, // this is the default
+
+        // A rate of 1 means all traces will be sent, so it's good for testing.
+        // In production, you'll likely want to either choose a lower rate or use `tracesSampler` instead (see below).
+        tracesSampleRate: 1,
+
+        // Alternatively:
+        tracesSampler: samplingContext => {
+          // Examine provided context data (along with anything in the global namespace) to decide the sample rate
+          // for this transaction.
+          // Can return 0 to drop the transaction entirely.
+
+          if ("...") {
+            return 0.5 // These are important - take a big sample
+          }
+          else if ("...") {
+            return 0.01 // These are less important or happen much more frequently - only take 1% of them
+          }
+          else if ("...") {
+            return 0 // These aren't something worth tracking - drop all transactions like this
+          }
+          else {
+            return 0.1 // Default sample rate
+          }
+        }
       }
     },
     // ...
@@ -68,7 +91,7 @@ If you want to supply options to the `BrowserTracing` integration, use the `brow
       resolve: "@sentry/gatsby",
       options: {
           dsn: process.env.SENTRY_DSN, // this is the default
-          tracesSampleRate: 1, // this is just to test, you should lower this in production
+          tracesSampleRate: 1, // or tracesSampler (see above)
           browserTracingOptions: {
             // disable creating spans for XHR requests
             traceXHR: false,

packages/gatsby/gatsby-browser.js

@@ -6,10 +6,9 @@ exports.onClientEntry = function(_, pluginParams) {
     return;
   }
 
-  const tracesSampleRate = pluginParams.tracesSampleRate !== undefined ? pluginParams.tracesSampleRate : 0;
   const integrations = [...(pluginParams.integrations || [])];
 
-  if (tracesSampleRate && !integrations.some(ele => ele.name === 'BrowserTracing')) {
+  if (Tracing.hasTracingEnabled(pluginParams) && !integrations.some(ele => ele.name === 'BrowserTracing')) {
     integrations.push(new Tracing.Integrations.BrowserTracing(pluginParams.browserTracingOptions));
   }
 
@@ -22,7 +21,6 @@ exports.onClientEntry = function(_, pluginParams) {
     // eslint-disable-next-line no-undef
     dsn: __SENTRY_DSN__,
     ...pluginParams,
-    tracesSampleRate,
     integrations,
   });
 

packages/gatsby/test/gatsby-browser.test.ts

@@ -53,7 +53,6 @@ describe('onClientEntry', () => {
       environment: process.env.NODE_ENV,
       integrations: [],
       release: (global as any).__SENTRY_RELEASE__,
-      tracesSampleRate: 0,
     });
   });
 
@@ -100,6 +99,16 @@ describe('onClientEntry', () => {
     );
   });
 
+  it('sets a tracesSampler if defined as option', () => {
+    const tracesSampler = jest.fn();
+    onClientEntry(undefined, { tracesSampler });
+    expect(sentryInit).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        tracesSampler,
+      }),
+    );
+  });
+
   it('adds `BrowserTracing` integration if tracesSampleRate is defined', () => {
     onClientEntry(undefined, { tracesSampleRate: 0.5 });
     expect(sentryInit).toHaveBeenLastCalledWith(
@@ -109,6 +118,16 @@ describe('onClientEntry', () => {
     );
   });
 
+  it('adds `BrowserTracing` integration if tracesSampler is defined', () => {
+    const tracesSampler = jest.fn();
+    onClientEntry(undefined, { tracesSampler });
+    expect(sentryInit).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        integrations: [expect.objectContaining({ name: 'BrowserTracing' })],
+      }),
+    );
+  });
+
   it('only defines a single `BrowserTracing` integration', () => {
     const Tracing = jest.requireActual('@sentry/tracing');
     const integrations = [new Tracing.Integrations.BrowserTracing()];

packages/hub/src/hub.ts

@@ -3,6 +3,7 @@ import {
   Breadcrumb,
   BreadcrumbHint,
   Client,
+  CustomSamplingContext,
   Event,
   EventHint,
   Extra,
@@ -19,7 +20,7 @@ import {
 } from '@sentry/types';
 import { consoleSandbox, getGlobalObject, isNodeEnv, logger, timestampWithMs, uuid4 } from '@sentry/utils';
 
-import { Carrier, Layer } from './interfaces';
+import { Carrier, DomainAsCarrier, Layer } from './interfaces';
 import { Scope } from './scope';
 
 /**
@@ -369,8 +370,8 @@ export class Hub implements HubInterface {
   /**
    * @inheritDoc
    */
-  public startTransaction(context: TransactionContext): Transaction {
-    return this._callExtensionMethod('startTransaction', context);
+  public startTransaction(context: TransactionContext, customSamplingContext?: CustomSamplingContext): Transaction {
+    return this._callExtensionMethod('startTransaction', context, customSamplingContext);
   }
 
   /**
@@ -456,22 +457,24 @@ export function getCurrentHub(): Hub {
   return getHubFromCarrier(registry);
 }
 
+/**
+ * Returns the active domain, if one exists
+ *
+ * @returns The domain, or undefined if there is no active domain
+ */
+export function getActiveDomain(): DomainAsCarrier | undefined {
+  const sentry = getMainCarrier().__SENTRY__;
+
+  return sentry && sentry.extensions && sentry.extensions.domain && sentry.extensions.domain.active;
+}
+
 /**
  * Try to read the hub from an active domain, and fallback to the registry if one doesn't exist
  * @returns discovered hub
  */
 function getHubFromActiveDomain(registry: Carrier): Hub {
   try {
-    const property = 'domain';
-    const carrier = getMainCarrier();
-    const sentry = carrier.__SENTRY__;
-    if (!sentry || !sentry.extensions || !sentry.extensions[property]) {
-      return getHubFromCarrier(registry);
-    }
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const domain = sentry.extensions[property] as any;
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-    const activeDomain = domain.active;
+    const activeDomain = getActiveDomain();
 
     // If there's no active domain, just return global hub
     if (!activeDomain) {

packages/hub/src/index.ts

@@ -1,3 +1,11 @@
-export { Carrier, Layer } from './interfaces';
+export { Carrier, DomainAsCarrier, Layer } from './interfaces';
 export { addGlobalEventProcessor, Scope } from './scope';
-export { getCurrentHub, getHubFromCarrier, getMainCarrier, Hub, makeMain, setHubOnCarrier } from './hub';
+export {
+  getActiveDomain,
+  getCurrentHub,
+  getHubFromCarrier,
+  getMainCarrier,
+  Hub,
+  makeMain,
+  setHubOnCarrier,
+} from './hub';

packages/hub/src/interfaces.ts

@@ -1,4 +1,5 @@
 import { Client } from '@sentry/types';
+import * as domain from 'domain';
 
 import { Hub } from './hub';
 import { Scope } from './scope';
@@ -20,9 +21,23 @@ export interface Carrier {
   __SENTRY__?: {
     hub?: Hub;
     /**
-     * These are extension methods for the hub, the current instance of the hub will be bound to it
+     * Extra Hub properties injected by various SDKs
      */
-    // eslint-disable-next-line @typescript-eslint/ban-types
-    extensions?: { [key: string]: Function };
+    extensions?: {
+      /** Hack to prevent bundlers from breaking our usage of the domain package in the cross-platform Hub package */
+      domain?: typeof domain & {
+        /**
+         * The currently active domain. This is part of the domain package, but for some reason not declared in the
+         * package's typedef.
+         */
+        active?: domain.Domain;
+      };
+    } & {
+      /** Extension methods for the hub, which are bound to the current Hub instance */
+      // eslint-disable-next-line @typescript-eslint/ban-types
+      [key: string]: Function;
+    };
   };
 }
+
+export interface DomainAsCarrier extends domain.Domain, Carrier {}

packages/minimal/src/index.ts

@@ -2,6 +2,7 @@ import { getCurrentHub, Hub, Scope } from '@sentry/hub';
 import {
   Breadcrumb,
   CaptureContext,
+  CustomSamplingContext,
   Event,
   Extra,
   Extras,
@@ -190,22 +191,25 @@ export function _callOnClient(method: string, ...args: any[]): void {
 }
 
 /**
- * Starts a new `Transaction` and returns it. This is the entry point to manual
- * tracing instrumentation.
+ * Starts a new `Transaction` and returns it. This is the entry point to manual tracing instrumentation.
  *
- * A tree structure can be built by adding child spans to the transaction, and
- * child spans to other spans. To start a new child span within the transaction
- * or any span, call the respective `.startChild()` method.
+ * A tree structure can be built by adding child spans to the transaction, and child spans to other spans. To start a
+ * new child span within the transaction or any span, call the respective `.startChild()` method.
  *
- * Every child span must be finished before the transaction is finished,
- * otherwise the unfinished spans are discarded.
+ * Every child span must be finished before the transaction is finished, otherwise the unfinished spans are discarded.
  *
- * The transaction must be finished with a call to its `.finish()` method, at
- * which point the transaction with all its finished child spans will be sent to
- * Sentry.
+ * The transaction must be finished with a call to its `.finish()` method, at which point the transaction with all its
+ * finished child spans will be sent to Sentry.
  *
  * @param context Properties of the new `Transaction`.
+ * @param customSamplingContext Information given to the transaction sampling function (along with context-dependent
+ * default values). See {@link Options.tracesSampler}.
+ *
+ * @returns The transaction which was just started
  */
-export function startTransaction(context: TransactionContext): Transaction {
-  return callOnHub('startTransaction', { ...context });
+export function startTransaction(
+  context: TransactionContext,
+  customSamplingContext?: CustomSamplingContext,
+): Transaction {
+  return callOnHub('startTransaction', { ...context }, customSamplingContext);
 }