Cloudflare Workers client for Sentry
npm install 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.
This SDK provides all options and methods of ScopeClass and additionally:
| 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. |
#### Transport options
On top of base transportOptions you can pass additional configuration:
| Option | Type | Description |
| ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| headers | Record
| 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. |
- 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.
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
``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
`
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).