feat(shared): Add opt-out support for SDK telemetry

packages/clerk-js/src/core/clerk.ts

@@ -173,7 +173,7 @@ export default class Clerk implements ClerkInterface {
   #devBrowserHandler: DevBrowserHandler | null = null;
   #environment?: EnvironmentResource | null;
   #fapiClient: FapiClient;
-  #telemetry: TelemetryCollector;
+  #telemetry?: TelemetryCollector;
   #instanceType: InstanceType;
   #isReady = false;
 
@@ -308,12 +308,6 @@ export default class Clerk implements ClerkInterface {
       this.#instanceType = instanceType;
     }
     this.#fapiClient = createFapiClient(this);
-    this.#telemetry = new TelemetryCollector({
-      clerkVersion: Clerk.version,
-      verbose: true,
-      samplingRate: 1,
-      publishableKey: key,
-    });
     BaseResource.clerk = this;
   }
 
@@ -331,6 +325,19 @@ export default class Clerk implements ClerkInterface {
       ...options,
     };
 
+    if (this.#options.sdkMetadata) {
+      Clerk.sdkMetadata = this.#options.sdkMetadata;
+    }
+
+    this.#telemetry = new TelemetryCollector({
+      clerkVersion: Clerk.version,
+      verbose: true,
+      samplingRate: 1,
+      // @ts-expect-error -- in v5 this will always be defined
+      publishableKey: this.publishableKey,
+      ...this.#options.telemetry,
+    });
+
     if (this.#options.standardBrowser) {
       this.#isReady = await this.#loadInStandardBrowser();
     } else {

packages/gatsby-plugin-clerk/src/GatsbyClerkProvider.tsx

@@ -7,6 +7,8 @@ import {
 import { navigate } from 'gatsby';
 import React from 'react';
 
+import { TELEMETRY_DEBUG, TELEMETRY_DISABLED } from './constants';
+
 const SDK_METADATA = {
   name: PACKAGE_NAME,
   version: PACKAGE_VERSION,
@@ -28,6 +30,10 @@ export function ClerkProvider({ children, ...rest }: GatsbyClerkProviderProps) {
       navigate={to => navigate(to)}
       initialState={__clerk_ssr_state || {}}
       sdkMetadata={SDK_METADATA}
+      telemetry={{
+        disabled: TELEMETRY_DISABLED,
+        debug: TELEMETRY_DEBUG,
+      }}
       {...restProps}
     >
       {__clerk_ssr_interstitial_html ? (

packages/gatsby-plugin-clerk/src/constants.ts

@@ -1,4 +1,5 @@
 import { apiUrlFromPublishableKey } from '@clerk/shared/apiUrlFromPublishableKey';
+import { isTruthy } from '@clerk/shared/underscore';
 
 export const PUBLISHABLE_KEY = process.env.GATSBY_CLERK_PUBLISHABLE_KEY || '';
 export const API_URL = process.env.CLERK_API_URL || apiUrlFromPublishableKey(PUBLISHABLE_KEY);
@@ -7,3 +8,6 @@ export const SECRET_KEY = process.env.CLERK_SECRET_KEY || '';
 
 export const CLERK_JS = process.env.GATSBY_CLERK_JS;
 export const PROXY_URL = process.env.GATSBY_CLERK_PROXY_URL;
+
+export const TELEMETRY_DISABLED = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DISABLED);
+export const TELEMETRY_DEBUG = isTruthy(process.env.GATSBY_CLERK_TELEMETRY_DEBUG);

packages/nextjs/src/utils/mergeNextClerkPropsWithEnv.ts

@@ -15,6 +15,10 @@ export const mergeNextClerkPropsWithEnv = (props: Omit<NextClerkProviderProps, '
     signUpUrl: props.signUpUrl || process.env.NEXT_PUBLIC_CLERK_SIGN_UP_URL || '',
     afterSignInUrl: props.afterSignInUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL || '',
     afterSignUpUrl: props.afterSignUpUrl || process.env.NEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL || '',
+    telemetry: {
+      disabled: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DISABLED),
+      debug: isTruthy(process.env.NEXT_PUBLIC_CLERK_TELEMETRY_DEBUG),
+    },
     sdkMetadata: {
       name: PACKAGE_NAME,
       version: PACKAGE_VERSION,

packages/react/src/isomorphicClerk.ts

@@ -132,6 +132,11 @@ export default class IsomorphicClerk {
     this.options = options;
     this.Clerk = Clerk;
     this.mode = inBrowser() ? 'browser' : 'server';
+
+    if (!this.options.sdkMetadata) {
+      this.options.sdkMetadata = SDK_METADATA;
+    }
+
     void this.loadClerkJS();
   }
 
@@ -168,7 +173,6 @@ export default class IsomorphicClerk {
             domain: this.domain,
           } as any);
 
-          c.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
           await c.load(this.options);
         } else {
           // Otherwise use the instantiated Clerk object
@@ -195,13 +199,9 @@ export default class IsomorphicClerk {
           throw new Error('Failed to download latest ClerkJS. Contact [email protected].');
         }
 
-        global.Clerk.sdkMetadata = this.options.sdkMetadata ?? SDK_METADATA;
-
         await global.Clerk.load(this.options);
       }
 
-      global.Clerk.sdkMetadata = this.options.sdkMetadata ?? { name: PACKAGE_NAME, version: PACKAGE_VERSION };
-
       if (global.Clerk?.loaded || global.Clerk?.isReady()) {
         return this.hydrateClerkJS(global.Clerk);
       }

packages/remix/src/client/RemixClerkProvider.tsx

@@ -56,6 +56,8 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
     __afterSignUpUrl,
     __clerkJSUrl,
     __clerkJSVersion,
+    __telemetryDisabled,
+    __telemetryDebug,
   } = clerkState?.__internal_clerk_state || {};
 
   React.useEffect(() => {
@@ -77,6 +79,10 @@ export function ClerkProvider({ children, ...rest }: RemixClerkProviderProps): J
     afterSignUpUrl: __afterSignUpUrl,
     clerkJSUrl: __clerkJSUrl,
     clerkJSVersion: __clerkJSVersion,
+    telemetry: {
+      disabled: __telemetryDisabled,
+      debug: __telemetryDebug,
+    },
   };
 
   return (

packages/remix/src/client/types.ts

@@ -18,6 +18,8 @@ export type ClerkState = {
     __clerk_debug: any;
     __clerkJSUrl: string | undefined;
     __clerkJSVersion: string | undefined;
+    __telemetryDisabled: boolean | undefined;
+    __telemetryDebug: boolean | undefined;
   };
 };
 

packages/remix/src/ssr/utils.ts

@@ -1,5 +1,6 @@
 import type { AuthObject, RequestState } from '@clerk/backend';
 import { constants, debugRequestState, loadInterstitialFromLocal } from '@clerk/backend';
+import { isTruthy } from '@clerk/shared/underscore';
 import type { AppLoadContext, defer } from '@remix-run/server-runtime';
 import { json } from '@remix-run/server-runtime';
 import cookie from 'cookie';
@@ -165,6 +166,8 @@ export function getResponseClerkState(requestState: RequestState, context: AppLo
     __clerk_debug: debugRequestState(requestState),
     __clerkJSUrl: getEnvVariable('CLERK_JS', context),
     __clerkJSVersion: getEnvVariable('CLERK_JS_VERSION', context),
+    __telemetryDisabled: isTruthy(getEnvVariable('CLERK_TELEMETRY_DISABLED', context)),
+    __telemetryDebug: isTruthy(getEnvVariable('CLERK_TELEMETRY_DEBUG', context)),
   });
 
   const headers = observabilityHeadersFromRequestState(requestState);

packages/shared/.gitignore

@@ -1,2 +1,2 @@
-*/
+/*/
 !src/

packages/shared/jest.config.js

@@ -4,6 +4,9 @@ const { name } = require('./package.json');
 const config = {
   displayName: name.replace('@clerk', ''),
   injectGlobals: true,
+  globals: {
+    fetch: global.fetch,
+  },
 
   testEnvironment: 'jsdom',
   roots: ['<rootDir>/src'],

packages/shared/src/__tests__/telemetry.test.ts

@@ -0,0 +1,149 @@
+import { TelemetryCollector } from '../telemetry';
+
+jest.useFakeTimers();
+
+const TEST_PK = 'pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk';
+
+describe('TelemetryCollector', () => {
+  test('does nothing when disabled', async () => {
+    const fetchSpy = jest.spyOn(global, 'fetch');
+
+    const collector = new TelemetryCollector({
+      disabled: true,
+      publishableKey: TEST_PK,
+    });
+
+    collector.record('TEST_EVENT', {});
+
+    jest.runAllTimers();
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+
+    fetchSpy.mockRestore();
+  });
+
+  test('does nothing when CLERK_TELEMETRY_DISABLED is set', async () => {
+    process.env.CLERK_TELEMETRY_DISABLED = '1';
+
+    const fetchSpy = jest.spyOn(global, 'fetch');
+
+    const collector = new TelemetryCollector({
+      publishableKey: TEST_PK,
+    });
+
+    collector.record('TEST_EVENT', {});
+
+    jest.runAllTimers();
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+
+    fetchSpy.mockRestore();
+
+    process.env.CLERK_TELEMETRY_DISABLED = undefined;
+  });
+
+  test('does not send events when debug is enabled, logs them instead', async () => {
+    const fetchSpy = jest.spyOn(global, 'fetch');
+    const consoleSpy = jest.spyOn(global.console, 'log');
+
+    const collector = new TelemetryCollector({
+      debug: true,
+      publishableKey: TEST_PK,
+    });
+
+    collector.record('TEST_EVENT', {});
+
+    jest.runAllTimers();
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+
+    expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "cv": "",
+            "event": "TEST_EVENT",
+            "it": "development",
+            "payload": {},
+            "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+            "sdk": undefined,
+            "sdkv": undefined,
+          },
+        ],
+      ]
+    `);
+
+    consoleSpy.mockRestore();
+    fetchSpy.mockRestore();
+  });
+
+  test('enables debug via environment variable', async () => {
+    process.env.CLERK_TELEMETRY_DEBUG = '1';
+
+    const fetchSpy = jest.spyOn(global, 'fetch');
+    const consoleSpy = jest.spyOn(global.console, 'log');
+
+    const collector = new TelemetryCollector({
+      publishableKey: TEST_PK,
+    });
+
+    collector.record('TEST_EVENT', {});
+
+    jest.runAllTimers();
+
+    expect(fetchSpy).not.toHaveBeenCalled();
+
+    expect(consoleSpy.mock.calls).toMatchInlineSnapshot(`
+      [
+        [
+          {
+            "cv": "",
+            "event": "TEST_EVENT",
+            "it": "development",
+            "payload": {},
+            "pk": "pk_test_Zm9vLWJhci0xMy5jbGVyay5hY2NvdW50cy5kZXYk",
+            "sdk": undefined,
+            "sdkv": undefined,
+          },
+        ],
+      ]
+    `);
+
+    consoleSpy.mockRestore();
+    fetchSpy.mockRestore();
+
+    process.env.CLERK_TELEMETRY_DEBUG = undefined;
+  });
+
+  test('sends events after a delay when buffer is not full', async () => {
+    const fetchSpy = jest.spyOn(global, 'fetch');
+
+    const collector = new TelemetryCollector({
+      publishableKey: TEST_PK,
+    });
+
+    collector.record('TEST_EVENT', {});
+
+    jest.runAllTimers();
+
+    expect(fetchSpy).toHaveBeenCalled();
+
+    fetchSpy.mockRestore();
+  });
+
+  test('sends events immediately when the buffer limit is reached', async () => {
+    const fetchSpy = jest.spyOn(global, 'fetch');
+
+    const collector = new TelemetryCollector({
+      maxBufferSize: 2,
+      publishableKey: TEST_PK,
+    });
+
+    collector.record('TEST_EVENT', {});
+    collector.record('TEST_EVENT', {});
+
+    expect(fetchSpy).toHaveBeenCalled();
+
+    fetchSpy.mockRestore();
+  });
+});