add specific types for default and custom sample context data

Author: lobsterkatie

packages/hub/src/hub.ts

@@ -3,14 +3,14 @@ import {
   Breadcrumb,
   BreadcrumbHint,
   Client,
+  CustomSampleContext,
   Event,
   EventHint,
   Extra,
   Extras,
   Hub as HubInterface,
   Integration,
   IntegrationClass,
-  SampleContext,
   Severity,
   Span,
   SpanContext,
@@ -370,8 +370,8 @@ export class Hub implements HubInterface {
   /**
    * @inheritDoc
    */
-  public startTransaction(context: TransactionContext, sampleContext?: SampleContext): Transaction {
-    return this._callExtensionMethod('startTransaction', context, sampleContext);
+  public startTransaction(context: TransactionContext, customSampleContext?: CustomSampleContext): Transaction {
+    return this._callExtensionMethod('startTransaction', context, customSampleContext);
   }
 
   /**

packages/minimal/src/index.ts

@@ -2,10 +2,10 @@ import { getCurrentHub, Hub, Scope } from '@sentry/hub';
 import {
   Breadcrumb,
   CaptureContext,
+  CustomSampleContext,
   Event,
   Extra,
   Extras,
-  SampleContext,
   Severity,
   Transaction,
   TransactionContext,
@@ -206,8 +206,9 @@ export function _callOnClient(method: string, ...args: any[]): void {
  * Sentry.
  *
  * @param context Properties of the new `Transaction`.
- * @param sampleContext Information given to the transaction sampling function
+ * @param customSampleContext Information given to the transaction sampling function (along with context-dependent
+ * default values)
  */
-export function startTransaction(context: TransactionContext, sampleContext?: SampleContext): Transaction {
-  return callOnHub('startTransaction', { ...context }, sampleContext);
+export function startTransaction(context: TransactionContext, customSampleContext?: CustomSampleContext): Transaction {
+  return callOnHub('startTransaction', { ...context }, customSampleContext);
 }

packages/tracing/src/hubextensions.ts

@@ -1,5 +1,5 @@
 import { getActiveDomain, getMainCarrier, Hub } from '@sentry/hub';
-import { SampleContext, TransactionContext } from '@sentry/types';
+import { CustomSampleContext, DefaultSampleContext, SampleContext, TransactionContext } from '@sentry/types';
 import {
   dynamicRequire,
   extractNodeRequestData,
@@ -98,10 +98,10 @@ function sample<T extends Transaction>(hub: Hub, transaction: T, sampleContext:
 /**
  * Gets the correct context to pass to the tracesSampler, based on the environment (i.e., which SDK is being used)
  *
- * @returns A SampleContext object
+ * @returns The default sample context
  */
-function getDefaultSampleContext(): SampleContext {
-  const defaultSampleContext: SampleContext = {};
+function getDefaultSampleContext(): DefaultSampleContext {
+  const defaultSampleContext: DefaultSampleContext = {};
 
   if (isNodeEnv()) {
     const domain = getActiveDomain();
@@ -171,9 +171,13 @@ function isValidSampleRate(rate: unknown): boolean {
  *
  * @see {@link Hub.startTransaction}
  */
-function _startTransaction(this: Hub, context: TransactionContext, sampleContext?: SampleContext): Transaction {
+function _startTransaction(
+  this: Hub,
+  context: TransactionContext,
+  customSampleContext?: CustomSampleContext,
+): Transaction {
   const transaction = new Transaction(context, this);
-  return sample(this, transaction, { ...getDefaultSampleContext(), ...sampleContext });
+  return sample(this, transaction, { ...getDefaultSampleContext(), ...customSampleContext });
 }
 
 /**

packages/types/src/hub.ts

@@ -6,7 +6,7 @@ import { Integration, IntegrationClass } from './integration';
 import { Scope } from './scope';
 import { Severity } from './severity';
 import { Span, SpanContext } from './span';
-import { SampleContext, Transaction, TransactionContext } from './transaction';
+import { CustomSampleContext, Transaction, TransactionContext } from './transaction';
 import { User } from './user';
 
 /**
@@ -198,7 +198,8 @@ export interface Hub {
    * Sentry.
    *
    * @param context Properties of the new `Transaction`.
-   * @param sampleContext Information given to the transaction sampling function
+   * @param customSampleContext Information given to the transaction sampling function (along with context-dependent
+   * default values)
    */
-  startTransaction(context: TransactionContext, sampleContext?: SampleContext): Transaction;
+  startTransaction(context: TransactionContext, customSampleContext?: CustomSampleContext): Transaction;
 }

packages/types/src/index.ts

@@ -10,6 +10,7 @@ export { Hub } from './hub';
 export { Integration, IntegrationClass } from './integration';
 export { LogLevel } from './loglevel';
 export { Mechanism } from './mechanism';
+export { ExtractedNodeRequestData, WorkerLocation } from './misc';
 export { Options } from './options';
 export { Package } from './package';
 export { Request } from './request';
@@ -22,7 +23,13 @@ export { Span, SpanContext } from './span';
 export { StackFrame } from './stackframe';
 export { Stacktrace } from './stacktrace';
 export { Status } from './status';
-export { SampleContext, Transaction, TransactionContext } from './transaction';
+export {
+  CustomSampleContext,
+  DefaultSampleContext,
+  SampleContext,
+  Transaction,
+  TransactionContext,
+} from './transaction';
 export { Thread } from './thread';
 export { Transport, TransportOptions, TransportClass } from './transport';
 export { User } from './user';

packages/types/src/misc.ts

@@ -0,0 +1,61 @@
+/**
+ * Data extracted from an incoming request to a node server
+ */
+export interface ExtractedNodeRequestData {
+  [key: string]: any;
+
+  /** Specific headers from the request */
+  headers?: { [key: string]: string };
+
+  /**  The request's method */
+  method?: string;
+
+  /** The request's URL, including query string */
+  url?: string;
+
+  /** String representing the cookies sent along with the request */
+  cookies?: { [key: string]: string };
+
+  /** The request's query string, without the leading '?' */
+  query_string?: string;
+
+  /** Any data sent in the request's body, as a JSON string */
+  data?: string;
+}
+
+/**
+ * Location object on a service worker's `self` object.
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/API/WorkerLocation.
+ */
+export interface WorkerLocation {
+  /** The protocol scheme of the URL of the script executed in the Worker, including the final ':'. */
+  readonly protocol: string;
+
+  /** The host, that is the hostname, a ':', and the port of the URL of the script executed in the Worker. */
+  readonly host: string;
+
+  /** The domain of the URL of the script executed in the Worker. */
+  readonly hostname: string;
+
+  /** The canonical form of the origin of the specific location. */
+  readonly origin: string;
+
+  /** The port number of the URL of the script executed in the Worker. */
+  readonly port: string;
+
+  /** The path of the URL of the script executed in the Worker, beginning with a '/'. */
+  readonly pathname: string;
+
+  /** The parameters (query string) of the URL of the script executed in the Worker, beginning with a '?'. */
+  readonly search: string;
+
+  /** The fragment identifier of the URL of the script executed in the Worker, beginning with a '#'. */
+  readonly hash: string;
+
+  /** Stringifier that returns the whole URL of the script executed in the Worker. */
+  readonly href: string;
+
+  /** Synonym for `href` attribute */
+  toString(): string;
+}

packages/types/src/transaction.ts

@@ -1,3 +1,4 @@
+import { ExtractedNodeRequestData, WorkerLocation } from './misc';
 import { Span, SpanContext } from './span';
 
 /**
@@ -50,9 +51,25 @@ export interface Transaction extends TransactionContext, Span {
 }
 
 /**
- * The data passed to the `tracesSampler` function, which forms the basis for whatever decisions it might make.
- * Combination of default values (which differ per SDK/integration) and data passed to `startTransaction`.
+ * The context passed to the tracesSampler function by default.
+ */
+export interface DefaultSampleContext {
+  /** Object representing the URL of the current page or woker script. Passed in a browser or service worker context */
+  location?: Location | WorkerLocation;
+
+  /** Object representing the incoming request to a node server. Passed when in a node server context. */
+  request?: ExtractedNodeRequestData;
+}
+
+/**
+ * Context data passed by the user when starting a transaction, to be used by the tracesSampler method.
  */
-export interface SampleContext {
+export interface CustomSampleContext {
   [key: string]: any;
 }
+
+/**
+ * The data passed to the `tracesSampler` function, which forms the basis for whatever decisions it might make.
+ * Combination of default values (which differ per SDK/integration) and data passed to `startTransaction`.
+ */
+export type SampleContext = DefaultSampleContext & CustomSampleContext;

packages/utils/src/node.ts

@@ -1,4 +1,6 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
+import { ExtractedNodeRequestData } from '@sentry/types';
+
 import { isString } from './is';
 import { normalize } from './object';
 
@@ -36,7 +38,7 @@ const DEFAULT_REQUEST_KEYS = ['cookies', 'data', 'headers', 'method', 'query_str
 export function extractNodeRequestData(
   req: { [key: string]: any },
   keys: string[] = DEFAULT_REQUEST_KEYS,
-): { [key: string]: string } {
+): ExtractedNodeRequestData {
   // make sure we can safely use dynamicRequire below
   if (!isNodeEnv()) {
     throw new Error("Can't get node request data outside of a node environment");