feat: add diagnostic

packages/analytics-browser/src/config.ts

@@ -3,6 +3,7 @@ import {
   BrowserOptions,
   BrowserConfig as IBrowserConfig,
   DefaultTrackingOptions,
+  Diagnostic,
   Storage,
   TrackingOptions,
   TransportType,
@@ -25,6 +26,7 @@ import { parseLegacyCookies } from './cookie-migration';
 import { CookieOptions } from '@amplitude/analytics-types/lib/esm/config/browser';
 import { DEFAULT_IDENTITY_STORAGE, DEFAULT_SERVER_ZONE } from './constants';
 import { AmplitudeBrowser } from './browser-client';
+import { BrowserDiagnostic } from './diagnostics/diagnostic';
 
 // Exported for testing purposes only. Do not expose to public interface.
 export class BrowserConfig extends Config implements IBrowserConfig {
@@ -75,9 +77,10 @@ export class BrowserConfig extends Config implements IBrowserConfig {
     },
     public transport: 'fetch' | 'xhr' | 'beacon' = 'fetch',
     public useBatch: boolean = false,
+    public diagnosticProvider: Diagnostic = new BrowserDiagnostic(),
     userId?: string,
   ) {
-    super({ apiKey, storageProvider, transportProvider: createTransport(transport) });
+    super({ apiKey, storageProvider, transportProvider: createTransport(transport), diagnosticProvider });
     this._cookieStorage = cookieStorage;
     this.deviceId = deviceId;
     this.lastEventId = lastEventId;
@@ -247,6 +250,7 @@ export const useBrowserConfig = async (
     trackingOptions,
     options.transport,
     options.useBatch,
+    options.diagnosticProvider,
     userId,
   );
 };

packages/analytics-browser/src/diagnostics/diagnostic.ts

@@ -0,0 +1,10 @@
+import { BaseDiagnostic } from '@amplitude/analytics-core';
+
+export class BrowserDiagnostic extends BaseDiagnostic {
+  isDisabled = false;
+
+  async flush(): Promise<void> {
+    await fetch(this.serverUrl, this.requestPayloadBuilder(this.queue));
+    await super.flush();
+  }
+}

packages/analytics-browser/test/browser-client.test.ts

@@ -2,7 +2,7 @@ import { AmplitudeBrowser } from '../src/browser-client';
 import * as core from '@amplitude/analytics-core';
 import * as Config from '../src/config';
 import * as CookieMigration from '../src/cookie-migration';
-import { UserSession } from '@amplitude/analytics-types';
+import { Status, UserSession } from '@amplitude/analytics-types';
 import {
   CookieStorage,
   FetchTransport,
@@ -261,6 +261,190 @@ describe('browser-client', () => {
       }).promise;
       expect(webAttributionPluginPlugin).toHaveBeenCalledTimes(1);
     });
+
+    describe('diagnostic', () => {
+      test('should init diagnostic with default api key', async () => {
+        await client.init(apiKey).promise;
+        expect(client.config.diagnosticProvider.apiKey).toBe(apiKey);
+      });
+
+      test('should not diagnostic track when 200', async () => {
+        const transportProvider = {
+          send: jest.fn().mockImplementationOnce(() => {
+            return Promise.resolve({
+              status: Status.Success,
+              statusCode: 200,
+            });
+          }),
+        };
+
+        await client.init(apiKey, {
+          defaultTracking: false,
+        }).promise;
+        const diagnosticTrack = jest.spyOn(client.config.diagnosticProvider, 'track');
+        client.config.transportProvider = transportProvider;
+        await client.track('event_type', { userId: 'user_0' }).promise;
+
+        expect(diagnosticTrack).toHaveBeenCalledTimes(0);
+      });
+
+      test.each([null, new Error()])('should diagnostic track when 0 unexpected error', async (res) => {
+        const transportProvider = {
+          send: jest.fn().mockImplementationOnce(() => {
+            return Promise.resolve(res);
+          }),
+        };
+
+        await client.init(apiKey, {
+          defaultTracking: false,
+        }).promise;
+        const diagnosticTrack = jest.spyOn(client.config.diagnosticProvider, 'track');
+        client.config.transportProvider = transportProvider;
+        await client.track('event_type', { userId: 'user_0' }).promise;
+
+        expect(diagnosticTrack).toHaveBeenCalledTimes(1);
+        expect(diagnosticTrack).toHaveBeenCalledWith(1, 0, core.DIAGNOSTIC_MESSAGES.UNEXPECTED_ERROR);
+      });
+
+      test('should diagnostic track when flush and non 200', async () => {
+        const transportProvider = {
+          send: jest.fn().mockImplementationOnce(() => {
+            return Promise.resolve({
+              status: Status.Failed,
+              statusCode: 500,
+            });
+          }),
+        };
+
+        await client.init(apiKey, {
+          defaultTracking: false,
+        }).promise;
+        const diagnosticTrack = jest.spyOn(client.config.diagnosticProvider, 'track');
+        client.config.transportProvider = transportProvider;
+        client.track('event_type', { userId: 'user_0' });
+        await client.flush().promise;
+
+        expect(diagnosticTrack).toHaveBeenCalledTimes(1);
+        expect(diagnosticTrack).toHaveBeenCalledWith(1, 0, core.DIAGNOSTIC_MESSAGES.UNEXPECTED_ERROR);
+      });
+
+      test.each([
+        ['api_key', undefined, core.DIAGNOSTIC_MESSAGES.INVALID_OR_MISSING_FIELDS],
+        [undefined, { time: [0] }, core.DIAGNOSTIC_MESSAGES.EVENT_ERROR],
+      ])(
+        'should diagnostic track when 400 invalid response',
+        async (missingField, eventsWithInvalidFields, message) => {
+          const transportProvider = {
+            send: jest.fn().mockImplementationOnce(() => {
+              return Promise.resolve({
+                status: Status.Invalid,
+                statusCode: 400,
+                body: {
+                  error: 'error',
+                  missingField: missingField,
+                  eventsWithInvalidFields: eventsWithInvalidFields,
+                  eventsWithMissingFields: {},
+                  eventsWithInvalidIdLengths: {},
+                  silencedEvents: [],
+                },
+              });
+            }),
+          };
+
+          await client.init(apiKey, {
+            defaultTracking: false,
+          }).promise;
+          const diagnosticTrack = jest.spyOn(client.config.diagnosticProvider, 'track');
+          client.config.transportProvider = transportProvider;
+          await client.track('event_type', { userId: 'user_0' }).promise;
+
+          expect(diagnosticTrack).toHaveBeenCalledTimes(1);
+          expect(diagnosticTrack).toHaveBeenCalledWith(1, 400, message);
+        },
+      );
+
+      test('should diagnostic track when 429 rate limit when flush', async () => {
+        const transportProvider = {
+          send: jest.fn().mockImplementationOnce(() => {
+            return Promise.resolve({
+              status: Status.RateLimit,
+              statusCode: 429,
+              body: {
+                exceededDailyQuotaUsers: { user_0: 1 },
+                exceededDailyQuotaDevices: {},
+                throttledEvents: [],
+              },
+            });
+          }),
+        };
+
+        await client.init(apiKey, {
+          defaultTracking: false,
+        }).promise;
+        const diagnosticTrack = jest.spyOn(client.config.diagnosticProvider, 'track');
+        client.config.transportProvider = transportProvider;
+        client.track('event_type', { userId: 'user_0' });
+        // flush() calls destination.flush(useRetry: false)
+        await client.flush().promise;
+
+        expect(diagnosticTrack).toHaveBeenCalledTimes(1);
+        expect(diagnosticTrack).toHaveBeenCalledWith(1, 429, core.DIAGNOSTIC_MESSAGES.EXCEEDED_DAILY_QUOTA);
+      });
+
+      test('should diagnostic track when 413', async () => {
+        const transportProvider = {
+          send: jest.fn().mockImplementationOnce(() => {
+            return Promise.resolve({
+              status: Status.PayloadTooLarge,
+              statusCode: 413,
+              body: {
+                error: 'error',
+              },
+            });
+          }),
+        };
+
+        await client.init(apiKey, {
+          defaultTracking: false,
+        }).promise;
+        const diagnosticTrack = jest.spyOn(client.config.diagnosticProvider, 'track');
+        client.config.transportProvider = transportProvider;
+        await client.track('event_type', { userId: 'user_0' }).promise;
+
+        expect(diagnosticTrack).toHaveBeenCalledTimes(1);
+        expect(diagnosticTrack).toHaveBeenCalledWith(1, 413, core.DIAGNOSTIC_MESSAGES.PAYLOAD_TOO_LARGE);
+      });
+
+      test('should diagnostic track when 500 hit max retries', async () => {
+        const transportProvider = {
+          send: jest.fn().mockImplementationOnce(() => {
+            return Promise.resolve({
+              status: Status.Invalid,
+              statusCode: 400,
+              body: {
+                error: 'error',
+                missingField: '',
+                eventsWithInvalidFields: {},
+                eventsWithMissingFields: {},
+                eventsWithInvalidIdLengths: {},
+                silencedEvents: [],
+              },
+            });
+          }),
+        };
+
+        await client.init(apiKey, {
+          defaultTracking: false,
+          flushMaxRetries: 1,
+        }).promise;
+        const diagnosticTrack = jest.spyOn(client.config.diagnosticProvider, 'track');
+        client.config.transportProvider = transportProvider;
+        await client.track('event_type', { userId: 'user_0' }).promise;
+
+        expect(diagnosticTrack).toHaveBeenCalledTimes(1);
+        expect(diagnosticTrack).toHaveBeenCalledWith(1, 500, core.DIAGNOSTIC_MESSAGES.EXCEEDED_MAX_RETRY);
+      });
+    });
   });
 
   describe('getUserId', () => {

packages/analytics-browser/test/config.test.ts

@@ -11,6 +11,7 @@ import { SendBeaconTransport } from '../src/transports/send-beacon';
 import { uuidPattern } from './helpers/constants';
 import { DEFAULT_IDENTITY_STORAGE, DEFAULT_SERVER_ZONE } from '../src/constants';
 import { AmplitudeBrowser } from '../src/browser-client';
+import { BrowserDiagnostic } from '../src/diagnostics/diagnostic';
 
 describe('config', () => {
   const someUUID: string = expect.stringMatching(uuidPattern) as string;
@@ -73,13 +74,19 @@ describe('config', () => {
         transport: 'fetch',
         transportProvider: new FetchTransport(),
         useBatch: false,
+        diagnosticProvider: new BrowserDiagnostic({ apiKey }),
       });
     });
 
     test('shoud return _optOut', () => {
       const config = new Config.BrowserConfig(apiKey);
       expect(config.optOut).toBe(false);
     });
+
+    test('should set default api key for diagnostic provider', () => {
+      const config = new Config.BrowserConfig(apiKey);
+      expect(config.diagnosticProvider.apiKey).toBe(apiKey);
+    });
   });
 
   describe('useBrowserConfig', () => {
@@ -128,6 +135,7 @@ describe('config', () => {
         transport: 'fetch',
         transportProvider: new FetchTransport(),
         useBatch: false,
+        diagnosticProvider: new BrowserDiagnostic({ apiKey }),
       });
       expect(getTopLevelDomain).toHaveBeenCalledTimes(1);
     });
@@ -213,6 +221,7 @@ describe('config', () => {
         transport: 'fetch',
         transportProvider: new FetchTransport(),
         useBatch: false,
+        diagnosticProvider: new BrowserDiagnostic({ apiKey }),
       });
     });
 

packages/analytics-browser/test/diagnostic.test.ts

@@ -0,0 +1,47 @@
+import { DIAGNOSTIC_ENDPOINT, DIAGNOSTIC_METADATA_TYPE } from '@amplitude/analytics-core';
+import { BrowserDiagnostic } from '../src/diagnostics/diagnostic';
+
+describe('Diagnostic', () => {
+  test('should fetch', async () => {
+    const diagnostic = new BrowserDiagnostic();
+    const fetchMock = jest.fn().mockResolvedValueOnce({} as Response);
+    Date.now = jest.fn().mockReturnValue(1697583342266);
+    global.fetch = fetchMock;
+
+    diagnostic.track(5, 400, 'test message 0');
+    diagnostic.track(10, 500, 'test message 1');
+    await diagnostic.flush();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(DIAGNOSTIC_ENDPOINT, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        api_key: '',
+        omni_metrics: [
+          {
+            metadata_type: DIAGNOSTIC_METADATA_TYPE,
+            library: 'amplitude-ts',
+            accounting_time_min: Math.floor(1697583342266 / 60 / 1000),
+            response_code: 400,
+            trigger: 'test message 0',
+            action: 'drop events',
+            event_count: 5,
+          },
+          {
+            metadata_type: DIAGNOSTIC_METADATA_TYPE,
+            library: 'amplitude-ts',
+            accounting_time_min: Math.floor(1697583342266 / 60 / 1000),
+            response_code: 500,
+            trigger: 'test message 1',
+            action: 'drop events',
+            event_count: 10,
+          },
+        ],
+      }),
+    });
+    fetchMock.mockRestore();
+  });
+});

packages/analytics-browser/test/helpers/mock.ts

@@ -78,6 +78,12 @@ export const createConfigurationMock = (options?: Partial<BrowserConfig>) => {
     },
     trackingSessionEvents: false,
     userId: undefined,
+    diagnosticProvider: {
+      isDisabled: false,
+      serverUrl: undefined,
+      apiKey: undefined,
+      track: jest.fn(),
+    },
     ...options,
   };
 };

packages/analytics-core/src/config.ts

@@ -1,6 +1,7 @@
 import {
   Event,
   Config as IConfig,
+  Diagnostic,
   Logger as ILogger,
   LogLevel,
   Storage,
@@ -18,6 +19,7 @@ import {
 } from './constants';
 
 import { Logger } from './logger';
+import { BaseDiagnostic } from './diagnostics/diagnostic';
 
 export const getDefaultConfig = () => ({
   flushMaxRetries: 12,
@@ -30,6 +32,7 @@ export const getDefaultConfig = () => ({
   serverUrl: AMPLITUDE_SERVER_URL,
   serverZone: 'US' as ServerZoneType,
   useBatch: false,
+  diagnosticProvider: new BaseDiagnostic(),
 });
 
 export class Config implements IConfig {
@@ -48,6 +51,7 @@ export class Config implements IConfig {
   transportProvider: Transport;
   storageProvider?: Storage<Event[]>;
   useBatch: boolean;
+  diagnosticProvider: Diagnostic;
 
   protected _optOut = false;
   get optOut() {
@@ -75,6 +79,12 @@ export class Config implements IConfig {
     this.storageProvider = options.storageProvider;
     this.transportProvider = options.transportProvider;
     this.useBatch = options.useBatch ?? defaultConfig.useBatch;
+
+    this.diagnosticProvider = options.diagnosticProvider ?? defaultConfig.diagnosticProvider;
+    if (!this.diagnosticProvider.apiKey) {
+      this.diagnosticProvider.apiKey = this.apiKey;
+    }
+
     this.loggerProvider.enable(this.logLevel);
 
     const serverConfig = createServerConfig(options.serverUrl, options.serverZone, options.useBatch);