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 Hub 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 @sentry/integrations package, and you can also write your own! To ensure an integration will work properly in toucan-js, it must:

• not use global getCurrentHub from @sentry/core.
• 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/integrations are re-exported from toucan-js:

• Dedupe
• ExtraErrorData
• RewriteFrames
• SessionTiming
• Transaction

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

• LinkedErrors
• RequestData

Custom integration example:

import { Toucan } from 'toucan-js';
import { RewriteFrames } from '@sentry/integrations';

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: [new RewriteFrames({ 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).