feat(am): Introduce startTransaction

CHANGELOG.md

@@ -16,6 +16,8 @@
 - [core] fix: sent_at for envelope headers to use same clock #2597
 - [apm] fix: Improve bundle size by moving span status to @sentry/apm #2589
 - [apm] feat: No longer discard transactions instead mark them deadline exceeded #2588
+- [apm] feat: Introduce `Sentry.startTransaction` and `Transaction.startChild` #2600
+- [apm] feat: Transactions no longer go through `beforeSend` #2600
 - [browser] fix: Emit Sentry Request breadcrumbs from inside the client (#2615)
 
 ## 5.15.5

packages/apm/src/hubextensions.ts

@@ -1,13 +1,13 @@
 import { getMainCarrier, Hub } from '@sentry/hub';
-import { SpanContext } from '@sentry/types';
+import { SpanContext, TransactionContext } from '@sentry/types';
+import { logger } from '@sentry/utils';
 
 import { Span } from './span';
+import { Transaction } from './transaction';
 
 /** Returns all trace headers that are currently on the top scope. */
-function traceHeaders(): { [key: string]: string } {
-  // @ts-ignore
-  const that = this as Hub;
-  const scope = that.getScope();
+function traceHeaders(this: Hub): { [key: string]: string } {
+  const scope = this.getScope();
   if (scope) {
     const span = scope.getSpan();
     if (span) {
@@ -24,45 +24,53 @@ function traceHeaders(): { [key: string]: string } {
  * the created Span with the SpanContext will have a reference to it and become it's child.
  * Otherwise it'll crete a new `Span`.
  *
- * @param spanContext Properties with which the span should be created
+ * @param context Properties with which the span should be created
  */
-function startSpan(spanContext?: SpanContext): Span {
-  // @ts-ignore
-  const hub = this as Hub;
-  const scope = hub.getScope();
-  const client = hub.getClient();
-  let span;
+function startSpan(this: Hub, context: SpanContext | TransactionContext): Transaction | Span {
+  // This is our safeguard so people always get a Transaction in return.
+  // We set `_isTransaction: true` in {@link Sentry.startTransaction} to have a runtime check
+  // if the user really wanted to create a Transaction.
+  if ((context as TransactionContext)._isTransaction && !(context as TransactionContext).name) {
+    logger.warn('You are trying to start a Transaction but forgot to provide a `name` property.');
+    logger.warn('Will fall back to <unlabeled transaction>, use `transaction.setName()` to change it.');
+    (context as TransactionContext).name = '<unlabeled transaction>';
+  }
 
-  // This flag determines if we already added the span as a child to the span that currently lives on the scope
-  // If we do not have this, we will add it later on twice to the span recorder and therefore have too many spans
-  let addedAsChild = false;
+  if ((context as TransactionContext).name) {
+    // We are dealing with a Transaction
+    const transaction = new Transaction(context as TransactionContext, this);
 
-  if (scope) {
-    const parentSpan = scope.getSpan() as Span;
-    if (parentSpan) {
-      span = parentSpan.child(spanContext);
-      addedAsChild = true;
+    const client = this.getClient();
+    // We only roll the dice on sampling for root spans of transactions because all child spans inherit this state
+    if (transaction.sampled === undefined) {
+      const sampleRate = (client && client.getOptions().tracesSampleRate) || 0;
+      // if true = we want to have the transaction
+      // if false = we don't want to have it
+      // Math.random (inclusive of 0, but not 1)
+      transaction.sampled = Math.random() < sampleRate;
     }
-  }
 
-  if (!span) {
-    span = new Span(spanContext, hub);
-  }
+    // We only want to create a span list if we sampled the transaction
+    // If sampled == false, we will discard the span anyway, so we can save memory by not storing child spans
+    if (transaction.sampled) {
+      const experimentsOptions = (client && client.getOptions()._experiments) || {};
+      transaction.initSpanRecorder(experimentsOptions.maxSpans as number);
+    }
 
-  // We only roll the dice on sampling for "root" spans (transactions) because the childs inherit this state
-  if (span.sampled === undefined && span.isRootSpan()) {
-    const sampleRate = (client && client.getOptions().tracesSampleRate) || 0;
-    span.sampled = Math.random() < sampleRate;
+    return transaction;
   }
 
-  // We only want to create a span list if we sampled the transaction
-  // in case we will discard the span anyway because sampled == false, we safe memory and do not store child spans
-  if (span.sampled && !addedAsChild) {
-    const experimentsOptions = (client && client.getOptions()._experiments) || {};
-    span.initSpanRecorder(experimentsOptions.maxSpans as number);
+  const scope = this.getScope();
+  if (scope) {
+    // If there is a Span on the Scope we start a child and return that instead
+    const parentSpan = scope.getSpan();
+    if (parentSpan) {
+      return parentSpan.startChild(context);
+    }
   }
 
-  return span;
+  // Otherwise we return a new Span
+  return new Span(context);
 }
 
 /**

packages/apm/src/index.ts

@@ -3,6 +3,7 @@ import * as ApmIntegrations from './integrations';
 
 export { ApmIntegrations as Integrations };
 export { Span, TRACEPARENT_REGEXP } from './span';
+export { Transaction } from './transaction';
 
 export { SpanStatus } from './spanstatus';
 

packages/apm/src/integrations/express.ts

@@ -1,8 +1,16 @@
-import { EventProcessor, Hub, Integration } from '@sentry/types';
+import { Integration, Transaction } from '@sentry/types';
 import { logger } from '@sentry/utils';
 // tslint:disable-next-line:no-implicit-dependencies
 import { Application, ErrorRequestHandler, NextFunction, Request, RequestHandler, Response } from 'express';
 
+/**
+ * Internal helper for `__sentry_transaction`
+ * @hidden
+ */
+interface SentryTracingResponse {
+  __sentry_transaction?: Transaction;
+}
+
 /**
  * Express integration
  *
@@ -35,12 +43,12 @@ export class Express implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(_addGlobalEventProcessor: (callback: EventProcessor) => void, getCurrentHub: () => Hub): void {
+  public setupOnce(): void {
     if (!this._app) {
       logger.error('ExpressIntegration is missing an Express instance');
       return;
     }
-    instrumentMiddlewares(this._app, getCurrentHub);
+    instrumentMiddlewares(this._app);
   }
 }
 
@@ -56,40 +64,66 @@ export class Express implements Integration {
  * // error handler
  * app.use(function (err, req, res, next) { ... })
  */
-function wrap(fn: Function, getCurrentHub: () => Hub): RequestHandler | ErrorRequestHandler {
+function wrap(fn: Function): RequestHandler | ErrorRequestHandler {
   const arrity = fn.length;
 
   switch (arrity) {
     case 2: {
-      return function(this: NodeJS.Global, _req: Request, res: Response): any {
-        const span = getCurrentHub().startSpan({
-          description: fn.name,
-          op: 'middleware',
-        });
-        res.once('finish', () => span.finish());
+      return function(this: NodeJS.Global, _req: Request, res: Response & SentryTracingResponse): any {
+        const transaction = res.__sentry_transaction;
+        if (transaction) {
+          const span = transaction.startChild({
+            description: fn.name,
+            op: 'middleware',
+          });
+          res.once('finish', () => {
+            span.finish();
+          });
+        }
         return fn.apply(this, arguments);
       };
     }
     case 3: {
-      return function(this: NodeJS.Global, req: Request, res: Response, next: NextFunction): any {
-        const span = getCurrentHub().startSpan({
-          description: fn.name,
-          op: 'middleware',
-        });
+      return function(
+        this: NodeJS.Global,
+        req: Request,
+        res: Response & SentryTracingResponse,
+        next: NextFunction,
+      ): any {
+        const transaction = res.__sentry_transaction;
+        const span =
+          transaction &&
+          transaction.startChild({
+            description: fn.name,
+            op: 'middleware',
+          });
         fn.call(this, req, res, function(this: NodeJS.Global): any {
-          span.finish();
+          if (span) {
+            span.finish();
+          }
           return next.apply(this, arguments);
         });
       };
     }
     case 4: {
-      return function(this: NodeJS.Global, err: any, req: Request, res: Response, next: NextFunction): any {
-        const span = getCurrentHub().startSpan({
-          description: fn.name,
-          op: 'middleware',
-        });
+      return function(
+        this: NodeJS.Global,
+        err: any,
+        req: Request,
+        res: Response & SentryTracingResponse,
+        next: NextFunction,
+      ): any {
+        const transaction = res.__sentry_transaction;
+        const span =
+          transaction &&
+          transaction.startChild({
+            description: fn.name,
+            op: 'middleware',
+          });
         fn.call(this, err, req, res, function(this: NodeJS.Global): any {
-          span.finish();
+          if (span) {
+            span.finish();
+          }
           return next.apply(this, arguments);
         });
       };
@@ -110,16 +144,16 @@ function wrap(fn: Function, getCurrentHub: () => Hub): RequestHandler | ErrorReq
  * app.use([<path>], <fn>, ...<fn>)
  * app.use([<path>], ...<fn>[])
  */
-function wrapUseArgs(args: IArguments, getCurrentHub: () => Hub): unknown[] {
+function wrapUseArgs(args: IArguments): unknown[] {
   return Array.from(args).map((arg: unknown) => {
     if (typeof arg === 'function') {
-      return wrap(arg, getCurrentHub);
+      return wrap(arg);
     }
 
     if (Array.isArray(arg)) {
       return arg.map((a: unknown) => {
         if (typeof a === 'function') {
-          return wrap(a, getCurrentHub);
+          return wrap(a);
         }
         return a;
       });
@@ -132,10 +166,10 @@ function wrapUseArgs(args: IArguments, getCurrentHub: () => Hub): unknown[] {
 /**
  * Patches original app.use to utilize our tracing functionality
  */
-function instrumentMiddlewares(app: Application, getCurrentHub: () => Hub): Application {
+function instrumentMiddlewares(app: Application): Application {
   const originalAppUse = app.use;
   app.use = function(): any {
-    return originalAppUse.apply(this, wrapUseArgs(arguments, getCurrentHub));
+    return originalAppUse.apply(this, wrapUseArgs(arguments));
   };
   return app;
 }