feat(cloudflare): Instrument sync KV

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/index.ts

@@ -0,0 +1,51 @@
+import * as Sentry from '@sentry/cloudflare';
+import { DurableObject } from 'cloudflare:workers';
+
+interface Env {
+ SENTRY_DSN: string;
+ TEST_DURABLE_OBJECT: DurableObjectNamespace;
+}
+
+class SyncKvDurableObjectBase extends DurableObject<Env> {
+ public constructor(ctx: DurableObjectState, env: Env) {
+ super(ctx, env);
+ }
+
+ async fetch(): Promise<Response> {
+ this.ctx.storage.kv.put('test-key', { value: 'hello' });
+ const val = this.ctx.storage.kv.get('test-key');
+ const entries = [...this.ctx.storage.kv.list()];
+ const deleted = this.ctx.storage.kv.delete('test-key');
+
+ return Response.json({ get: val, listSize: entries.length, deleted });
+ }
+}
+
+export const TestDurableObject = Sentry.instrumentDurableObjectWithSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ SyncKvDurableObjectBase,
+);
+
+export default Sentry.withSentry(
+ (env: Env) => ({
+ dsn: env.SENTRY_DSN,
+ tracesSampleRate: 1.0,
+ }),
+ {
+ async fetch(request: Request, env: Env): Promise<Response> {
+ const url = new URL(request.url);
+
+ if (url.pathname === '/flush-marker') {
+ Sentry.captureMessage('flush-marker');
+ return new Response(JSON.stringify({ ok: true }), { headers: { 'Content-Type': 'application/json' } });
+ }
+
+ const id = env.TEST_DURABLE_OBJECT.idFromName('test');
+ const stub = env.TEST_DURABLE_OBJECT.get(id);
+ return stub.fetch(request);
+ },
+ } satisfies ExportedHandler<Env>,
+);

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/test.ts

@@ -0,0 +1,77 @@
+import type { Envelope } from '@sentry/core';
+import { expect, it } from 'vitest';
+import { SEMANTIC_ATTRIBUTE_SENTRY_OP, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
+import { createRunner } from '../../../runner';
+
+const flushMarkerMatcher = (envelope: Envelope): void => {
+ const [, items] = envelope;
+ const [itemHeader, itemBody] = items[0] as [{ type: string }, Record<string, unknown>];
+
+ expect(itemHeader.type).toBe('event');
+ expect(itemBody.message).toBe('flush-marker');
+};
+
+it('instruments sync KV operations on Durable Object storage', async ({ signal }) => {
+ const runner = createRunner(__dirname)
+ .expect(envelope => {
+ const transactionEvent = envelope[1]?.[0]?.[1];
+ const spans = transactionEvent?.spans ?? [];
+
+ expect(transactionEvent).toEqual(
+ expect.objectContaining({
+ type: 'transaction',
+ transaction: 'GET /',
+ }),
+ );
+
+ expect(spans).toHaveLength(4);
+ expect(spans).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_put',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'db',
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'put',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_get',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_list',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'list',
+ }),
+ }),
+ expect.objectContaining({
+ description: 'durable_object_storage_kv_delete',
+ op: 'db',
+ origin: 'auto.db.cloudflare.durable_object',
+ data: expect.objectContaining({
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'delete',
+ }),
+ }),
+ ]),
+ );
+ })
+ .expect(flushMarkerMatcher)
+ .start(signal);
+
+ await runner.makeRequest('get', '/');
+ await runner.makeRequest('get', '/flush-marker');
+ await runner.completed();
+});

dev-packages/cloudflare-integration-tests/suites/tracing/durableobject-sync-kv/wrangler.jsonc

@@ -0,0 +1,20 @@
+{
+ "name": "worker-name",
+ "main": "index.ts",
+ "compatibility_date": "2025-06-17",
+ "migrations": [
+ {
+ "new_sqlite_classes": ["TestDurableObject"],
+ "tag": "v1",
+ },
+ ],
+ "durable_objects": {
+ "bindings": [
+ {
+ "class_name": "TestDurableObject",
+ "name": "TEST_DURABLE_OBJECT",
+ },
+ ],
+ },
+ "compatibility_flags": ["nodejs_als"],
+}

packages/cloudflare/src/instrumentations/instrumentDurableObjectStorage.ts

@@ -1,6 +1,7 @@
-import type { DurableObjectStorage } from '@cloudflare/workers-types';
+import type { DurableObjectStorage, SyncKvStorage } from '@cloudflare/workers-types';
 import { isThenable, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
 import { storeSpanContext } from '../utils/traceLinks';
+import { instrumentDurableObjectSyncKvStorage } from './instrumentDurableObjectSyncKvStorage';
 
 const STORAGE_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list', 'setAlarm', 'getAlarm', 'deleteAlarm'] as const;
 
@@ -35,6 +36,10 @@ export function instrumentDurableObjectStorage(
  // reference" errors.
  const original = Reflect.get(target, prop, target);
 
+ if (prop === 'kv' && original != null && 'get' in original && 'put' in original) {
+ return instrumentDurableObjectSyncKvStorage(original as SyncKvStorage);
+ }
+
  if (typeof original !== 'function') {
  return original;
  }

packages/cloudflare/src/instrumentations/instrumentDurableObjectSyncKvStorage.ts

@@ -0,0 +1,43 @@
+import type { SyncKvStorage } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, startSpan } from '@sentry/core';
+
+const SYNC_KV_METHODS_TO_INSTRUMENT = ['get', 'put', 'delete', 'list'] as const;
+
+type SyncKvMethod = (typeof SYNC_KV_METHODS_TO_INSTRUMENT)[number];
+
+export function instrumentDurableObjectSyncKvStorage(syncKv: SyncKvStorage): SyncKvStorage {
+ return new Proxy(syncKv, {
+ get(target, prop, _receiver) {
+ const original = Reflect.get(target, prop, target);
+
+ if (typeof original !== 'function') {
+ return original;
+ }
+
+ const methodName = prop as SyncKvMethod;
+
+ if (!SYNC_KV_METHODS_TO_INSTRUMENT.includes(methodName)) {
+ return (original as (...args: unknown[]) => unknown).bind(target);
+ }
+
+ return function (this: unknown, ...args: unknown[]) {
+ return startSpan(
+ {
+ name: `durable_object_storage_kv_${methodName}`,
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ // keeping the value as close as possible to the Cloudflare Worker KV instrumentation
+ // https://github.com/cloudflare/workerd/blob/6b8b11787e2b2a800ab0edd0690bfab3857b0529/src/workerd/api/sync-kv.c%2B%2B#L19
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': methodName,
+ },
+ },
+ () => {
+ return (original as (...args: unknown[]) => unknown).apply(target, args);
+ },
+ );
+ };
+ },
+ });
+}

packages/cloudflare/test/instrumentDurableObjectStorage.test.ts

@@ -1,3 +1,4 @@
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN } from '@sentry/core';
 import * as sentryCore from '@sentry/core';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { instrumentDurableObjectStorage } from '../src/instrumentations/instrumentDurableObjectStorage';
@@ -304,6 +305,28 @@ describe('instrumentDurableObjectStorage', () => {
  });
  });
 
+ describe('sync KV instrumentation', () => {
+ it('instruments the kv property with a proxy', () => {
+ const mockStorage = createMockStorage();
+ const instrumented = instrumentDurableObjectStorage(mockStorage);
+
+ instrumented.kv.get('myKey');
+
+ expect(sentryCore.startSpan).toHaveBeenCalledWith(
+ {
+ name: 'durable_object_storage_kv_get',
+ op: 'db',
+ attributes: {
+ [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.durable_object',
+ 'db.system.name': 'cloudflare-durable-object-sql',
+ 'db.operation.name': 'get',
+ },
+ },
+ expect.any(Function),
+ );
+ });
+ });
+
  describe('native getter preservation', () => {
  it('preserves native getter `this` binding through the proxy', () => {
  // Private fields simulate workerd's native brand check —
@@ -349,5 +372,11 @@ function createMockStorage(): any {
  sql: {
  exec: vi.fn(),
  },
+ kv: {
+ get: vi.fn().mockReturnValue(undefined),
+ put: vi.fn().mockReturnValue(undefined),
+ delete: vi.fn().mockReturnValue(false),
+ list: vi.fn().mockReturnValue([]),
+ },
  };
 }