sanitizer optional, export default with usage, fix tests

Author: Abinet18

packages/instrumentation-browser-navigation/README.md

@@ -63,6 +63,7 @@ The instrumentation accepts the following configuration options:
 | ------ | ---- | ------- | ----------- |
 | `enabled` | `boolean` | `true` | Enable/disable the instrumentation |
 | `useNavigationApiIfAvailable` | `boolean` | `true` | Use the Navigation API when available for better accuracy |
+| `sanitizeUrl` | `function` | `undefined` | Callback to sanitize URLs before adding to log records |
 | `applyCustomLogRecordData` | `function` | `undefined` | Callback to add custom attributes to log records |
 
 ## Navigation API vs Traditional APIs
@@ -73,6 +74,68 @@ When `useNavigationApiIfAvailable` is `true` (default), the instrumentation will
 - **Fall back to traditional APIs** (history patching, popstate, etc.) in older browsers
 - **Prevent duplicate events** by using only one API set at a time
 
+## URL Sanitization
+
+**Important**: By default, URLs are **not sanitized** and will be recorded as-is. For security and privacy, you should provide a `sanitizeUrl` function to redact sensitive information.
+
+### Using the Default Sanitizer
+
+The package exports a `defaultSanitizeUrl` function that removes credentials and common sensitive query parameters:
+
+```ts
+import { BrowserNavigationInstrumentation, defaultSanitizeUrl } from '@opentelemetry/instrumentation-browser-navigation';
+
+registerInstrumentations({
+  instrumentations: [
+    new BrowserNavigationInstrumentation({
+      sanitizeUrl: defaultSanitizeUrl,
+    }),
+  ],
+});
+```
+
+The default sanitizer redacts:
+- **Credentials**: `https://user:[email protected]` → `https://REDACTED:[email protected]`
+- **Sensitive parameters**: `password`, `token`, `api_key`, `secret`, `auth`, etc.
+
+### Custom URL Sanitization
+
+You can provide your own sanitization logic:
+
+```ts
+const customSanitizer = (url: string) => {
+  // Remove all query parameters
+  return url.split('?')[0];
+};
+
+// Or more targeted sanitization
+const targetedSanitizer = (url: string) => {
+  return url.replace(/sessionId=[^&]*/gi, 'sessionId=REDACTED');
+};
+
+registerInstrumentations({
+  instrumentations: [
+    new BrowserNavigationInstrumentation({
+      sanitizeUrl: customSanitizer,
+    }),
+  ],
+});
+```
+
+### No Sanitization
+
+If you want to record URLs without any sanitization (not recommended for production):
+
+```ts
+registerInstrumentations({
+  instrumentations: [
+    new BrowserNavigationInstrumentation({
+      // No sanitizeUrl provided - URLs recorded as-is
+    }),
+  ],
+});
+```
+
 ## Adding Custom Attributes
 
 If you need to add custom attributes to each navigation event, provide a callback via `applyCustomLogRecordData`:

packages/instrumentation-browser-navigation/src/index.ts

@@ -16,3 +16,4 @@
 
 export { BrowserNavigationInstrumentation } from './instrumentation';
 export type { BrowserNavigationInstrumentationConfig } from './types';
+export { defaultSanitizeUrl } from './utils';

packages/instrumentation-browser-navigation/src/instrumentation.ts

@@ -24,7 +24,7 @@ import {
   ApplyCustomLogRecordDataFunction,
   SanitizeUrlFunction,
 } from './types';
-import { isHashChange, defaultSanitizeUrl } from './utils';
+import { isHashChange } from './utils';
 
 /**
  * This class represents a browser navigation instrumentation plugin
@@ -39,7 +39,7 @@ export const ATTR_BROWSER_NAVIGATION_TYPE = 'browser.navigation.type';
 export class BrowserNavigationInstrumentation extends InstrumentationBase<BrowserNavigationInstrumentationConfig> {
   applyCustomLogRecordData: ApplyCustomLogRecordDataFunction | undefined =
     undefined;
-  sanitizeUrl: SanitizeUrlFunction = defaultSanitizeUrl; // Initialize with default
+  sanitizeUrl?: SanitizeUrlFunction; // No default sanitization
   private _onLoadHandler?: () => void;
   private _onPopStateHandler?: (ev: PopStateEvent) => void;
   private _onNavigateHandler?: (ev: Event) => void;
@@ -53,10 +53,7 @@ export class BrowserNavigationInstrumentation extends InstrumentationBase<Browse
   constructor(config: BrowserNavigationInstrumentationConfig) {
     super(PACKAGE_NAME, PACKAGE_VERSION, config);
     this.applyCustomLogRecordData = config?.applyCustomLogRecordData;
-    // Override default with custom sanitizer if provided
-    if (config?.sanitizeUrl) {
-      this.sanitizeUrl = config.sanitizeUrl;
-    }
+    this.sanitizeUrl = config?.sanitizeUrl;
   }
 
   init() {}
@@ -68,7 +65,7 @@ export class BrowserNavigationInstrumentation extends InstrumentationBase<Browse
     const navLogRecord: LogRecord = {
       eventName: EVENT_NAME,
       attributes: {
-        [ATTR_URL_FULL]: this.sanitizeUrl(document.documentURI),
+        [ATTR_URL_FULL]: this.sanitizeUrl ? this.sanitizeUrl(document.documentURI) : document.documentURI,
         [ATTR_BROWSER_NAVIGATION_SAME_DOCUMENT]: false,
         [ATTR_BROWSER_NAVIGATION_HASH_CHANGE]: false,
       },
@@ -110,7 +107,7 @@ export class BrowserNavigationInstrumentation extends InstrumentationBase<Browse
     const navLogRecord: LogRecord = {
       eventName: EVENT_NAME,
       attributes: {
-        [ATTR_URL_FULL]: this.sanitizeUrl(currentUrl),
+        [ATTR_URL_FULL]: this.sanitizeUrl ? this.sanitizeUrl(currentUrl) : currentUrl,
         [ATTR_BROWSER_NAVIGATION_SAME_DOCUMENT]: sameDocument,
         [ATTR_BROWSER_NAVIGATION_HASH_CHANGE]: hashChange,
         ...(navType ? { [ATTR_BROWSER_NAVIGATION_TYPE]: navType } : {}),

packages/instrumentation-browser-navigation/test/navigation.test.ts

@@ -23,6 +23,7 @@ import {
 
 import * as sinon from 'sinon';
 import { BrowserNavigationInstrumentation } from '../src';
+import { defaultSanitizeUrl } from '../src/utils';
 import {
   EVENT_NAME,
   ATTR_BROWSER_NAVIGATION_SAME_DOCUMENT,
@@ -373,7 +374,7 @@ describe('Browser Navigation Instrumentation', () => {
           );
           window.removeEventListener('popstate', popstateHandler);
           done();
-        }, 50);
+        }, 150);
       };
 
       window.addEventListener('popstate', popstateHandler);
@@ -419,7 +420,7 @@ describe('Browser Navigation Instrumentation', () => {
         }
       };
 
-      entryChangeHandler = (event: any) => {
+      entryChangeHandler = (_event: any) => {
         // Let the navigation complete, then check records
         setTimeout(() => {
           const records = exporter.getFinishedLogRecords();
@@ -470,7 +471,7 @@ describe('Browser Navigation Instrumentation', () => {
             completeDone();
           }
         }, 50);
-      } catch (_error) {
+      } catch {
         // Fallback if Navigation API methods fail
         console.log(
           'Navigation API methods not fully supported, using fallback'
@@ -502,12 +503,20 @@ describe('Browser Navigation Instrumentation', () => {
     });
 
     it('should export LogRecord with Navigation API hash change detection', done => {
+      let testCompleted = false;
+      const completeDone = (error?: Error) => {
+        if (!testCompleted) {
+          testCompleted = true;
+          done(error);
+        }
+      };
+
       // Check if Navigation API is actually available in the test environment
       if (!(window as any).navigation) {
         console.log(
           'Navigation API not available in test environment, skipping test'
         );
-        done();
+        completeDone();
         return;
       }
 
@@ -530,7 +539,7 @@ describe('Browser Navigation Instrumentation', () => {
         }
       };
 
-      entryChangeHandler = (event: any) => {
+      entryChangeHandler = (_event: any) => {
         setTimeout(() => {
           const records = exporter.getFinishedLogRecords();
           if (records.length >= 1) {
@@ -553,7 +562,7 @@ describe('Browser Navigation Instrumentation', () => {
             ];
             assert.ok(navType === 'push' || navType === 'traverse');
             cleanup();
-            done();
+            completeDone();
           }
         }, 10);
       };
@@ -570,18 +579,18 @@ describe('Browser Navigation Instrumentation', () => {
           const navLogRecord = records.slice(-1)[0] as ReadableLogRecord;
           assert.strictEqual(navLogRecord.eventName, EVENT_NAME);
           cleanup();
-          done();
+          completeDone();
         } else {
           console.log('No hash navigation records found');
           cleanup();
-          done();
+          completeDone();
         }
       }, 100);
 
         // Cleanup timeout
         setTimeout(() => {
           cleanup();
-          done(new Error('Test timeout - Hash change navigation not detected'));
+          completeDone(new Error('Test timeout - Hash change navigation not detected'));
         }, 1000);
       }, 10); // Close the setTimeout for readyState wait
     });
@@ -590,6 +599,7 @@ describe('Browser Navigation Instrumentation', () => {
       instrumentation = new BrowserNavigationInstrumentation({
         enabled: true,
         useNavigationApiIfAvailable: false, // Test history API path
+        sanitizeUrl: defaultSanitizeUrl,
       });
       instrumentation.enable();
 
@@ -664,7 +674,7 @@ describe('Browser Navigation Instrumentation', () => {
           'Should preserve normal query params'
         );
         done();
-      }, 10);
+      }, 150);
     });
 
     it('should work with Navigation API enabled', done => {