feat(cloudflare): Add plugin for cloudflare pages

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

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';

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) });
-}

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';

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());
+}