feat(instrumentation): Add allowUrls config option to web instrumentation

CHANGELOG.md

@@ -13,6 +13,10 @@ For semantic convention package changes, see the [semconv CHANGELOG](packages/se
 
 ### :rocket: (Enhancement)
 
+* feat(instrumentation): Add allowUrls config option to web instrumentation [#4938](https://github.com/open-telemetry/opentelemetry-js/pull/4938) @jairo-mendoza
+  * `XMLHttpRequestInstrumentation` and `FetchInstrumentation` now accept an `allowUrls` config option.
+  * `isUrlAllowed` function added to core. Both web instrumentation classes will depend on this function when using the new config option.
+
 ### :bug: (Bug Fix)
 
 ### :books: (Refine Doc)

experimental/CHANGELOG.md

@@ -9,6 +9,8 @@ All notable changes to experimental packages in this project will be documented
 
 ### :rocket: (Enhancement)
 
+* feat(instrumentation): Add allowUrls config option to web instrumentation [#4938](https://github.com/open-telemetry/opentelemetry-js/pull/4938) @jairo-mendoza
+
 ### :bug: (Bug Fix)
 
 * fix(instrumentation): Fix wrapping ESM files with absolute path [#5094](https://github.com/open-telemetry/opentelemetry-js/pull/5094) @serkan-ozal

experimental/packages/opentelemetry-instrumentation-fetch/src/fetch.ts

@@ -64,6 +64,11 @@ export interface FetchInstrumentationConfig extends InstrumentationConfig {
   clearTimingResources?: boolean;
   // urls which should include trace headers when origin doesn't match
   propagateTraceHeaderCorsUrls?: web.PropagateTraceHeaderCorsUrls;
+  /**
+   * URLs that partially match any regex or exactly match strings in allowUrls
+   * will be traced.
+   */
+  allowUrls?: Array<string | RegExp>;
   /**
    * URLs that partially match any regex in ignoreUrls will not be traced.
    * In addition, URLs that are _exact matches_ of strings in ignoreUrls will
@@ -201,6 +206,10 @@ export class FetchInstrumentation extends InstrumentationBase<FetchInstrumentati
     url: string,
     options: Partial<Request | RequestInit> = {}
   ): api.Span | undefined {
+    if (!core.isUrlAllowed(url, this.getConfig().allowUrls)) {
+      this._diag.debug('ignoring span as url does not match an allowed url');
+      return;
+    }
     if (core.isUrlIgnored(url, this.getConfig().ignoreUrls)) {
       this._diag.debug('ignoring span as url matches ignored url');
       return;

experimental/packages/opentelemetry-instrumentation-fetch/test/fetch.test.ts

@@ -717,6 +717,40 @@ describe('fetch', () => {
     });
   });
 
+  describe('when url is allowed', () => {
+    beforeEach(async () => {
+      const propagateTraceHeaderCorsUrls = url;
+      await prepareData(url, {
+        propagateTraceHeaderCorsUrls,
+        allowUrls: [propagateTraceHeaderCorsUrls],
+      });
+    });
+    afterEach(() => {
+      clearData();
+    });
+    it('should create a span', () => {
+      assert.ok(exportSpy.args.length > 0, 'span should be exported');
+    });
+  });
+
+  describe('when url is NOT allowed', () => {
+    const otherUrl = 'http://localhost:8099/get';
+
+    beforeEach(async () => {
+      const propagateTraceHeaderCorsUrls = url;
+      await prepareData(url, {
+        propagateTraceHeaderCorsUrls,
+        allowUrls: [otherUrl],
+      });
+    });
+    afterEach(() => {
+      clearData();
+    });
+    it('should NOT create any span', () => {
+      assert.ok(exportSpy.args.length === 0, "span shouldn't be exported");
+    });
+  });
+
   describe('when url is ignored', () => {
     beforeEach(async () => {
       const propagateTraceHeaderCorsUrls = url;
@@ -729,7 +763,11 @@ describe('fetch', () => {
       clearData();
     });
     it('should NOT create any span', () => {
-      assert.strictEqual(exportSpy.args.length, 0, "span shouldn't b exported");
+      assert.strictEqual(
+        exportSpy.args.length,
+        0,
+        "span shouldn't be exported"
+      );
     });
     it('should pass request object as the first parameter to the original function (#2411)', () => {
       const r = new Request(url);

experimental/packages/opentelemetry-instrumentation-xml-http-request/src/xhr.ts

@@ -21,7 +21,12 @@ import {
   InstrumentationConfig,
   safeExecuteInTheMiddle,
 } from '@opentelemetry/instrumentation';
-import { hrTime, isUrlIgnored, otperformance } from '@opentelemetry/core';
+import {
+  hrTime,
+  isUrlAllowed,
+  isUrlIgnored,
+  otperformance,
+} from '@opentelemetry/core';
 import {
   SEMATTRS_HTTP_HOST,
   SEMATTRS_HTTP_METHOD,
@@ -73,6 +78,11 @@ export interface XMLHttpRequestInstrumentationConfig
   clearTimingResources?: boolean;
   /** URLs which should include trace headers when origin doesn't match */
   propagateTraceHeaderCorsUrls?: PropagateTraceHeaderCorsUrls;
+  /**
+   * URLs that partially match any regex or exactly match strings in allowUrls
+   * will be traced.
+   */
+  allowUrls?: Array<string | RegExp>;
   /**
    * URLs that partially match any regex in ignoreUrls will not be traced.
    * In addition, URLs that are _exact matches_ of strings in ignoreUrls will
@@ -331,6 +341,10 @@ export class XMLHttpRequestInstrumentation extends InstrumentationBase<XMLHttpRe
     url: string,
     method: string
   ): api.Span | undefined {
+    if (!isUrlAllowed(url, this.getConfig().allowUrls)) {
+      this._diag.debug('ignoring span as url does not match an allowed url');
+      return;
+    }
     if (isUrlIgnored(url, this.getConfig().ignoreUrls)) {
       this._diag.debug('ignoring span as url matches ignored url');
       return;

experimental/packages/opentelemetry-instrumentation-xml-http-request/test/xhr.test.ts

@@ -626,6 +626,37 @@ describe('xhr', () => {
           }
         );
 
+        describe('when url is allowed', () => {
+          beforeEach(done => {
+            clearData();
+            const propagateTraceHeaderCorsUrls = url;
+            prepareData(done, url, {
+              propagateTraceHeaderCorsUrls,
+              allowUrls: [propagateTraceHeaderCorsUrls],
+            });
+          });
+
+          it('should create a span', () => {
+            assert.ok(exportSpy.called, 'span should be exported');
+          });
+        });
+
+        describe('when another url is allowed', () => {
+          const otherUrl = 'http://localhost:8099/get';
+          beforeEach(done => {
+            clearData();
+            const propagateTraceHeaderCorsUrls = url;
+            prepareData(done, url, {
+              propagateTraceHeaderCorsUrls,
+              allowUrls: [otherUrl],
+            });
+          });
+
+          it('should NOT create a span', () => {
+            assert.ok(exportSpy.notCalled, "span shouldn't be exported");
+          });
+        });
+
         describe('when url is ignored', () => {
           beforeEach(done => {
             clearData();

packages/opentelemetry-core/src/index.ts

@@ -112,7 +112,7 @@ export {
 export { merge } from './utils/merge';
 export { TracesSamplerValues } from './utils/sampling';
 export { TimeoutError, callWithTimeout } from './utils/timeout';
-export { isUrlIgnored, urlMatches } from './utils/url';
+export { isUrlAllowed, isUrlIgnored, urlMatches } from './utils/url';
 export { isWrapped } from './utils/wrap';
 export { BindOnceFuture } from './utils/callback';
 export { VERSION } from './version';

packages/opentelemetry-core/src/utils/url.ts

@@ -20,6 +20,26 @@ export function urlMatches(url: string, urlToMatch: string | RegExp): boolean {
     return !!url.match(urlToMatch);
   }
 }
+/**
+ * Check if {@param url} should be allowed when comparing against {@param allowedUrls}
+ * @param url
+ * @param allowedUrls
+ */
+export function isUrlAllowed(
+  url: string,
+  allowedUrls?: Array<string | RegExp>
+): boolean {
+  if (!allowedUrls) {
+    return true;
+  }
+
+  for (const allowedUrl of allowedUrls) {
+    if (urlMatches(url, allowedUrl)) {
+      return true;
+    }
+  }
+  return false;
+}
 /**
  * Check if {@param url} should be ignored when comparing against {@param ignoredUrls}
  * @param url

packages/opentelemetry-core/test/utils/url.test.ts

@@ -16,10 +16,12 @@
 
 import * as assert from 'assert';
 
-import { isUrlIgnored } from '../../src';
+import { isUrlAllowed, isUrlIgnored } from '../../src';
 
 const urlIgnored = 'url should be ignored';
 const urlNotIgnored = 'url should NOT be ignored';
+const urlAllowed = 'url should be allowed';
+const urlNotAllowed = 'url should NOT be allowed';
 
 const urlToTest = 'http://myaddress.com/somepath';
 
@@ -85,4 +87,35 @@ describe('Core - Utils - url', () => {
       });
     });
   });
+
+  describe('isUrlAllowed', () => {
+    describe('when allowed urls are undefined', () => {
+      it('should return true', () => {
+        assert.strictEqual(isUrlAllowed(urlToTest), true, urlAllowed);
+      });
+    });
+    describe('when allowed urls are empty', () => {
+      it('should return false', () => {
+        assert.strictEqual(isUrlAllowed(urlToTest, []), false, urlAllowed);
+      });
+    });
+    describe('when allowed urls contains test url', () => {
+      it('should return true', () => {
+        assert.strictEqual(
+          isUrlAllowed(urlToTest, ['http://myaddress.com/somepath']),
+          true,
+          urlAllowed
+        );
+      });
+    });
+    describe('when allowed urls does NOT contain test url', () => {
+      it('should return false', () => {
+        assert.strictEqual(
+          isUrlAllowed(urlToTest, ['http://myaddress.com/other']),
+          false,
+          urlNotAllowed
+        );
+      });
+    });
+  });
 });