Cloudflare Workers SDK

Use @squasher-ai/edge in Cloudflare Workers. It wraps your fetch, queue, and scheduled handlers, and it sends the events of each invocation after the response. This page is tested with version 0.4.0.

What the SDK captures

Source	Captured
Errors thrown by `fetch`, `queue`, `scheduled`	Yes, when you wrap the handlers in `withSquasher`.
Each invocation	Yes: one event with the duration and the status, also on success.
Errors that you catch	Yes, when you call `captureError`.
Spans, logs, and metrics	Yes, when you call `span`, `log`, and `recordMetric`.
Durable Object methods and alarms	Only inside `runWithSquasher`.
Pages Functions (`onRequest`)	No. `withSquasher` wraps only Worker handlers.

Install the SDK

npm install @squasher-ai/edge

The SDK needs the nodejs_compat compatibility flag, for AsyncLocalStorage:

wrangler.jsonc

{
  "compatibility_flags": ["nodejs_compat"],
}

Save your ingest key and project ID as Worker secrets. To get both values, see Create an ingest key.

npx wrangler secret put SQUASHER_API_KEY
npx wrangler secret put SQUASHER_PROJECT_ID

For wrangler dev, put the same two values in .dev.vars.

Wrap the Worker

Pass withSquasher a function that reads the configuration from env, and your handlers.

src/index.ts

import { withSquasher } from "@squasher-ai/edge";

interface Env {
  SQUASHER_API_KEY: string;
  SQUASHER_PROJECT_ID: string;
}

export default withSquasher<Env>(
  (env) => ({
    apiKey: env.SQUASHER_API_KEY,
    projectId: env.SQUASHER_PROJECT_ID,
    environment: "production",
    resourceAttributes: { "service.name": "checkout-worker" },
  }),
  {
    async fetch(request, env, ctx) {
      return new Response("OK");
    },
  },
);

For each invocation, the wrapper makes a new client. When the handler throws, it sends an error event and throws the error again. Squasher names the issue after the handler, for example edge GET /checkout or edge queue orders, and keeps the error message and the stack trace on the event. Numbers and UUIDs in the path become :id. Set environment to production in production: automatic AI triage runs only on issues from that environment. When you do not set service.name, the SDK uses edge-worker.

Capture errors that you catch

Inside a wrapped handler, call captureError. It uses the client of the current invocation.

src/index.ts

import { captureError } from "@squasher-ai/edge";

try {
  await chargeCard(order);
} catch (error) {
  captureError(error as Error, { orderId: order.id });
  return new Response("Payment failed", { status: 502 });
}

The issue gets the error message as its title. setUser, setTag, and captureMessage also work inside a wrapped handler.

Add spans, logs, and metrics

src/index.ts

import { log, recordMetric, span } from "@squasher-ai/edge";

const rows = await span("db.query", { kind: "client", attrs: { "db.system.name": "d1" } }, () =>
  env.DB.prepare("SELECT * FROM orders").all(),
);
log.info("orders loaded", { count: rows.results.length });
recordMetric("orders.loaded", rows.results.length, { type: "counter" });

Spans that start inside another span become its children. Logs and metrics get the trace ID of the active span. log.error accepts an Error, and then it also sends the stack trace. When a fetch request has a valid W3C traceparent header, the invocation joins that trace: it uses the caller’s trace ID and becomes a child of the caller’s span. A missing, malformed, or all-zero header starts a new trace. To continue the trace in a Worker you call, set the header from the active span:

import { getActiveSpan } from "@squasher-ai/edge";

const active = getActiveSpan();
const headers = new Headers(request.headers);
if (active) headers.set("traceparent", `00-${active.traceId}-${active.spanId}-01`);
const response = await env.BACKEND.fetch(new Request(request, { headers }));

Use the SDK in Durable Objects

withSquasher covers only the Worker handlers. In a Durable Object method or alarm, run the code inside runWithSquasher, and put the work in a span. When the function throws, span sends an error event with the error message and throws the error again. runWithSquasher sends the events when the function ends.

src/counter.ts

import { DurableObject } from "cloudflare:workers";
import { runWithSquasher, span } from "@squasher-ai/edge";

export class Counter extends DurableObject<Env> {
  async alarm() {
    await runWithSquasher(
      { apiKey: this.env.SQUASHER_API_KEY, projectId: this.env.SQUASHER_PROJECT_ID },
      () => span("counter.alarm", () => this.flushCounts()),
    );
  }
}

Send a test error

Add a route that throws, run npx wrangler dev, and open /squasher-test once:

src/index.ts

async fetch(request) {
  if (new URL(request.url).pathname === "/squasher-test") {
    throw new Error("Squasher test error");
  }
  return new Response("OK");
},

Then select Issues in the sidebar of your project. The issue is named edge GET /squasher-test. If it does not appear, see Troubleshooting.

Options

Option	Default	Description
`apiKey`	Required	Your ingest key. An empty string turns the SDK off: it sends nothing.
`projectId`	Required	Your project ID.
`environment`	None	The environment name, for example `production`.
`release`	None	The release name, for example the git commit SHA.
`resourceAttributes`	None	Fields for every event, for example `{ "service.name": "checkout-worker" }`.
`beforeSend`	None	A function that gets each event before it is sent. Return the event to send it, or `null` to drop it.
`sampling`	Send all	Rates from 0 to 1: `successRate`, `errorRate`, `slowRate`, and `slowThresholdMs` (1000).
`maxBreadcrumbs`	`50`	Breadcrumbs kept in memory. Squasher does not store them.
`debug`	`false`	Log SDK activity to the console. Debug mode does not sample.
`endpoint`	`https://ingest.squasher.ai`	The ingest URL.

Each invocation sends at least one event. To store fewer events for successful invocations, set sampling: { successRate: 0.1 }. Errors are kept at the default errorRate of 1.

Limits

The SDK keeps at most 30 events for each invocation. It drops the events after the 30th.
The SDK retries a failed send at most 2 times.
Cloudflare Workers advance the clock only after I/O, so a span of CPU-only work shows 0 ms.
The SDK sends breadcrumbs, but Squasher does not store them.
If you bundle your Worker, stack traces point at the bundle. Upload source maps for the release so the issue page shows the original files.

Give the setup to a coding agent

Copy this prompt into your coding agent to install the SDK the same way:

Install @squasher-ai/edge in this Cloudflare Worker. Add "nodejs_compat" to compatibility_flags in the
wrangler config. Store SQUASHER_API_KEY and SQUASHER_PROJECT_ID as Worker secrets and in .dev.vars.
Wrap the default export with withSquasher((env) => ({ apiKey: env.SQUASHER_API_KEY, projectId:
env.SQUASHER_PROJECT_ID, environment: "production" }), handlers). Use captureError for caught errors.
In Durable Objects, use runWithSquasher and span. Verify with a route that throws
new Error("Squasher test error") under wrangler dev.

Next steps

Cloudflare Logpush

Send Worker logs to the same project without code.

Pino transport

Use the same spans, logs, and metrics in Node.js.

Read AI triage

Learn what the triage summary tells you.

Troubleshooting

Find out why an event does not appear.

Get started

Guides

Cloudflare Workers SDK

What the SDK captures

Install the SDK

Wrap the Worker

Capture errors that you catch

Add spans, logs, and metrics

Use the SDK in Durable Objects

Send a test error

Options

Limits

Give the setup to a coding agent

Next steps

Cloudflare Logpush

Pino transport

Read AI triage

Troubleshooting

​What the SDK captures

​Install the SDK

​Wrap the Worker

​Capture errors that you catch

​Add spans, logs, and metrics

​Use the SDK in Durable Objects

​Send a test error

​Options

​Limits

​Give the setup to a coding agent

​Next steps

Cloudflare Logpush

Pino transport

Read AI triage

Troubleshooting

What the SDK captures

Install the SDK

Wrap the Worker

Capture errors that you catch

Add spans, logs, and metrics

Use the SDK in Durable Objects

Send a test error

Options

Limits

Give the setup to a coding agent

Next steps