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

@@ -11,6 +11,7 @@ All notable changes to experimental packages in this project will be documented
 
 * feat(api-logs): Add delegating no-op logger provider [#4861](https://github.com/open-telemetry/opentelemetry-js/pull/4861) @hectorhdzg
 * feat(instrumentation-http): Add support for client span semantic conventions 1.27 [#4940](https://github.com/open-telemetry/opentelemetry-js/pull/4940) @dyladan
+* feat(instrumentation): Add allowUrls config option to web instrumentation [#4938](https://github.com/open-telemetry/opentelemetry-js/pull/4938) @jairo-mendoza
 
 ### :bug: (Bug Fix)
 

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

@@ -17,9 +17,29 @@
   if (typeof urlToMatch === 'string') {
     return url === urlToMatch;
   } else {
     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