toucan-js

toucan-js

Toucan is a Sentry client for Cloudflare Workers written in TypeScript.

• Reliable: In Cloudflare Workers isolate model, it is inadvisable to set or mutate global state within the event handler. Toucan was created with Workers' concurrent model in mind. No race-conditions, no undelivered logs, no nonsense metadata in Sentry.
• Flexible: Supports fetch and scheduled Workers, their .mjs equivalents, and Durable Objects.
• Familiar API: Follows Sentry unified API guidelines.

Features

This SDK provides all options and methods of ScopeClass and additionally:

Additional constructor options

Option	Type	Description
context	Context	This can be any object that contains waitUntil. It can be FetchEvent, ScheduledEvent, DurableObjectState, or .mjs context.
request	Request	If set, the SDK will send information about incoming requests to Sentry. By default, only the request method and request origin + pathname are sent. If you want to include more data, you need to use requestDataOptions option.
requestDataOptions	RequestDataOptions	Object containing allowlist for specific parts of request. Refer to sensitive data section below.

Constructor options overrides

Transport options

On top of base transportOptions you can pass additional configuration:

Option	Type	Description
headers	Record<string, string>	Custom headers passed to fetch.
fetcher	typeof fetch	Custom fetch function. This can be useful for tests or when the global fetch used by toucan-js doesn't satisfy your use-cases. Note that custom fetcher must conform to fetch interface.

Additional methods

• Toucan.setEnabled(enabled: boolean): void: Can be used to disable and again enable the SDK later in your code.
• Toucan.setRequestBody(body: unknown): void: Attaches request body to future events. body can be anything serializable.

Integrations

You can use custom integrations to enhance toucan-js as you would any other Sentry SDK. Some integrations are provided in various Sentry packages, and you can also write your own! To ensure an integration will work properly in toucan-js, it must:

• not enhance or wrap global runtime methods (such as console.log).
• not use runtime APIs that aren't available in Cloudflare Workers (NodeJS runtime functions, window object, etc...).

Supported integrations from @sentry/core are re-exported from toucan-js:

• dedupeIntegration
• extraErrorDataIntegration
• rewriteFramesIntegration
• sessionTimingIntegration

toucan-js also provides 2 integrations that are enabled by default, but are provided if you need to reconfigure them:

• linkedErrorsIntegration
• requestDataIntegration
• zodErrorsIntegration

Custom integration example:

import { Toucan, rewriteFramesIntegration } from 'toucan-js';

type Env = {
  SENTRY_DSN: string;
};

export default {
  async fetch(request, env, context): Promise<Response> {
    const sentry = new Toucan({
      dsn: env.SENTRY_DSN,
      context,
      request,
      integrations: [rewriteFramesIntegration({ root: '/' })],
    });

    ...
  },
} as ExportedHandler<Env>;

Sensitive data

By default, Toucan does not send any request data that might contain PII (Personally Identifiable Information) to Sentry.

This includes:

• request headers
• request cookies
• request search params
• request body
• user's IP address (read from CF-Connecting-Ip header)

You will need to explicitly allow these data using:

• allowedHeaders option (array of headers or Regex or boolean)
• allowedCookies option (array of cookies or Regex or boolean)
• allowedSearchParams option (array of search params or Regex or boolean)
• allowedIps option (array of search params or Regex or boolean)

These options are available on RequestData integration or requestDataOptions option (which is passed down to RequestData automatically).