feat(cloudflare): instrument scheduled handler (#13114)

This PR adds instrumentation for the [`scheduled`
handler](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/)
in cloudflare workers. This is used for cron triggers.

I elected to not do automatic cron instrumentation for now.
Instead I added manual instrumentation docs to the README, this will get
copied to the sentry docs eventually.

packages/cloudflare/README.md

@@ -15,7 +15,7 @@
 - [Official SDK Docs](https://docs.sentry.io/quickstart/)
 - [TypeDoc](http://getsentry.github.io/sentry-javascript/)
 
-**Note: This SDK is unreleased. Please follow the
+**Note: This SDK is in an alpha state. Please follow the
 [tracking GH issue](https://github.com/getsentry/sentry-javascript/issues/12620) for updates.**
 
 ## Install
@@ -143,8 +143,50 @@ You can use the `instrumentD1WithSentry` method to instrument [Cloudflare D1](ht
 Cloudflare's serverless SQL database with Sentry.
 
 ```javascript
+import * as Sentry from '@sentry/cloudflare';
+
 // env.DB is the D1 DB binding configured in your `wrangler.toml`
-const db = instrumentD1WithSentry(env.DB);
+const db = Sentry.instrumentD1WithSentry(env.DB);
 // Now you can use the database as usual
 await db.prepare('SELECT * FROM table WHERE id = ?').bind(1).run();
 ```
+
+## Cron Monitoring (Cloudflare Workers)
+
+[Sentry Crons](https://docs.sentry.io/product/crons/) allows you to monitor the uptime and performance of any scheduled,
+recurring job in your application.
+
+To instrument your cron triggers, use the `Sentry.withMonitor` API in your
+[`Scheduled` handler](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/).
+
+```js
+export default {
+  async scheduled(event, env, ctx) {
+    ctx.waitUntil(
+      Sentry.withMonitor('your-cron-name', () => {
+        return doSomeTaskOnASchedule();
+      }),
+    );
+  },
+};
+```
+
+You can also use supply a monitor config to upsert cron monitors with additional metadata:
+
+```js
+const monitorConfig = {
+  schedule: {
+    type: 'crontab',
+    value: '* * * * *',
+  },
+  checkinMargin: 2, // In minutes. Optional.
+  maxRuntime: 10, // In minutes. Optional.
+  timezone: 'America/Los_Angeles', // Optional.
+};
+
+export default {
+  async scheduled(event, env, ctx) {
+    Sentry.withMonitor('your-cron-name', () => doSomeTaskOnASchedule(), monitorConfig);
+  },
+};
+```

packages/cloudflare/package.json

@@ -47,10 +47,9 @@
     "@cloudflare/workers-types": "^4.x"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20240722.0",
+    "@cloudflare/workers-types": "^4.20240725.0",
     "@types/node": "^14.18.0",
-    "miniflare": "^3.20240718.0",
-    "wrangler": "^3.65.1"
+    "wrangler": "^3.67.1"
   },
   "scripts": {
     "build": "run-p build:transpile build:types",

packages/cloudflare/src/handler.ts

@@ -1,7 +1,21 @@
-import type { ExportedHandler, ExportedHandlerFetchHandler } from '@cloudflare/workers-types';
-import type { Options } from '@sentry/types';
+import type {
+  ExportedHandler,
+  ExportedHandlerFetchHandler,
+  ExportedHandlerScheduledHandler,
+} from '@cloudflare/workers-types';
+import {
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+  captureException,
+  flush,
+  startSpan,
+  withIsolationScope,
+} from '@sentry/core';
 import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import type { CloudflareOptions } from './client';
 import { wrapRequestHandler } from './request';
+import { addCloudResourceContext } from './scope-utils';
+import { init } from './sdk';
 
 /**
  * Extract environment generic from exported handler.
@@ -21,7 +35,7 @@ type ExtractEnv<P> = P extends ExportedHandler<infer Env> ? Env : never;
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function withSentry<E extends ExportedHandler<any>>(
-  optionsCallback: (env: ExtractEnv<E>) => Options,
+  optionsCallback: (env: ExtractEnv<E>) => CloudflareOptions,
   handler: E,
 ): E {
   setAsyncLocalStorageAsyncContextStrategy();
@@ -40,5 +54,52 @@ export function withSentry<E extends ExportedHandler<any>>(
     (handler.fetch as any).__SENTRY_INSTRUMENTED__ = true;
   }
 
+  if (
+    'scheduled' in handler &&
+    typeof handler.scheduled === 'function' &&
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    !(handler.scheduled as any).__SENTRY_INSTRUMENTED__
+  ) {
+    handler.scheduled = new Proxy(handler.scheduled, {
+      apply(target, thisArg, args: Parameters<ExportedHandlerScheduledHandler<ExtractEnv<E>>>) {
+        const [event, env, context] = args;
+        return withIsolationScope(isolationScope => {
+          const options = optionsCallback(env);
+          const client = init(options);
+          isolationScope.setClient(client);
+
+          addCloudResourceContext(isolationScope);
+
+          return startSpan(
+            {
+              op: 'faas.cron',
+              name: `Scheduled Cron ${event.cron}`,
+              attributes: {
+                'faas.cron': event.cron,
+                'faas.time': new Date(event.scheduledTime).toISOString(),
+                'faas.trigger': 'timer',
+                [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.faas.cloudflare',
+                [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'task',
+              },
+            },
+            async () => {
+              try {
+                return await (target.apply(thisArg, args) as ReturnType<typeof target>);
+              } catch (e) {
+                captureException(e, { mechanism: { handled: false, type: 'cloudflare' } });
+                throw e;
+              } finally {
+                context.waitUntil(flush(2000));
+              }
+            },
+          );
+        });
+      },
+    });
+
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-explicit-any
+    (handler.scheduled as any).__SENTRY_INSTRUMENTED__ = true;
+  }
+
   return handler;
 }

packages/cloudflare/src/request.ts

@@ -11,9 +11,10 @@ import {
   startSpan,
   withIsolationScope,
 } from '@sentry/core';
-import type { Scope, SpanAttributes } from '@sentry/types';
-import { stripUrlQueryAndFragment, winterCGRequestToRequestData } from '@sentry/utils';
+import type { SpanAttributes } from '@sentry/types';
+import { stripUrlQueryAndFragment } from '@sentry/utils';
 import type { CloudflareOptions } from './client';
+import { addCloudResourceContext, addCultureContext, addRequest } from './scope-utils';
 import { init } from './sdk';
 
 interface RequestHandlerWrapperOptions {
@@ -96,28 +97,3 @@ export function wrapRequestHandler(
     );
   });
 }
-
-/**
- * Set cloud resource context on scope.
- */
-function addCloudResourceContext(scope: Scope): void {
-  scope.setContext('cloud_resource', {
-    'cloud.provider': 'cloudflare',
-  });
-}
-
-/**
- * Set culture context on scope
- */
-function addCultureContext(scope: Scope, cf: IncomingRequestCfProperties): void {
-  scope.setContext('culture', {
-    timezone: cf.timezone,
-  });
-}
-
-/**
- * Set request data on scope
- */
-function addRequest(scope: Scope, request: Request): void {
-  scope.setSDKProcessingMetadata({ request: winterCGRequestToRequestData(request) });
-}

packages/cloudflare/src/scope-utils.ts

@@ -0,0 +1,29 @@
+import type { IncomingRequestCfProperties } from '@cloudflare/workers-types';
+
+import type { Scope } from '@sentry/types';
+import { winterCGRequestToRequestData } from '@sentry/utils';
+
+/**
+ * Set cloud resource context on scope.
+ */
+export function addCloudResourceContext(scope: Scope): void {
+  scope.setContext('cloud_resource', {
+    'cloud.provider': 'cloudflare',
+  });
+}
+
+/**
+ * Set culture context on scope
+ */
+export function addCultureContext(scope: Scope, cf: IncomingRequestCfProperties): void {
+  scope.setContext('culture', {
+    timezone: cf.timezone,
+  });
+}
+
+/**
+ * Set request data on scope
+ */
+export function addRequest(scope: Scope, request: Request): void {
+  scope.setSDKProcessingMetadata({ request: winterCGRequestToRequestData(request) });
+}

packages/cloudflare/src/sdk.ts

@@ -7,17 +7,17 @@ import {
   linkedErrorsIntegration,
   requestDataIntegration,
 } from '@sentry/core';
-import type { Integration, Options } from '@sentry/types';
+import type { Integration } from '@sentry/types';
 import { stackParserFromStackParserOptions } from '@sentry/utils';
-import type { CloudflareClientOptions } from './client';
+import type { CloudflareClientOptions, CloudflareOptions } from './client';
 import { CloudflareClient } from './client';
 
 import { fetchIntegration } from './integrations/fetch';
 import { makeCloudflareTransport } from './transport';
 import { defaultStackParser } from './vendor/stacktrace';
 
 /** Get the default integrations for the Cloudflare SDK. */
-export function getDefaultIntegrations(options: Options): Integration[] {
+export function getDefaultIntegrations(options: CloudflareOptions): Integration[] {
   const sendDefaultPii = options.sendDefaultPii ?? false;
   return [
     dedupeIntegration(),
@@ -32,7 +32,7 @@ export function getDefaultIntegrations(options: Options): Integration[] {
 /**
  * Initializes the cloudflare SDK.
  */
-export function init(options: Options): CloudflareClient | undefined {
+export function init(options: CloudflareOptions): CloudflareClient | undefined {
   if (options.defaultIntegrations === undefined) {
     options.defaultIntegrations = getDefaultIntegrations(options);
   }