feat(cloudflare): Add plugin for cloudflare pages (#13123)

Before reviewing this change, I recommend reading through a GH discussion I wrote up that explains the reasoning behind the API surface of the cloudflare SDK: #13007 This PR adds support for [Cloudflare Pages](https://developers.cloudflare.com/pages/), Cloudflare's fullstack development deployment platform that is powered by Cloudflare Workers under the hood. Think of this platform having very similar capabilities (and constraints) as Vercel. To set the plugin up, you do something like so: ```javascript // functions/_middleware.js import * as Sentry from '@sentry/cloudflare'; export const onRequest = Sentry.sentryPagesPlugin({ dsn: process.env.SENTRY_DSN, tracesSampleRate: 1.0, }); ``` We have to use the middleware instead of a global init because we need to call `init` for every single new incoming request to make sure the sentry instance does not get stale with redeployments. While implementing `sentryPagesPlugin`, I noticed that there was a logic that was redundant between it and `withSentry`, the API for cloudflare workers. This led me to refactor this into a common helper, `wrapRequestHandler`, which is contained in `packages/cloudflare/src/request.ts`. That is why there is diffs in this PR for `packages/cloudflare/src/handler.ts`.
getsentry · Jul 31, 2024 · 945cdbc · 945cdbc
1 parent e2668f8
commit 945cdbc
Show file tree

Hide file tree

Showing 10 changed files with 543 additions and 355 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,28 @@
 
 - "You miss 100 percent of the chances you don't take. — Wayne Gretzky" — Michael Scott
 
+## Unreleased
+
+### Important Changes
+
+- **feat(cloudflare): Add plugin for cloudflare pages (#13123)**
+
+This release adds support for Cloudflare Pages to `@sentry/cloudflare`, our SDK for the
+[Cloudflare Workers JavaScript Runtime](https://developers.cloudflare.com/workers/)! For details on how to use it,
+please see the [README](./packages/cloudflare/README.md). Any feedback/bug reports are greatly appreciated, please
+[reach out on GitHub](https://github.com/getsentry/sentry-javascript/issues/12620).
+
+```javascript
+// functions/_middleware.js
+import * as Sentry from '@sentry/cloudflare';
+
+export const onRequest = Sentry.sentryPagesPlugin({
+  dsn: __PUBLIC_DSN__,
+  // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
+  tracesSampleRate: 1.0,
+});
+```
+
 ## 8.21.0
 
 ### Important Changes

diff --git a/packages/cloudflare/README.md b/packages/cloudflare/README.md
@@ -4,7 +4,7 @@
   </a>
 </p>
 
-# Official Sentry SDK for Cloudflare [UNRELEASED]
+# Official Sentry SDK for Cloudflare
 
 [![npm version](https://img.shields.io/npm/v/@sentry/cloudflare.svg)](https://www.npmjs.com/package/@sentry/cloudflare)
 [![npm dm](https://img.shields.io/npm/dm/@sentry/cloudflare.svg)](https://www.npmjs.com/package/@sentry/cloudflare)
@@ -18,9 +18,7 @@
 **Note: This SDK is unreleased. Please follow the
 [tracking GH issue](https://github.com/getsentry/sentry-javascript/issues/12620) for updates.**
 
-Below details the setup for the Cloudflare Workers. Cloudflare Pages support is in active development.
-
-## Setup (Cloudflare Workers)
+## Install
 
 To get started, first install the `@sentry/cloudflare` package:
 
@@ -36,6 +34,46 @@ compatibility_flags = ["nodejs_compat"]
 # compatibility_flags = ["nodejs_als"]
 ```
 
+Then you can either setup up the SDK for [Cloudflare Pages](#setup-cloudflare-pages) or
+[Cloudflare Workers](#setup-cloudflare-workers).
+
+## Setup (Cloudflare Pages)
+
+To use this SDK, add the `sentryPagesPlugin` as
+[middleware to your Cloudflare Pages application](https://developers.cloudflare.com/pages/functions/middleware/).
+
+We recommend adding a `functions/_middleware.js` for the middleware setup so that Sentry is initialized for your entire
+app.
+
+```javascript
+// functions/_middleware.js
+import * as Sentry from '@sentry/cloudflare';
+
+export const onRequest = Sentry.sentryPagesPlugin({
+  dsn: process.env.SENTRY_DSN,
+  // Set tracesSampleRate to 1.0 to capture 100% of spans for tracing.
+  tracesSampleRate: 1.0,
+});
+```
+
+If you need to to chain multiple middlewares, you can do so by exporting an array of middlewares. Make sure the Sentry
+middleware is the first one in the array.
+
+```javascript
+import * as Sentry from '@sentry/cloudflare';
+
+export const onRequest = [
+  // Make sure Sentry is the first middleware
+  Sentry.sentryPagesPlugin({
+    dsn: process.env.SENTRY_DSN,
+    tracesSampleRate: 1.0,
+  }),
+  // Add more middlewares here
+];
+```
+
+## Setup (Cloudflare Workers)
+
 To use this SDK, wrap your handler with the `withSentry` function. This will initialize the SDK and hook into the
 environment. Note that you can turn off almost all side effects using the respective options.
 
@@ -58,7 +96,7 @@ export default withSentry(
 );
 ```
 
-### Sourcemaps (Cloudflare Workers)
+### Sourcemaps
 
 Configure uploading sourcemaps via the Sentry Wizard:
 
@@ -68,10 +106,11 @@ npx @sentry/wizard@latest -i sourcemaps
 
 See more details in our [docs](https://docs.sentry.io/platforms/javascript/sourcemaps/).
 
-## Usage (Cloudflare Workers)
+## Usage
 
 To set context information or send manual events, use the exported functions of `@sentry/cloudflare`. Note that these
-functions will require your exported handler to be wrapped in `withSentry`.
+functions will require the usage of the Sentry helpers, either `withSentry` function for Cloudflare Workers or the
+`sentryPagesPlugin` middleware for Cloudflare Pages.
 
 ```javascript
 import * as Sentry from '@sentry/cloudflare';

diff --git a/packages/cloudflare/src/handler.ts b/packages/cloudflare/src/handler.ts
@@ -1,23 +1,7 @@
-import type {
-  ExportedHandler,
-  ExportedHandlerFetchHandler,
-  IncomingRequestCfProperties,
-} from '@cloudflare/workers-types';
-import {
-  SEMANTIC_ATTRIBUTE_SENTRY_OP,
-  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
-  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
-  captureException,
-  continueTrace,
-  flush,
-  setHttpStatus,
-  startSpan,
-  withIsolationScope,
-} from '@sentry/core';
-import type { Options, Scope, SpanAttributes } from '@sentry/types';
-import { stripUrlQueryAndFragment, winterCGRequestToRequestData } from '@sentry/utils';
+import type { ExportedHandler, ExportedHandlerFetchHandler } from '@cloudflare/workers-types';
+import type { Options } from '@sentry/types';
 import { setAsyncLocalStorageAsyncContextStrategy } from './async';
-import { init } from './sdk';
+import { wrapRequestHandler } from './request';
 
 /**
  * Extract environment generic from exported handler.
@@ -47,70 +31,8 @@ export function withSentry<E extends ExportedHandler<any>>(
     handler.fetch = new Proxy(handler.fetch, {
       apply(target, thisArg, args: Parameters<ExportedHandlerFetchHandler<ExtractEnv<E>>>) {
         const [request, env, context] = args;
-        return withIsolationScope(isolationScope => {
-          const options = optionsCallback(env);
-          const client = init(options);
-          isolationScope.setClient(client);
-
-          const attributes: SpanAttributes = {
-            [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.http.cloudflare-worker',
-            [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
-            [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'http.server',
-            ['http.request.method']: request.method,
-            ['url.full']: request.url,
-          };
-
-          const contentLength = request.headers.get('content-length');
-          if (contentLength) {
-            attributes['http.request.body.size'] = parseInt(contentLength, 10);
-          }
-
-          let pathname = '';
-          try {
-            const url = new URL(request.url);
-            pathname = url.pathname;
-            attributes['server.address'] = url.hostname;
-            attributes['url.scheme'] = url.protocol.replace(':', '');
-          } catch {
-            // skip
-          }
-
-          addRequest(isolationScope, request);
-          addCloudResourceContext(isolationScope);
-          if (request.cf) {
-            addCultureContext(isolationScope, request.cf);
-            attributes['network.protocol.name'] = request.cf.httpProtocol;
-          }
-
-          const routeName = `${request.method} ${pathname ? stripUrlQueryAndFragment(pathname) : '/'}`;
-
-          return continueTrace(
-            { sentryTrace: request.headers.get('sentry-trace') || '', baggage: request.headers.get('baggage') },
-            () => {
-              // Note: This span will not have a duration unless I/O happens in the handler. This is
-              // because of how the cloudflare workers runtime works.
-              // See: https://developers.cloudflare.com/workers/runtime-apis/performance/
-              return startSpan(
-                {
-                  name: routeName,
-                  attributes,
-                },
-                async span => {
-                  try {
-                    const res = await (target.apply(thisArg, args) as ReturnType<typeof target>);
-                    setHttpStatus(span, res.status);
-                    return res;
-                  } catch (e) {
-                    captureException(e, { mechanism: { handled: false, type: 'cloudflare' } });
-                    throw e;
-                  } finally {
-                    context.waitUntil(flush(2000));
-                  }
-                },
-              );
-            },
-          );
-        });
+        const options = optionsCallback(env);
+        return wrapRequestHandler({ options, request, context }, () => target.apply(thisArg, args));
       },
     });
 
@@ -120,19 +42,3 @@ export function withSentry<E extends ExportedHandler<any>>(
 
   return handler;
 }
-
-function addCloudResourceContext(isolationScope: Scope): void {
-  isolationScope.setContext('cloud_resource', {
-    'cloud.provider': 'cloudflare',
-  });
-}
-
-function addCultureContext(isolationScope: Scope, cf: IncomingRequestCfProperties): void {
-  isolationScope.setContext('culture', {
-    timezone: cf.timezone,
-  });
-}
-
-function addRequest(isolationScope: Scope, request: Request): void {
-  isolationScope.setSDKProcessingMetadata({ request: winterCGRequestToRequestData(request) });
-}
diff --git a/packages/cloudflare/src/index.ts b/packages/cloudflare/src/index.ts
@@ -85,6 +85,7 @@ export {
 } from '@sentry/core';
 
 export { withSentry } from './handler';
+export { sentryPagesPlugin } from './pages-plugin';
 
 export { CloudflareClient } from './client';
 export { getDefaultIntegrations } from './sdk';

diff --git a/packages/cloudflare/src/pages-plugin.ts b/packages/cloudflare/src/pages-plugin.ts
@@ -0,0 +1,32 @@
+import { setAsyncLocalStorageAsyncContextStrategy } from './async';
+import type { CloudflareOptions } from './client';
+import { wrapRequestHandler } from './request';
+
+/**
+ * Plugin middleware for Cloudflare Pages.
+ *
+ * Initializes the SDK and wraps cloudflare pages requests with SDK instrumentation.
+ *
+ * @example
+ * ```javascript
+ * // functions/_middleware.js
+ * import * as Sentry from '@sentry/cloudflare';
+ *
+ * export const onRequest = Sentry.sentryPagesPlugin({
+ *  dsn: process.env.SENTRY_DSN,
+ *  tracesSampleRate: 1.0,
+ * });
+ * ```
+ *
+ * @param _options
+ * @returns
+ */
+export function sentryPagesPlugin<
+  Env = unknown,
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  Params extends string = any,
+  Data extends Record<string, unknown> = Record<string, unknown>,
+>(options: CloudflareOptions): PagesPluginFunction<Env, Params, Data, CloudflareOptions> {
+  setAsyncLocalStorageAsyncContextStrategy();
+  return context => wrapRequestHandler({ options, request: context.request, context }, () => context.next());
+}