fix(cloudflare, vercel-edge): Disable timer-based flush for serverless runtimes

The weight-based flushing mechanism for logs and metrics schedules a
`setTimeout(fn, 5000)` after each capture. In Cloudflare Workers built
with `@cloudflare/vite-plugin` (native ESM + `no_bundle: true`), workerd
rejects this timer as running outside request context.

Add a `_flushInterval` internal option to `ClientOptions`. When set to 0,
the idle flush timer is skipped entirely. Size-based flushing (800KB) and
explicit `flush()` calls (via `withSentry` → `flushAndDispose`) still work.

Set `_flushInterval: 0` in `CloudflareClient` and `VercelEdgeClient`.

Fixes #20888

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

packages/cloudflare/src/client.ts

@@ -34,6 +34,7 @@ export class CloudflareClient extends ServerRuntimeClient {
       // TODO: Grab version information
       runtime: { name: 'cloudflare' },
       // TODO: Add server name
+      _flushInterval: 0,
     };
 
     super(clientOptions);

packages/core/src/client.ts

@@ -137,18 +137,21 @@ function setupWeightBasedFlushing<
     if (weight >= 800_000) {
       flushFn(client);
     } else if (!isTimerActive) {
-      // Only start timer if one isn't already running.
-      // This prevents flushing being delayed by items that arrive close to the timeout limit
-      // and thus resetting the flushing timeout and delaying items being flushed.
-      isTimerActive = true;
-      // Use safeUnref so the timer doesn't prevent the process from exiting
-      flushTimeout = safeUnref(
-        setTimeout(() => {
-          flushFn(client);
-          // Note: isTimerActive is reset by the flushHook handler above, not here,
-          // to avoid race conditions when new items arrive during the flush.
-        }, DEFAULT_FLUSH_INTERVAL),
-      );
+      const flushInterval = client.getOptions()._flushInterval ?? DEFAULT_FLUSH_INTERVAL;
+      if (flushInterval > 0) {
+        // Only start timer if one isn't already running.
+        // This prevents flushing being delayed by items that arrive close to the timeout limit
+        // and thus resetting the flushing timeout and delaying items being flushed.
+        isTimerActive = true;
+        // Use safeUnref so the timer doesn't prevent the process from exiting
+        flushTimeout = safeUnref(
+          setTimeout(() => {
+            flushFn(client);
+            // Note: isTimerActive is reset by the flushHook handler above, not here,
+            // to avoid race conditions when new items arrive during the flush.
+          }, flushInterval),
+        );
+      }
     }
   });
 

packages/core/src/types/options.ts

@@ -597,6 +597,18 @@ export interface ClientOptions<TO extends BaseTransportOptions = BaseTransportOp
    */
   enableMetrics?: boolean;
 
+  /**
+   * Interval in ms for the idle flush timer used by logs and metrics.
+   * Set to 0 to disable timer-based flushing entirely — useful for
+   * serverless runtimes that forbid background timers (e.g. Cloudflare Workers).
+   *
+   * Size-based flushing and explicit `flush()` calls still work regardless.
+   *
+   * @default 5000
+   * @internal
+   */
+  _flushInterval?: number;
+
   /**
    * An event-processing callback for metrics, guaranteed to be invoked after all other metric
    * processors. This allows a metric to be modified or dropped before it's sent.

packages/core/test/lib/client.test.ts

@@ -3245,6 +3245,64 @@ describe('Client', () => {
 
       expect(flushMetricsHandler).toHaveBeenCalledTimes(1);
     });
+
+    it('does not create a flush timer when _flushInterval is 0', () => {
+      const safeUnrefSpy = vi.spyOn(timerModule, 'safeUnref');
+
+      const options = getDefaultTestClientOptions({
+        dsn: PUBLIC_DSN,
+        _flushInterval: 0,
+      });
+      const client = new TestClient(options);
+      const scope = new Scope();
+      scope.setClient(client);
+
+      _INTERNAL_captureMetric({ name: 'test_metric', value: 42, type: 'counter', attributes: {} }, { scope });
+
+      expect(safeUnrefSpy).not.toHaveBeenCalled();
+
+      safeUnrefSpy.mockRestore();
+    });
+
+    it('still flushes metrics via flush event when _flushInterval is 0', () => {
+      const options = getDefaultTestClientOptions({
+        dsn: PUBLIC_DSN,
+        _flushInterval: 0,
+      });
+      const client = new TestClient(options);
+      const scope = new Scope();
+      scope.setClient(client);
+
+      const sendEnvelopeSpy = vi.spyOn(client, 'sendEnvelope');
+
+      _INTERNAL_captureMetric({ name: 'metric1', value: 1, type: 'counter', attributes: {} }, { scope });
+
+      expect(sendEnvelopeSpy).not.toHaveBeenCalled();
+
+      client.emit('flush');
+
+      expect(sendEnvelopeSpy).toHaveBeenCalledTimes(1);
+    });
+
+    it('still flushes metrics on size threshold when _flushInterval is 0', () => {
+      const options = getDefaultTestClientOptions({
+        dsn: PUBLIC_DSN,
+        _flushInterval: 0,
+      });
+      const client = new TestClient(options);
+      const scope = new Scope();
+      scope.setClient(client);
+
+      const sendEnvelopeSpy = vi.spyOn(client, 'sendEnvelope');
+
+      const largeValue = 'x'.repeat(400_000);
+      _INTERNAL_captureMetric(
+        { name: 'large_metric', value: 1, type: 'counter', attributes: { large_value: largeValue } },
+        { scope },
+      );
+
+      expect(sendEnvelopeSpy).toHaveBeenCalledTimes(1);
+    });
   });
 
   describe('promise buffer usage', () => {

packages/vercel-edge/src/client.ts

@@ -30,6 +30,7 @@ export class VercelEdgeClient extends ServerRuntimeClient<VercelEdgeClientOption
       // Use provided runtime or default to 'vercel-edge'
       runtime: options.runtime || { name: 'vercel-edge' },
       serverName: options.serverName || process.env.SENTRY_NAME,
+      _flushInterval: 0,
     };
 
     super(clientOptions);