feat(am): Introduce startTransaction

CHANGELOG.md

@@ -16,6 +16,7 @@
 - [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 `startChild` #2600
 
 ## 5.15.5
 

packages/apm/src/hubextensions.ts

@@ -1,7 +1,8 @@
 import { getMainCarrier, Hub } from '@sentry/hub';
-import { SpanContext } from '@sentry/types';
+import { SpanContext, TransactionContext } from '@sentry/types';
 
 import { Span } from './span';
+import { Transaction } from './transaction';
 
 /** Returns all trace headers that are currently on the top scope. */
 function traceHeaders(): { [key: string]: string } {
@@ -26,43 +27,50 @@ function traceHeaders(): { [key: string]: string } {
  *
  * @param spanContext Properties with which the span should be created
  */
-function startSpan(spanContext?: SpanContext): Span {
+function startSpan(spanOrTransactionContext: SpanContext | TransactionContext): Transaction | Span {
   // @ts-ignore
   const hub = this as Hub;
   const scope = hub.getScope();
   const client = hub.getClient();
-  let span;
 
-  // 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;
+  let newSpanContext = spanOrTransactionContext;
 
+  // We create an empty Span in case there is no scope on the hub
+  let parentSpan = new Span();
   if (scope) {
-    const parentSpan = scope.getSpan() as Span;
+    // If there is a Span on the Scope we use the span_id / trace_id
+    // To define the parent <-> child relationship
+    parentSpan = scope.getSpan() as Span;
     if (parentSpan) {
-      span = parentSpan.child(spanContext);
-      addedAsChild = true;
+      const { trace_id } = parentSpan.getTraceContext();
+      newSpanContext = {
+        traceId: trace_id,
+        ...spanOrTransactionContext,
+      };
     }
   }
 
-  if (!span) {
-    span = new Span(spanContext, hub);
-  }
+  // We are dealing with a Transaction
+  if ((newSpanContext as TransactionContext).name) {
+    const transaction = new Transaction(newSpanContext as TransactionContext, hub);
 
-  // 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;
-  }
+    // 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;
+      transaction.sampled = Math.random() < sampleRate;
+    }
+
+    // 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 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);
+    return transaction;
   }
 
-  return span;
+  return new Span(newSpanContext);
 }
 
 /**

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,4 +1,4 @@
-import { EventProcessor, Hub, Integration } from '@sentry/types';
+import { Integration } from '@sentry/types';
 import { logger } from '@sentry/utils';
 // tslint:disable-next-line:no-implicit-dependencies
 import { Application, ErrorRequestHandler, NextFunction, Request, RequestHandler, Response } from 'express';
@@ -35,12 +35,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,42 +56,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());
+        // tslint:disable: no-unsafe-any
+        const transaction = (res as any).getTransaction && (res as any).getTransaction();
+        if (transaction) {
+          const span = transaction.startChild({
+            description: fn.name,
+            op: 'middleware',
+          });
+          res.once('finish', () => {
+            span.finish();
+          });
+        }
+        // tslint:enable: no-unsafe-any
         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',
-        });
-        fn.call(this, req, res, function(this: NodeJS.Global): any {
-          span.finish();
-          return next.apply(this, arguments);
-        });
+        // tslint:disable: no-unsafe-any
+        const transaction = (res as any).getTransaction && (res as any).getTransaction();
+        if (transaction) {
+          const span = transaction.startChild({
+            description: fn.name,
+            op: 'middleware',
+          });
+          fn.call(this, req, res, function(this: NodeJS.Global): any {
+            span.finish();
+            return next.apply(this, arguments);
+          });
+        } else {
+          fn.call(this, req, res, function(this: NodeJS.Global): any {
+            return next.apply(this, arguments);
+          });
+        }
+        // tslint:enable: no-unsafe-any
       };
     }
     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',
-        });
-        fn.call(this, err, req, res, function(this: NodeJS.Global): any {
-          span.finish();
-          return next.apply(this, arguments);
-        });
+        // tslint:disable: no-unsafe-any
+        const transaction = (res as any).getTransaction && (res as any).getTransaction();
+        if (transaction) {
+          const span = transaction.startChild({
+            description: fn.name,
+            op: 'middleware',
+          });
+          fn.call(this, err, req, res, function(this: NodeJS.Global): any {
+            span.finish();
+            return next.apply(this, arguments);
+          });
+        } else {
+          fn.call(this, err, req, res, function(this: NodeJS.Global): any {
+            return next.apply(this, arguments);
+          });
+        }
       };
     }
     default: {
@@ -110,16 +134,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 +156,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;
 }