feat(node): Add tracePropagationTargets option

Author: Luca Forstner

packages/node-integration-tests/suites/tracing/tracePropagationTargets/scenario.ts

@@ -0,0 +1,26 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import '@sentry/tracing';
+
+import * as Sentry from '@sentry/node';
+import * as http from 'http';
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  tracePropagationTargets: [/\/v0/, 'v1'],
+  integrations: [new Sentry.Integrations.Http({ tracing: true })],
+});
+
+const transaction = Sentry.startTransaction({ name: 'test_transaction' });
+
+Sentry.configureScope(scope => {
+  scope.setSpan(transaction);
+});
+
+http.get('http://match-this-url.com/api/v0');
+http.get('http://match-this-url.com/api/v1');
+http.get('http://dont-match-this-url.com/api/v2');
+http.get('http://dont-match-this-url.com/api/v3');
+
+transaction.finish();

packages/node-integration-tests/suites/tracing/tracePropagationTargets/test.ts

@@ -0,0 +1,37 @@
+import nock from 'nock';
+
+import { runScenario, runServer } from '../../../utils';
+
+test('HttpIntegration should instrument correct requests when tracePropagationTargets option is provided', async () => {
+  const match1 = nock('http://match-this-url.com')
+    .get('/api/v0')
+    .matchHeader('baggage', val => typeof val === 'string')
+    .matchHeader('sentry-trace', val => typeof val === 'string')
+    .reply(200);
+
+  const match2 = nock('http://match-this-url.com')
+    .get('/api/v1')
+    .matchHeader('baggage', val => typeof val === 'string')
+    .matchHeader('sentry-trace', val => typeof val === 'string')
+    .reply(200);
+
+  const match3 = nock('http://dont-match-this-url.com')
+    .get('/api/v2')
+    .matchHeader('baggage', val => val === undefined)
+    .matchHeader('sentry-trace', val => val === undefined)
+    .reply(200);
+
+  const match4 = nock('http://dont-match-this-url.com')
+    .get('/api/v3')
+    .matchHeader('baggage', val => val === undefined)
+    .matchHeader('sentry-trace', val => val === undefined)
+    .reply(200);
+
+  const serverUrl = await runServer(__dirname);
+  await runScenario(serverUrl);
+
+  expect(match1.isDone()).toBe(true);
+  expect(match2.isDone()).toBe(true);
+  expect(match3.isDone()).toBe(true);
+  expect(match4.isDone()).toBe(true);
+});

packages/node-integration-tests/utils/index.ts

@@ -152,12 +152,16 @@ export async function runServer(testDir: string, serverPath?: string, scenarioPa
   const url = `http://localhost:${port}/test`;
   const defaultServerPath = path.resolve(process.cwd(), 'utils', 'defaults', 'server');
 
-  await new Promise(resolve => {
+  await new Promise<void>(resolve => {
     // eslint-disable-next-line @typescript-eslint/no-var-requires, @typescript-eslint/no-unsafe-member-access
     const app = require(serverPath || defaultServerPath).default as Express;
 
-    app.get('/test', async () => {
-      require(scenarioPath || `${testDir}/scenario`);
+    app.get('/test', (_req, res) => {
+      try {
+        require(scenarioPath || `${testDir}/scenario`);
+      } finally {
+        res.status(200).end();
+      }
     });
 
     const server = app.listen(port, () => {
@@ -170,3 +174,14 @@ export async function runServer(testDir: string, serverPath?: string, scenarioPa
 
   return url;
 }
+
+export async function runScenario(serverUrl: string): Promise<void> {
+  return new Promise<void>(resolve => {
+    http
+      .get(serverUrl, res => {
+        res.on('data', () => undefined);
+        res.on('end', resolve);
+      })
+      .end();
+  });
+}

packages/node/src/integrations/http.ts

@@ -1,9 +1,10 @@
-import { getCurrentHub } from '@sentry/core';
-import { Integration, Span } from '@sentry/types';
-import { fill, logger, mergeAndSerializeBaggage, parseSemver } from '@sentry/utils';
+import { getCurrentHub, Hub } from '@sentry/core';
+import { EventProcessor, Integration, Span } from '@sentry/types';
+import { fill, isMatchingPattern, logger, mergeAndSerializeBaggage, parseSemver } from '@sentry/utils';
 import * as http from 'http';
 import * as https from 'https';
 
+import { NodeClientOptions } from '../types';
 import {
   cleanSpanDescription,
   extractUrl,
@@ -15,7 +16,10 @@ import {
 
 const NODE_VERSION = parseSemver(process.versions.node);
 
-/** http module integration */
+/**
+ * The http module integration instruments nodes internal http module. It creates breadcrumbs, transactions for outgoing
+ * http requests and attaches trace data when tracing is enabled via its `tracing` option.
+ */
 export class Http implements Integration {
   /**
    * @inheritDoc
@@ -48,13 +52,22 @@ export class Http implements Integration {
   /**
    * @inheritDoc
    */
-  public setupOnce(): void {
+  public setupOnce(
+    _addGlobalEventProcessor: (callback: EventProcessor) => void,
+    setupOnceGetCurrentHub: () => Hub,
+  ): void {
     // No need to instrument if we don't want to track anything
     if (!this._breadcrumbs && !this._tracing) {
       return;
     }
 
-    const wrappedHandlerMaker = _createWrappedRequestMethodFactory(this._breadcrumbs, this._tracing);
+    const clientOptions = setupOnceGetCurrentHub().getClient()?.getOptions() as NodeClientOptions | undefined;
+
+    const wrappedHandlerMaker = _createWrappedRequestMethodFactory(
+      this._breadcrumbs,
+      this._tracing,
+      clientOptions?.tracePropagationTargets,
+    );
 
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const httpModule = require('http');
@@ -90,7 +103,26 @@ type WrappedRequestMethodFactory = (original: OriginalRequestMethod) => WrappedR
 function _createWrappedRequestMethodFactory(
   breadcrumbsEnabled: boolean,
   tracingEnabled: boolean,
+  tracePropagationTargets: (string | RegExp)[] | undefined,
 ): WrappedRequestMethodFactory {
+  // We're caching results so we dont have to recompute regexp everytime we create a request.
+  const urlMap: Record<string, boolean> = {};
+  const shouldAttachTraceData = (url: string): boolean => {
+    if (tracePropagationTargets === undefined) {
+      return true;
+    }
+
+    if (urlMap[url]) {
+      return urlMap[url];
+    }
+
+    urlMap[url] = tracePropagationTargets.some(tracePropagationTarget =>
+      isMatchingPattern(url, tracePropagationTarget),
+    );
+
+    return urlMap[url];
+  };
+
   return function wrappedRequestMethodFactory(originalRequestMethod: OriginalRequestMethod): WrappedRequestMethod {
     return function wrappedMethod(this: typeof http | typeof https, ...args: RequestMethodArgs): http.ClientRequest {
       // eslint-disable-next-line @typescript-eslint/no-this-alias
@@ -109,28 +141,37 @@ function _createWrappedRequestMethodFactory(
       let parentSpan: Span | undefined;
 
       const scope = getCurrentHub().getScope();
+
       if (scope && tracingEnabled) {
         parentSpan = scope.getSpan();
+
         if (parentSpan) {
           span = parentSpan.startChild({
             description: `${requestOptions.method || 'GET'} ${requestUrl}`,
             op: 'http.client',
           });
 
-          const sentryTraceHeader = span.toTraceparent();
-          __DEBUG_BUILD__ &&
-            logger.log(
-              `[Tracing] Adding sentry-trace header ${sentryTraceHeader} to outgoing request to ${requestUrl}: `,
-            );
-
-          const baggage = parentSpan.transaction && parentSpan.transaction.getBaggage();
-          const headerBaggageString = requestOptions.headers && requestOptions.headers.baggage;
-
-          requestOptions.headers = {
-            ...requestOptions.headers,
-            'sentry-trace': sentryTraceHeader,
-            baggage: mergeAndSerializeBaggage(baggage, headerBaggageString),
-          };
+          if (shouldAttachTraceData(requestUrl)) {
+            const sentryTraceHeader = span.toTraceparent();
+            __DEBUG_BUILD__ &&
+              logger.log(
+                `[Tracing] Adding sentry-trace header ${sentryTraceHeader} to outgoing request to "${requestUrl}": `,
+              );
+
+            const baggage = parentSpan.transaction && parentSpan.transaction.getBaggage();
+            const headerBaggageString = requestOptions.headers && requestOptions.headers.baggage;
+
+            requestOptions.headers = {
+              ...requestOptions.headers,
+              'sentry-trace': sentryTraceHeader,
+              baggage: mergeAndSerializeBaggage(baggage, headerBaggageString),
+            };
+          } else {
+            __DEBUG_BUILD__ &&
+              logger.log(
+                `[Tracing] Not adding sentry-trace header to outgoing request (${requestUrl}) due to mismatching tracePropagationTargets option.`,
+              );
+          }
         }
       }
 

packages/node/src/types.ts

@@ -6,6 +6,19 @@ export interface BaseNodeOptions {
   /** Sets an optional server name (device name) */
   serverName?: string;
 
+  // We have this option seperately in both the node options and the browser options, so that we can have different JSDoc
+  // comments, since this has different behaviour in the Browser and Node SDKs.
+  /**
+   * List of strings/regex controlling to which outgoing requests
+   * the SDK will attach tracing headers.
+   *
+   * By default the SDK will attach those headers to all outgoing
+   * requests. If this option is provided, the SDK will match the
+   * request URL of outgoing requests against the items in this
+   * array, and only attach tracing headers if a match was found.
+   */
+  tracePropagationTargets?: (string | RegExp)[];
+
   /** Callback that is executed when a fatal global error occurs. */
   onFatalError?(error: Error): void;
 }

packages/node/test/integrations/http.test.ts

@@ -17,6 +17,9 @@ import { getDefaultNodeClientOptions } from '../helper/node-client-options';
 
 const NODE_VERSION = parseSemver(process.versions.node);
 
+const originalHttpGet = http.get;
+const originalHttpRequest = http.request;
+
 describe('tracing', () => {
   function createTransactionOnScope(
     customOptions: Partial<NodeClientOptions> = {},
@@ -168,6 +171,110 @@ describe('tracing', () => {
 
     expect(baggage).not.toBeDefined();
   });
+
+  describe('tracePropagationTargets option', () => {
+    beforeEach(() => {
+      // hacky way of restoring monkey patched functions
+      // @ts-ignore TS doesn't let us assign to this but we want to
+      http.get = originalHttpGet;
+      // @ts-ignore TS doesn't let us assign to this but we want to
+      http.request = originalHttpRequest;
+    });
+
+    function createHub(customOptions: Partial<NodeClientOptions> = {}) {
+      const options = getDefaultNodeClientOptions({
+        dsn: 'https://[email protected]/12312012',
+        tracesSampleRate: 1.0,
+        release: '1.0.0',
+        environment: 'production',
+        ...customOptions,
+      });
+
+      const hub = new Hub();
+
+      // we need to mock both of these because the tracing handler relies on `@sentry/core` while the sampler relies on
+      // `@sentry/hub`, and mocking breaks the link between the two
+      jest.spyOn(sentryCore, 'getCurrentHub').mockImplementation(() => hub);
+      jest.spyOn(hubModule, 'getCurrentHub').mockImplementation(() => hub);
+
+      const client = new NodeClient(options);
+      jest.spyOn(hub, 'getClient').mockImplementation(() => client);
+      hub.bindClient(client);
+
+      return hub;
+    }
+
+    function createTransactionAndPutOnScope(hub: Hub) {
+      addExtensionMethods();
+      const transaction = hub.startTransaction({ name: 'dogpark' });
+      hub.getScope()?.setSpan(transaction);
+    }
+
+    it.each([
+      ['http://dogs.are.great/api/v1/index/', [/.*/]],
+      ['http://dogs.are.great/api/v1/index/', [/\/api/]],
+      ['http://dogs.are.great/api/v1/index/', [/\/(v1|v2)/]],
+      ['http://dogs.are.great/api/v1/index/', [/dogs\.are\.great/, /dogs\.are\.not\.great/]],
+      ['http://dogs.are.great/api/v1/index/', [/http:/]],
+      ['http://dogs.are.great/api/v1/index/', ['dogs.are.great']],
+      ['http://dogs.are.great/api/v1/index/', ['/api/v1']],
+      ['http://dogs.are.great/api/v1/index/', ['http://']],
+      ['http://dogs.are.great/api/v1/index/', ['']],
+    ])(
+      'attaches trace inforation to header of outgoing requests when url matches tracePropagationTargets (url="%s", tracePropagationTargets=%p)',
+      (url, tracePropagationTargets) => {
+        nock(url).get(/.*/).reply(200);
+
+        const httpIntegration = new HttpIntegration({ tracing: true });
+
+        const hub = createHub({ tracePropagationTargets });
+
+        httpIntegration.setupOnce(
+          () => undefined,
+          () => hub,
+        );
+
+        createTransactionAndPutOnScope(hub);
+
+        const request = http.get(url);
+
+        expect(request.getHeader('sentry-trace')).toBeDefined();
+        expect(request.getHeader('baggage')).toBeDefined();
+      },
+    );
+
+    it.each([
+      ['http://dogs.are.great/api/v1/index/', []],
+      ['http://cats.are.great/api/v1/index/', [/\/v2/]],
+      ['http://cats.are.great/api/v1/index/', [/\/(v2|v3)/]],
+      ['http://cats.are.great/api/v1/index/', [/dogs\.are\.great/, /dogs\.are\.not\.great/]],
+      ['http://cats.are.great/api/v1/index/', [/https:/]],
+      ['http://cats.are.great/api/v1/index/', ['dogs.are.great']],
+      ['http://cats.are.great/api/v1/index/', ['/api/v2']],
+      ['http://cats.are.great/api/v1/index/', ['https://']],
+    ])(
+      'doesn\'t attach trace inforation to header of outgoing requests when url doesn\'t match tracePropagationTargets (url="%s", tracePropagationTargets=%p)',
+      (url, tracePropagationTargets) => {
+        nock(url).get(/.*/).reply(200);
+
+        const httpIntegration = new HttpIntegration({ tracing: true });
+
+        const hub = createHub({ tracePropagationTargets });
+
+        httpIntegration.setupOnce(
+          () => undefined,
+          () => hub,
+        );
+
+        createTransactionAndPutOnScope(hub);
+
+        const request = http.get(url);
+
+        expect(request.getHeader('sentry-trace')).not.toBeDefined();
+        expect(request.getHeader('baggage')).not.toBeDefined();
+      },
+    );
+  });
 });
 
 describe('default protocols', () => {