Sentry for Pi Durable (Cloudflare)
Learn how to send Pi Durable agent runs, model requests, tool calls, and errors to Sentry from Cloudflare Durable Objects.
Pi Durable is Earendil's durable agent harness, built on the same foundations as the Pi coding agent. This guide sets up the Sentry SDK in a Worker that runs Pi Durable in a Durable Object, for example through the Agents SDK PiHarness, so agent runs, model requests, tool calls, and errors flow into Sentry Agent Tracing.
Pi Durable is experimental, and its API can change between releases. The Sentry integration supports @earendil-works/pi-durable >=1.0.0 <2.0.0 and requires JavaScript SDK version 11.6.0 or later.
Before you begin, you need:
- A Sentry account and project. The project's DSN tells the SDK where to send data.
- A Worker using
@earendil-works/pi-durableversion1.0.0or later, built with Vite and@cloudflare/vite-plugin. To host Pi Durable withPiHarness, you need the Agents SDK (agents) version0.26.0or later. @sentry/cloudflareversion11.6.0or later.
Choose the features you want to configure, and this guide will show you how:
Install the Sentry Cloudflare SDK:
npm install @sentry/cloudflare@^11.6.0
npm install @sentry/cloudflare@^11.6.0
yarn add @sentry/cloudflare@^11.6.0
pnpm add @sentry/cloudflare@^11.6.0
Add the Sentry Vite plugin to your Vite config:
vite.config.mtsimport { cloudflare } from "@cloudflare/vite-plugin";
import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [cloudflare(), sentryCloudflareVitePlugin()],
});
import { cloudflare } from "@cloudflare/vite-plugin";
import { sentryCloudflareVitePlugin } from "@sentry/cloudflare/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [cloudflare(), sentryCloudflareVitePlugin()],
});
The plugin instruments Harness.open() at build time, so every Harness your Worker opens is traced. It also wraps your Worker entry, your Durable Object classes, and your Agents SDK classes with Sentry, so Sentry.init() runs in the Durable Object that hosts Pi Durable without any changes to your code.
Create an instrument.server.ts file next to your Worker entry (the file named in Wrangler's main). The plugin picks it up by convention and uses its default export as the Sentry options:
src/instrument.server.tsimport { defineCloudflareOptions } from "@sentry/cloudflare";
export default defineCloudflareOptions((env: Env) => ({
dsn: "___PUBLIC_DSN___",
// ___PRODUCT_OPTION_START___ performance
// Set tracesSampleRate to 1.0 to capture 100%
// of spans for tracing.
// We recommend adjusting this value in production.
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
}));
import { defineCloudflareOptions } from "@sentry/cloudflare";
export default defineCloudflareOptions((env: Env) => ({
dsn: "___PUBLIC_DSN___",
// ___PRODUCT_OPTION_START___ performance
// Set tracesSampleRate to 1.0 to capture 100%
// of spans for tracing.
// We recommend adjusting this value in production.
tracesSampleRate: 1.0,
// ___PRODUCT_OPTION_END___ performance
}));
Enable Node.js compatibility in your Wrangler config so the SDK can run on Workers:
wrangler.tomlmain = "src/index.ts"
compatibility_flags = ["nodejs_compat"]
main = "src/index.ts"
compatibility_flags = ["nodejs_compat"]
Your Pi Durable code doesn't change. For example, an Agents SDK class that hosts Pi Durable with PiHarness is traced as is:
src/assistant.tsimport { createModels } from "@earendil-works/pi-ai/models";
import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { Agent } from "agents";
import { PiHarness } from "agents/harness/pi";
export class Assistant extends Agent<Env> {
registry = createRegistry();
harness = new PiHarness({
harness: ({ storage, context }) => {
// pi-ai reads provider keys from `process.env` by default, so hand over the Worker's secret.
const models = createModels({
authContext: {
env: async (name) =>
name === "OPENAI_API_KEY"
? this.env.OPENAI_API_KEY
: undefined,
fileExists: async () => false,
},
});
models.setProvider(openaiProvider());
return Harness.open(
storage,
{ models, registry: this.registry },
context,
);
},
defaults: { model: { provider: "openai", id: "gpt-6.1-sol" } },
});
constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env);
this.lifecycle.use(this.harness);
}
}
import { createModels } from "@earendil-works/pi-ai/models";
import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
import { createRegistry, Harness } from "@earendil-works/pi-durable";
import { Agent } from "agents";
import { PiHarness } from "agents/harness/pi";
export class Assistant extends Agent<Env> {
registry = createRegistry();
harness = new PiHarness({
harness: ({ storage, context }) => {
// pi-ai reads provider keys from `process.env` by default, so hand over the Worker's secret.
const models = createModels({
authContext: {
env: async (name) =>
name === "OPENAI_API_KEY"
? this.env.OPENAI_API_KEY
: undefined,
fileExists: async () => false,
},
});
models.setProvider(openaiProvider());
return Harness.open(
storage,
{ models, registry: this.registry },
context,
);
},
defaults: { model: { provider: "openai", id: "gpt-6.1-sol" } },
});
constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env);
this.lifecycle.use(this.harness);
}
}
With this setup, Sentry captures errors thrown by your tools and extensions, and AI spans for every run (agent runs, model requests, tool calls, token usage, and latency). Manual spans you start inside a tool nest under that tool's span. Prompts and model outputs are recorded on your AI spans by default.
To review what's captured and turn recording of prompts and responses off, see Control the Data You Send to Sentry below.
By default, the SDK sends the inputs and outputs of your model requests and tool calls, such as prompts, responses, and tool arguments. This will give you rich debugging context. Review the data your agent handles before you deploy to production.
The SDK always filters sensitive values whose keys match a built-in denylist, such as auth or password, and sends [Filtered] instead.
To send less data, turn off the categories you don't need in the dataCollection option:
src/instrument.server.tsimport { defineCloudflareOptions } from "@sentry/cloudflare";
export default defineCloudflareOptions((env: Env) => ({
dsn: "___PUBLIC_DSN___",
dataCollection: {
genAI: { inputs: false, outputs: false },
},
}));
import { defineCloudflareOptions } from "@sentry/cloudflare";
export default defineCloudflareOptions((env: Env) => ({
dsn: "___PUBLIC_DSN___",
dataCollection: {
genAI: { inputs: false, outputs: false },
},
}));
For the full list of categories and their defaults, see the dataCollection options.
Sentry groups the runs of a Pi Durable conversation into a single Conversation automatically — there's no Sentry-specific setup. The SDK sets gen_ai.conversation.id on the agent, model, and tool spans of every run to <harness id>:<conversation id>.
Pi Durable numbers conversations per storage, starting from 1, so the SDK prefixes a random id for each opened Harness to keep root conversations from different storages apart. This id changes when the Harness reopens, for example after a process restart or after a Durable Object restarts. Runs from before and after a restart then show up as separate conversations in Sentry.
A subagent runs in a conversation of its own. Its first run nests under the tool call that created it, so the subagent shows up inside the parent's trace.
Submit a message to one of your conversations, ideally one that calls a tool. Then open Explore → Agents in Sentry. Select the conversation to open its detail. The timeline shows the agent run, model requests, tool calls, token usage, latency, and any errors your tools threw.
If no data appears, confirm that:
- The
dsnbelongs to the Sentry project you're viewing. tracesSampleRateis greater than0.- Your app completed at least one run after you added the setup.
- No AI spans at all. Confirm
sentryCloudflareVitePlugin()is in your Vite config and that you build and run the Worker through Vite. A Worker you deploy withwranglerdirectly, without the plugin, doesn't get the build-time instrumentation ofHarness.open(). - Every restart of the Durable Object starts a new conversation in Sentry. This is expected for now. See Link Conversations.
- Track AI agent spend with dashboards and alerts: build a dashboard for cost, tokens, models, and conversations.
- Pi Durable's README: conversations, tasks, extensions, and storage, from the Pi side.
- Use the appropriate JavaScript framework guide for application monitoring in a separate frontend or service.
@sentry/cloudflare:>=11.6.0@earendil-works/pi-durable:>=1.0.0 <2.0.0agents:>=0.26.0, when you host Pi Durable withPiHarness
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").