Sentry Cloudflare Workers SDK

[AbhiPrasad]

ref #2484
ref #5611

Let's add some 1st class cloudflare workers support (finally)!

We've had https://github.com/robertcepa/toucan-js for a while that has worked great, but doesn't match our unified API and doesn't have full support for performance, cron monitoring, and more.

First we can start off by making a basic package, @sentry/cloudflare-workers

### Initial
- [ ] https://github.com/getsentry/sentry-javascript/issues/12685
- [ ] https://github.com/getsentry/sentry-javascript/pull/12953
- [ ] https://github.com/getsentry/sentry-javascript/pull/13025
- [ ] https://github.com/getsentry/sentry-javascript/pull/13087
- [ ] https://github.com/getsentry/sentry-javascript/pull/13096

### After First Release
- [ ] https://github.com/getsentry/sentry-javascript/issues/13111
- [ ] https://github.com/getsentry/platformicons/issues/173
- [ ] https://github.com/getsentry/sentry-release-registry/pull/164
- [ ] https://github.com/getsentry/sentry-javascript/pull/13206
- [ ] Add wizard command to setup cloudflare workers sdk
- [ ] Add cloudflare workers to sentry onboarding
- [ ] Ensure distributed tracing between cloudflare workers
- [ ] Publish docs for cloudflare workers package
- [ ] Add version metadata https://developers.cloudflare.com/workers/runtime-apis/bindings/version-metadata/

Once the SDK is in a good state we can think about better instrumentation for the different bindings that cloudflare workers exposes. Top of mind is:

### Bindings support
- [ ] https://github.com/getsentry/sentry-javascript/issues/13141
- [ ] Add cloudflare queues instrumentation https://developers.cloudflare.com/queues/configuration/javascript-apis/
- [ ] Add r2 instrumentation https://developers.cloudflare.com/r2/api/workers/workers-api-reference/
- [ ] Add kv instrumentation https://developers.cloudflare.com/kv/
- [ ] Add durable objects instrumentation

At the same time we should make sure that we add support for our metaframeworks to use the Cloudflare workers SDK

### Support metaframeworks
- [ ] https://github.com/getsentry/sentry-javascript/pull/13123
- [ ] https://github.com/getsentry/sentry-javascript/issues/5610
- [ ] https://github.com/getsentry/sentry-javascript/issues/8291
- [ ] https://github.com/getsentry/sentry-javascript/issues/11920
- [ ] Astro
- [ ] Nuxt
- [ ] SolidStart
- [ ] Next.js (https://github.com/getsentry/sentry-javascript/issues/11920)

[AbhiPrasad]

Initial thinking of the general API.

We're probably only going to support ES modules syntax.

Current toucan requires you to always instantiate new Toucan. Ideally we can avoid this by exposing a helper that wraps export default obj from the entry point.

It would probably automatically try to read env.SENTRY_DSN to get the sentry dsn.

export default withSentry({ beforeSend }, {
  async fetch(request, env, ctx) {
    return new Response('Hello World!');
  },
});

For further customization, you can take a function withSentryHandler that isolates sentry to the specific handler you care about. This allows you to override how sentry is initialized for that specific handler without

export default withSentry({ tracesSampleRate: 1.0 }, {
  async fetch: withSentryFetchHandler((init) => (request, env, ctx) => {
    const client = init({ tracesSampleRate: 0.5, request, env, ctx });
    // do whatever you want with client
    return new Response('Hello World!');
  }),
});

With the withSentry API's you'll need to have compatibility_flags = [ "nodejs_als" ] on in your wrangler.toml, otherwise you risk request bleeding (we require AsyncLocalStorage to do isolation).

If you don't want any node_compat, we can't do the global withSentry magic function, so you'll need to manually create a client.

import * as Sentry from '@sentry/cloudflare-workers';

export default {
  async fetch(request, env, ctx) {
    const client = new Sentry.CloudflareWorkersClient();
    const scope = new Sentry.Scope();
    scope.setClient(client);

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

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

Unfortunately performance is not active here because the parent child relationship is wrong, so maybe we gate performance behind requiring compatibility_flags = [ "nodejs_als" ]. The same also applies for automatic instrumentation adding breadcrumbs, we risk attaching to the wrong request. All automatic instrumentation (like automatically instrumenting d1 or r2 bindings) might be turned off if we cannot access asynclocalstorage.

We also need to add support for Version metadata binding - I'm imagining this is easiest to expose as an init config where you tell us what environmental variable to access for this info, and we automatically update releases and such.

[AbhiPrasad]

I'm throwing around some experiments in https://github.com/AbhiPrasad/sentry-cloudflare-test/tree/main/examples

[ChristianJacobsen]

Hey @AbhiPrasad,

by adding support for Cloudflare Workers, do you also plan to add support for Cloudflare Pages? I know CF are working on unifying the two platforms, but it's still "a bit out there" (at least according to their Discord) and there are some subtle differences to how they work.

Anyways, awesome that you are doing this! 😄 I've been looking forward to official support for a long time!

[AbhiPrasad]

by adding support for Cloudflare Workers, do you also plan to add support for Cloudflare Pages

Yes for sure, this is def part of it because this is how all the metaframework integrations work. Let me make it more clear in the tracking issue, and also add some example of API design for that too.

[F0rce]

[...] how all the Metaframework integrations work

Does this include Astro? 👀 I know there is already an @sentry/astro integration (which is great), but the Cloudflare adapter (and Astro in SSR mode) is still not supported with it.

Like everyone else said, im also super happy that this is being worked on :)