feat(v10/cloudflare): Filter framework-internal Durable Object storage spans

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');

dev-packages/e2e-tests/test-applications/cloudflare-agent/tests/callable.test.ts

@@ -9,6 +9,16 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  );
  });
 
+ // The greet() call goes over the websocket, so its storage spans land in a webSocketMessage
+ // transaction. Filter for the one carrying our put span — control messages produce their own
+ // webSocketMessage transactions without storage spans.
+ const storageTransactionPromise = waitForTransaction('cloudflare-agent', transactionEvent => {
+ return (
+ transactionEvent.transaction === 'webSocketMessage' &&
+ (transactionEvent.spans ?? []).some(span => span.description === 'durable_object_storage_put')
+ );
+ });
+
  await page.goto(baseURL!);
 
  await expect(page.getByText('Connected')).toBeVisible();
@@ -32,24 +42,7 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  culture: { timezone: expect.any(String) },
  runtime: { name: 'cloudflare' },
  },
- spans: expect.arrayContaining([
- expect.objectContaining({
- data: {
- 'db.operation.name': 'get',
- 'db.system.name': 'cloudflare.durable_object.storage',
- 'sentry.op': 'db',
- 'sentry.origin': 'auto.db.cloudflare.durable_object',
- },
- description: 'durable_object_storage_get',
- op: 'db',
- origin: 'auto.db.cloudflare.durable_object',
- parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
- span_id: expect.stringMatching(/[a-f0-9]{16}/),
- start_timestamp: expect.any(Number),
- timestamp: expect.any(Number),
- trace_id: expect.stringMatching(/[a-f0-9]{32}/),
- }),
- ]),
+ spans: [],
  start_timestamp: expect.any(Number),
  timestamp: expect.any(Number),
  transaction: 'GET /agents/my-agent/user-123',
@@ -72,4 +65,65 @@ test('@callable() methods work correctly with Sentry instrumentDurableObjectWith
  packages: expect.any(Array),
  },
  });
+
+ // greet() touches 6 storage keys: 2 user ops + 3 framework-internal keys (cf_, __ps_, /) that
+ // must be filtered + 1 allowlisted cf_ key. Spans carry no key attribute, so filtering can only
+ // be verified by count — exactly these 3 storage spans (in execution order) should survive, and
+ // any framework-internal span leaking through shows up as an extra entry here.
+ const storageTransaction = await storageTransactionPromise;
+
+ const storageSpans = (storageTransaction.spans ?? []).filter(
+ span => span.origin === 'auto.db.cloudflare.durable_object',
+ );
+
+ expect(storageSpans).toEqual([
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'put',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ expect.objectContaining({
+ data: {
+ 'db.operation.name': 'get',
+ 'db.system.name': 'cloudflare.durable_object.storage',
+ 'sentry.op': 'db',
+ 'sentry.origin': 'auto.db.cloudflare.durable_object',
+ },
+ description: 'durable_object_storage_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ span_id: expect.stringMatching(/[a-f0-9]{16}/),
+ start_timestamp: expect.any(Number),
+ timestamp: expect.any(Number),
+ trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+ }),
+ ]);
 });

dev-packages/e2e-tests/test-applications/cloudflare-agent/worker/index.ts

@@ -4,6 +4,18 @@ import { routeAgentRequest, Agent, callable } from 'agents';
 class MyBaseAgent extends Agent {
  @callable()
  async greet(name: string): Promise<string> {
+ // User keys — instrumented, spans expected
+ await this.ctx.storage.put('test', 'any value');
+ await this.ctx.storage.get('test');
+
+ // Framework-internal keys (agents/partyserver/MCP OAuth conventions) — filtered, no spans expected
+ await this.ctx.storage.put('cf_e2e_internal', 'bookkeeping');
+ await this.ctx.storage.get('__ps_name');
+ await this.ctx.storage.get('/oauth/client/token');
+
+ // Allowlisted cf_ key — span expected
+ await this.ctx.storage.get('cf_user_key');
+
  return `Hello, ${name}!`;
  }
 }
@@ -14,6 +26,7 @@ export const MyAgent = Sentry.instrumentDurableObjectWithSentry(
  tunnel: `http://localhost:3031/`,
  tracesSampleRate: 1,
  enableRpcTracePropagation: true,
+ durableObjectStorageSpanAllowlist: ['cf_user_key'],
  }),
  MyBaseAgent,
 );

packages/cloudflare/src/client.ts

@@ -240,6 +240,31 @@ interface BaseCloudflareOptions {
  */
  durableObjectSqlSpanAllowlist?: Array<string | RegExp>;
 
+ /**
+ * KV keys that should stay instrumented even though they match a reserved prefix used by Durable
+ * Object frameworks (`agents`, `partyserver`, ...) for their internal storage entries.
+ *
+ * By default, KV reads/writes (`get`, `put`, `delete`, `list`) of `cf_`- or `__ps_`-prefixed keys
+ * are treated as framework noise and no `durable_object_storage_*` span is created for them,
+ * mirroring how `cf_`-prefixed SQL tables are handled (see {@link durableObjectSqlSpanAllowlist}).
+ * If one of your own keys happens to use such a prefix, add it here to opt it back into
+ * instrumentation. Strings must match exactly, while regular expressions give you prefix/pattern
+ * matching.
+ *
+ * @default []
+ * @example
+ * ```ts
+ * export default Sentry.withSentry(
+ * (env) => ({
+ * dsn: env.SENTRY_DSN,
+ * durableObjectStorageSpanAllowlist: ['cf_my_key', /^cf_reports_/],
+ * }),
+ * handler,
+ * );
+ * ```
+ */
+ durableObjectStorageSpanAllowlist?: Array<string | RegExp>;
+
  /**
  * @deprecated Use `enableRpcTracePropagation` instead. This option will be removed in a future major version.
  *

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,5 +1,7 @@
 import type { DurableObjectStorage, SyncKvStorage, SqlStorage } from '@cloudflare/workers-types';
-import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import { getClient, isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+import type { CloudflareClientOptions } from '../client';
+import { getStorageKeys, targetsCloudflareInternalKey } from '../utils/internalStorageKey';
 import { storeSpanContext } from '../utils/traceLinks';
 import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 import { instrumentSqlStorage } from './instrumentSqlStorage';
@@ -55,6 +57,15 @@ export function instrumentDurableObjectStorage(
  }
 
  return function (this: unknown, ...args: unknown[]) {
+ // KV entries managed by the DO framework itself (agents/partyserver state) are bookkeeping
+ // rather than user work — skip the span, mirroring how `cf_` SQL tables are treated.
+ const allowlist = (getClient()?.getOptions() as CloudflareClientOptions | undefined)
+ ?.durableObjectStorageSpanAllowlist;
+ const keys = getStorageKeys(methodName, args);
+ if (keys && keys.length > 0 && keys.every(key => targetsCloudflareInternalKey(key, allowlist))) {
+ return (original as (...a: unknown[]) => unknown).apply(target, args);
+ }
+
  return startSpan(
  {
  // Use underscore naming to match Cloudflare's native instrumentation (e.g., "durable_object_storage_get")

packages/cloudflare/src/utils/internalStorageKey.ts

@@ -0,0 +1,75 @@
+import { stringMatchesSomePattern } from '@sentry/core';
+
+/**
+ * Cloudflare frameworks that build on Durable Objects (`agents`, `partyserver`, ...) also manage
+ * their own internal KV entries alongside their internal SQLite tables, namespaced with a reserved
+ * prefix — e.g. `cf_agents_state`, `cf_agents_mcp_servers`, `__ps_name`. Reads/writes of these
+ * (message persistence, MCP connection bookkeeping, name hydration) are framework implementation
+ * details that otherwise flood traces with dozens of zero-signal `durable_object_storage_*` spans
+ * per request, so we match the reserved prefixes rather than an enumerated list. This mirrors the
+ * `cf_` convention used for internal SQL tables (see `targetsCloudflareInternalTable`).
+ *
+ * The prefixes are a reserved convention for framework-managed entries, so user keys should not use
+ * them. In case a user key does collide, the `durableObjectStorageSpanAllowlist` option lets them
+ * opt those keys back into instrumentation.
+ */
+export function targetsCloudflareInternalKey(key: string | undefined, allowlist?: Array<string | RegExp>): boolean {
+ if (!key) {
+ return false;
+ }
+
+ // Framework-managed KV namespaces:
+ // - `cf_` — agents / ai-chat internal state (mirrors the internal SQL table convention)
+ // - `__ps_` — partyserver internals (e.g. `__ps_name`)
+ // - `/` — MCP OAuth client state (`/<clientName>/<serverId>/{token,client_info,state,...}`),
+ // read on every MCP tool call. User keys on an Agent rarely use a leading slash; if one does,
+ // the allowlist opts it back in.
+ const isFrameworkKey = key.startsWith('cf_') || key.startsWith('__ps_') || key.startsWith('/');
+ if (!isFrameworkKey) {
+ return false;
+ }
+
+ // A key on the allowlist is treated as a user key and stays instrumented, even though it matches
+ // a reserved prefix.
+ return !allowlist?.length || !stringMatchesSomePattern(key, allowlist, true);
+}
+
+/**
+ * Extracts the KV keys a Durable Object storage call targets, so the caller can decide whether the
+ * operation only touches framework-internal entries. Returns `undefined` when the keys can't be
+ * determined from the arguments (e.g. `list()` without a prefix), in which case the call is treated
+ * as user work and stays instrumented.
+ */
+export function getStorageKeys(methodName: string, args: unknown[]): string[] | undefined {
+ const [first] = args;
+
+ if (methodName === 'get' || methodName === 'delete') {
+ // get(key) / get(keys[]) / delete(key) / delete(keys[])
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (Array.isArray(first)) {
+ return first.filter((k): k is string => typeof k === 'string');
+ }
+ return undefined;
+ }
+
+ if (methodName === 'put') {
+ // put(key, value) or put({ key: value, ... })
+ if (typeof first === 'string') {
+ return [first];
+ }
+ if (first && typeof first === 'object' && !Array.isArray(first)) {
+ return Object.keys(first);
+ }
+ return undefined;
+ }
+
+ if (methodName === 'list') {
+ // list({ prefix })
+ const prefix = first && typeof first === 'object' ? (first as { prefix?: unknown }).prefix : undefined;
+ return typeof prefix === 'string' ? [prefix] : undefined;
+ }
+
+ return undefined;
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -324,6 +324,80 @@ describe('instrumentDurableObjectStorage', () => {
  );
  });
 
+ describe('framework-internal KV keys', () => {
+ it('does not create a span for a cf_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('cf_agents_state');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a __ps_-prefixed get', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('__ps_name');
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed put with object entries', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.put({ cf_agents_a: 1, cf_agents_b: 2 });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a cf_-prefixed delete with an array of keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.delete(['cf_agents_a', 'cf_agents_b']);
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('does not create a span for a list with a cf_ prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list({ prefix: 'cf_agents_' });
+
+ expect(startSpanSpy).not.toHaveBeenCalled();
+ });
+
+ it('still creates a span when a batch mixes framework and user keys', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get(['cf_agents_state', 'myKey']);
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a list without a prefix', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.list();
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+
+ it('still creates a span for a user key', async () => {
+ const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');
+ const instrumented = instrumentDurableObjectStorage(createMockStorage());
+
+ await instrumented.get('myKey');
+
+ expect(startSpanSpy).toHaveBeenCalled();
+ });
+ });
+
  describe('non-instrumented methods', () => {
  it('does not instrument deleteAll, sync, transaction', async () => {
  const startSpanSpy = vi.spyOn(sentryCore, 'startSpan');