feat(nextjs): Track usage of pages and app router (#5236)

.changeset/eighty-emus-smile.md

@@ -0,0 +1,5 @@
+---
+'@clerk/nextjs': patch
+---
+
+Track usage of pages and app router.

.changeset/tricky-rings-trade.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Update `TelemetryCollector` to throttle events after they've been sampled.

packages/nextjs/src/app-router/client/ClerkProvider.tsx

@@ -13,6 +13,7 @@ import type { NextClerkProviderProps } from '../../types';
 import { ClerkJSScript } from '../../utils/clerk-js-script';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
+import { RouterTelemetry } from '../../utils/router-telemetry';
 import { isNextWithUnstableServerActions } from '../../utils/sdk-versions';
 import { invalidateCacheAction } from '../server-actions';
 import { useAwaitablePush } from './useAwaitablePush';
@@ -107,6 +108,7 @@ const NextClientClerkProvider = (props: NextClerkProviderProps) => {
   return (
     <ClerkNextOptionsProvider options={mergedProps}>
       <ReactClerkProvider {...mergedProps}>
+        <RouterTelemetry />
         <ClerkJSScript router='app' />
         {children}
       </ReactClerkProvider>

packages/nextjs/src/pages/ClerkProvider.tsx

@@ -11,6 +11,7 @@ import { ClerkJSScript } from '../utils/clerk-js-script';
 import { invalidateNextRouterCache } from '../utils/invalidateNextRouterCache';
 import { mergeNextClerkPropsWithEnv } from '../utils/mergeNextClerkPropsWithEnv';
 import { removeBasePath } from '../utils/removeBasePath';
+import { RouterTelemetry } from '../utils/router-telemetry';
 
 setErrorThrowerOptions({ packageName: PACKAGE_NAME });
 setClerkJsLoadingErrorPackageName(PACKAGE_NAME);
@@ -53,6 +54,7 @@ export function ClerkProvider({ children, ...props }: NextClerkProviderProps): J
         {...mergedProps}
         initialState={initialState}
       >
+        <RouterTelemetry />
         <ClerkJSScript router='pages' />
         {children}
       </ReactClerkProvider>

packages/nextjs/src/utils/router-telemetry.ts

@@ -0,0 +1,22 @@
+import { eventFrameworkMetadata } from '@clerk/shared/telemetry';
+
+import { useClerk } from '../client-boundary/hooks';
+import { usePagesRouter } from '../client-boundary/hooks/usePagesRouter';
+
+const RouterTelemetry = () => {
+  const clerk = useClerk();
+  const { pagesRouter } = usePagesRouter();
+
+  /**
+   * Caching and throttling is handled internally it's safe to execute on every navigation.
+   */
+  clerk.telemetry?.record(
+    eventFrameworkMetadata({
+      router: pagesRouter ? 'pages' : 'app',
+    }),
+  );
+
+  return null;
+};
+
+export { RouterTelemetry };

packages/shared/src/telemetry/collector.ts

@@ -135,14 +135,15 @@ export class TelemetryCollector implements TelemetryCollectorInterface {
   #shouldBeSampled(preparedPayload: TelemetryEvent, eventSamplingRate?: number) {
     const randomSeed = Math.random();
 
-    if (this.#eventThrottler.isEventThrottled(preparedPayload)) {
+    const toBeSampled =
+      randomSeed <= this.#config.samplingRate &&
+      (typeof eventSamplingRate === 'undefined' || randomSeed <= eventSamplingRate);
+
+    if (!toBeSampled) {
       return false;
     }
 
-    return (
-      randomSeed <= this.#config.samplingRate &&
-      (typeof eventSamplingRate === 'undefined' || randomSeed <= eventSamplingRate)
-    );
+    return !this.#eventThrottler.isEventThrottled(preparedPayload);
   }
 
   #scheduleFlush(): void {

packages/shared/src/telemetry/events/framework-metadata.ts

@@ -0,0 +1,17 @@
+import type { TelemetryEventRaw } from '@clerk/types';
+
+const EVENT_FRAMEWORK_METADATA = 'FRAMEWORK_METADATA';
+const EVENT_SAMPLING_RATE = 0.1;
+
+type EventFrameworkMetadata = Record<string, string | number | boolean>;
+
+/**
+ * Fired when a helper method is called from a Clerk SDK.
+ */
+export function eventFrameworkMetadata(payload: EventFrameworkMetadata): TelemetryEventRaw<EventFrameworkMetadata> {
+  return {
+    event: EVENT_FRAMEWORK_METADATA,
+    eventSamplingRate: EVENT_SAMPLING_RATE,
+    payload,
+  };
+}

packages/shared/src/telemetry/events/index.ts

@@ -1,2 +1,3 @@
 export * from './component-mounted';
 export * from './method-called';
+export * from './framework-metadata';