Cloudflare SDK Initial Roadmap

[AbhiPrasad]

ref: #12620

Over the past 2 weeks I've been looking at building out a Cloudflare SDK. Initially I was focusing on just cloudflare workers, but I soon realized that cloudflare pages support is extremely important, because a vast majority of the users who wanted Sentry supported were using cloudflare pages (in conjuction with remix, next.js, sveltekit, nuxt, etc.).

This is a writeup that goes through where we started from, and outlines the public API design of @sentry/cloudflare, the SDK we are set to release soon.

Prior art

Our recommended solution for cloudflare workers has been Toucan.js, which has worked pretty well for many users.

Here is the expected usage of Toucan:

import { Toucan } from 'toucan-js';
import { handler } from './handler';

type Env = {
  SENTRY_DSN: string;
};

export default {
  async fetch(request, env, context): Promise<Response> {
    const sentry = new Toucan({
      dsn: env.SENTRY_DSN,
      context,
      request,
    });

    try {
      handler();
      return new Response('Hello!');
    } catch (e) {
      sentry.captureException(e);

      return new Response('Something went wrong! Team has been notified.', {
        status: 500,
      });
    }
  },
} as ExportedHandler<Env>;

Cloudflare themselves point their users to use Toucan, and even created a Cloudlfare Pages plugin that leverages Toucan under the hood:

import sentryPlugin from "@cloudflare/pages-plugin-sentry";

export const onRequest: PagesFunction = sentryPlugin({
  dsn: "https://sentry.io/welcome/xyz",
});

Aside from Toucan, Cloudflare has also has a Sentry integration that leverages Tail Workers, out-of-band processes that receive information from the main process worker that can then asynchronously flush data to different sources.

Drawbacks of prior art

For it's purpose, Toucan works very well. There are few drawbacks in just using Toucan directly for your applications. The primary hurdles with Toucan are with it's developer experience.

1. You have to explicitly instantiate Toucan in your worker's fetch, which can be a lot of boilerplate code.
2. Toucan's APIs are designed for error monitoring, which means it's hard to get Sentry's tracing (performance), crons, and metrics functionality working with it.
3. The cloudflare pages plugin which uses Toucan needs to be explicitly added via middleware, which means it doesn't work well with the patterns of our meta-framework SDKs (@sentry/remix, @sentry/sveltekit).
4. Toucan's public API doesn't support all the SDK's options/public API
5. Toucan sends events in-process, so it forces the worker to stay-alive to send the event, which increases function duration

The tail worker has more drawbacks.

1. Sourcemaps are hard to set up, some users say they don't work properly
2. You have less control over the Sentry setup, so you don't have all the configuration exposed
3. The tail-worker powered integration only supports errors

@sentry/cloudflare

We are building @sentry/cloudflare as an attempt to unify the Sentry experience with Cloudflare, and support workers and pages accordingly. We would also like to add specialized instrumentation for Cloudflare's different products that connect to workers via bindings (D1, R2, queues, etc.) and support all the handlers that workers have (alarm, queue, scheduled, etc.).

Because we require tracing support as top-of-mind priority, AsyncLocalStorage support is a requirement of the SDK. This means that (for now) compatibility_flags = ["nodejs_compat"] or compatibility_flags = ["nodejs_als"] is required to be set to use the SDK.

Using @sentry/cloudflare with standalone worker

When just using @sentry/cloudflare with a standalone worker, you do something like so:

import * as Sentry from "@sentry/cloudflare";
import { handler } from "./handler";

type Env = {
  SENTRY_DSN: string;
};

export default withSentry(
  (env, context): Sentry.Options => ({
    dsn: env.SENTRY_DSN,
    tracesSampleRate: 1.0,
    environment: ENVIRONMENT,
    release: env.CF_VERSION_METADATA.versionId,
  }),
  {
    async fetch(request, env, context): Promise<Response> {
      try {
        handler();
        return new Response("Hello!");
      } catch (e) {
        Sentry.captureException(e);
        return new Response("Something went wrong! Team has been notified.", {
          status: 500,
        });
      }
    },
  },
) satisfies ExportedHandler<Env>;

withSentry is a helper function that wraps your worker. It takes two arguments. The first is identical to Sentry.init, and represents the sentry instance created for each handler instantiation. This needs to be done because workers can change their bindings (env) without re-deploying the entire worker, so a top-level Sentry.init call would become stale.

Under the hood this would use ctx.waitUntil to flush events, which means it has the same drawback as Toucan to keep the worker alive the entire execution time.

Using @sentry/cloudflare with cloudflare pages

Given there is a recommended way to publish pages plugins, we would format this the same way @cloudflare/pages-plugin-sentry works.

// Need to use `@sentry/cloudflare/pages` to match plugin formatting
import * as Sentry from "@sentry/cloudflare/pages";

export const onRequest = (context) => {
  return Sentry.sentryPagesPlugin({
    dsn: context.env.SENTRY_DSN,
    tracesSampleRate: 1.0,
    environment: ENVIRONMENT,
    release: context.env.CF_VERSION_METADATA.versionId,
  })(context);
};

Under the hood this would use @sentry/cloudflare.

Using @sentry/cloudflare with meta-framework SDKs

Given we re-export everything from @sentry/cloudflare/pages, we can easily use this in the metaframeworks and re-export as necessary. To start though, we'll probably recommend installing a separate package.

@sentry/cloudflare integrations

Once we have the worker and pages setup ready, we can start building out integrations for all of the different cloudflare products. We can create spans for R2/D1/Analytics Engine, automatically instrument cloudflare crons, and more!

Next Steps

After this has been initially released, there are a variety of improvements we can look to make.

1. We probably want to move @sentry/cloudflare to completely leverage tail workers and make sure it never flushes on the main process.
2. We can improve sourcemaps experience - Cloudflare adopting debug IDs would go a long way here.
3. Cloudflare's version bindings are relatively new, we can definitely improve the overall experience here
4. We can expand the existing Sentry Cloudflare integration to
   a. automatically create/manage Sentry projects
   b. setup sourcemaps uploading
   c. Bi-directionally link cloudflare w/ Sentry and let folks go back and forth from the different dashboards.
5. Cloudflare workers are an amazing tool for people to set up tunneling with Sentry. We should invest into this.