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:

$3

| 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. |

$3

#### Transport options

On top of base transportOptions you can pass additional configuration:

| Option | Type | Description |
| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| headers | Record | 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. |

$3

- 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

$3

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

type Env = {
SENTRY_DSN: string;
};

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

...
},
} as ExportedHandler;
`

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).