Create file to control telemetry event firing

Author: heatlikeheatwave

packages/nextjs/src/app-router/server/keyless-provider.tsx

@@ -6,7 +6,6 @@ import React from 'react';
 
 import { createClerkClientWithOptions } from '../../server/createClerkClient';
 import { collectKeylessMetadata, formatMetadataHeaders } from '../../server/keyless-custom-headers';
-import { detectKeylessEnvDrift } from '../../server/keyless-telemetry';
 import type { NextClerkProviderProps } from '../../types';
 import { canUseKeyless } from '../../utils/feature-flags';
 import { mergeNextClerkPropsWithEnv } from '../../utils/mergeNextClerkPropsWithEnv';
@@ -48,11 +47,6 @@ export const KeylessProvider = async (props: KeylessProviderProps) => {
     .then(mod => mod.createOrReadKeyless())
     .catch(() => null);
 
-  // Detect environment variable drift and fire telemetry events
-  if (newOrReadKeys) {
-    await detectKeylessEnvDrift();
-  }
-
   const { clerkDevelopmentCache, createConfirmationMessage, createKeylessModeMessage } = await import(
     '../../server/keyless-log-cache.js'
   );

packages/nextjs/src/server/keyless-telemetry.ts

@@ -1,9 +1,12 @@
 import type { TelemetryEventRaw } from '@clerk/types';
+import { promises as fs } from 'fs';
+import { join } from 'path';
 
 import { createClerkClientWithOptions } from './createClerkClient';
 
 const EVENT_KEYLESS_ENV_DRIFT_DETECTED = 'KEYLESS_ENV_DRIFT_DETECTED';
 const EVENT_SAMPLING_RATE = 1; // 100% sampling rate
+const TELEMETRY_FLAG_FILE = '.clerk/.tmp/keyless-telemetry-fired.json';
 
 type EventKeylessEnvDriftPayload = {
   publicKeyMatch: boolean;
@@ -14,6 +17,47 @@ type EventKeylessEnvDriftPayload = {
   envPublishableKey: string;
 };
 
+/**
+ * Gets the absolute path to the telemetry flag file.
+ */
+function getTelemetryFlagFilePath(): string {
+  return join(process.cwd(), TELEMETRY_FLAG_FILE);
+}
+
+/**
+ * Checks if the telemetry event has already been fired by looking for a flag file.
+ */
+async function hasTelemetryEventBeenFired(): Promise<boolean> {
+  try {
+    await fs.access(getTelemetryFlagFilePath());
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Creates a flag file to mark that the telemetry event has been fired.
+ */
+async function markTelemetryEventAsFired(): Promise<void> {
+  try {
+    // Ensure the directory exists
+    const dir = join(process.cwd(), '.clerk/.tmp');
+    await fs.mkdir(dir, { recursive: true });
+
+    // Create the flag file with timestamp
+    const flagData = {
+      firedAt: new Date().toISOString(),
+      event: EVENT_KEYLESS_ENV_DRIFT_DETECTED,
+    };
+
+    await fs.writeFile(getTelemetryFlagFilePath(), JSON.stringify(flagData, null, 2));
+  } catch (error) {
+    // Silently handle errors to avoid breaking the application
+    console.warn('Failed to create telemetry flag file:', error);
+  }
+}
+
 /**
  * Detects environment variable drift for keyless Next.js applications and fires telemetry events.
  *
@@ -23,6 +67,8 @@ type EventKeylessEnvDriftPayload = {
  * If there's a mismatch, it fires a `KEYLESS_ENV_DRIFT_DETECTED` event.
  * For local testing purposes, it also fires a `KEYLESS_ENV_DRIFT_NOT_DETECTED` event when
  * keys exist and match the environment variables.
+ *
+ * The telemetry event will only fire once per application instance to avoid noise.
  */
 export async function detectKeylessEnvDrift(): Promise<void> {
   // Only run on server side
@@ -31,6 +77,11 @@ export async function detectKeylessEnvDrift(): Promise<void> {
   }
 
   try {
+    // Check if telemetry event has already been fired
+    if (await hasTelemetryEventBeenFired()) {
+      return;
+    }
+
     // Dynamically import server-side dependencies to avoid client-side issues
     const { safeParseClerkFile } = await import('./keyless-node.js');
 
@@ -87,6 +138,9 @@ export async function detectKeylessEnvDrift(): Promise<void> {
       };
 
       clerkClient.telemetry?.record(driftDetectedEvent);
+
+      // Mark the telemetry event as fired to prevent future executions
+      await markTelemetryEventAsFired();
     }
   } catch (error) {
     // Silently handle errors to avoid breaking the application