diff --git a/dev-packages/cloudflare-integration-tests/suites/tail-stream/index-producer.ts b/dev-packages/cloudflare-integration-tests/suites/tail-stream/index-producer.ts new file mode 100644 index 000000000000..4bc14ed89a89 --- /dev/null +++ b/dev-packages/cloudflare-integration-tests/suites/tail-stream/index-producer.ts @@ -0,0 +1,5 @@ +export default { + async fetch() { + return new Response('ok'); + }, +} satisfies ExportedHandler; diff --git a/dev-packages/cloudflare-integration-tests/suites/tail-stream/index.ts b/dev-packages/cloudflare-integration-tests/suites/tail-stream/index.ts new file mode 100644 index 000000000000..70632becce3a --- /dev/null +++ b/dev-packages/cloudflare-integration-tests/suites/tail-stream/index.ts @@ -0,0 +1,19 @@ +interface Env { + PRODUCER: Fetcher; +} + +// Nothing is wrapped manually, the Vite plugin wraps the default export. +export default { + async fetch(_request, env) { + return env.PRODUCER.fetch('http://fake-host/'); + }, + // workerd calls `tailStream()` with the producer's onset event, then calls + // the returned object for the later events of that invocation. + tailStream() { + return { + outcome() { + throw new Error('Error from the tailStream outcome handler'); + }, + }; + }, +} satisfies ExportedHandler; diff --git a/dev-packages/cloudflare-integration-tests/suites/tail-stream/instrument.server.ts b/dev-packages/cloudflare-integration-tests/suites/tail-stream/instrument.server.ts new file mode 100644 index 000000000000..9de8aec879bb --- /dev/null +++ b/dev-packages/cloudflare-integration-tests/suites/tail-stream/instrument.server.ts @@ -0,0 +1,5 @@ +import { defineCloudflareOptions } from '@sentry/cloudflare'; + +export default defineCloudflareOptions((env: { SENTRY_DSN: string }) => ({ + dsn: env.SENTRY_DSN, +})); diff --git a/dev-packages/cloudflare-integration-tests/suites/tail-stream/test.ts b/dev-packages/cloudflare-integration-tests/suites/tail-stream/test.ts new file mode 100644 index 000000000000..3d906ace27bb --- /dev/null +++ b/dev-packages/cloudflare-integration-tests/suites/tail-stream/test.ts @@ -0,0 +1,25 @@ +import type { Event } from '@sentry/core'; +import { join } from 'path'; +import { expect, it } from 'vitest'; +import { createRunner } from '../../runner'; + +it('captures errors thrown by the handler that tailStream returns', async ({ signal }) => { + const runner = createRunner(__dirname) + // A tail consumer in another `wrangler dev` process does not receive + // streaming tail events, so the producer runs in the same process. + .withWranglerArgs('-c', join(__dirname, 'dist/cloudflare_tail_stream_producer/wrangler.json')) + .expect(envelope => { + const event = envelope[1][0]?.[1] as Event; + expect(event.exception?.values?.[0]).toEqual( + expect.objectContaining({ + type: 'Error', + value: 'Error from the tailStream outcome handler', + mechanism: { type: 'auto.faas.cloudflare.tail_stream', handled: false }, + }), + ); + }) + .start(signal); + + await runner.makeRequest('get', '/'); + await runner.completed(); +}); diff --git a/dev-packages/cloudflare-integration-tests/suites/tail-stream/vite.config.mts b/dev-packages/cloudflare-integration-tests/suites/tail-stream/vite.config.mts new file mode 100644 index 000000000000..71ebb6c3e6fa --- /dev/null +++ b/dev-packages/cloudflare-integration-tests/suites/tail-stream/vite.config.mts @@ -0,0 +1,10 @@ +import { cloudflare } from '@cloudflare/vite-plugin'; +import { sentryCloudflareVitePlugin } from '@sentry/cloudflare/vite'; +import { defineConfig } from 'vite'; + +export default defineConfig({ + plugins: [ + cloudflare({ auxiliaryWorkers: [{ configPath: './wrangler-producer.jsonc' }] }), + sentryCloudflareVitePlugin(), + ], +}); diff --git a/dev-packages/cloudflare-integration-tests/suites/tail-stream/wrangler-producer.jsonc b/dev-packages/cloudflare-integration-tests/suites/tail-stream/wrangler-producer.jsonc new file mode 100644 index 000000000000..97e22bd98f7d --- /dev/null +++ b/dev-packages/cloudflare-integration-tests/suites/tail-stream/wrangler-producer.jsonc @@ -0,0 +1,8 @@ +{ + "$schema": "../../node_modules/wrangler/config-schema.json", + "name": "cloudflare-tail-stream-producer", + "main": "index-producer.ts", + "compatibility_date": "2025-06-17", + "compatibility_flags": ["nodejs_compat"], + "streaming_tail_consumers": [{ "service": "cloudflare-tail-stream-consumer" }], +} diff --git a/dev-packages/cloudflare-integration-tests/suites/tail-stream/wrangler.jsonc b/dev-packages/cloudflare-integration-tests/suites/tail-stream/wrangler.jsonc new file mode 100644 index 000000000000..0f4b2e593c3c --- /dev/null +++ b/dev-packages/cloudflare-integration-tests/suites/tail-stream/wrangler.jsonc @@ -0,0 +1,8 @@ +{ + "$schema": "../../node_modules/wrangler/config-schema.json", + "name": "cloudflare-tail-stream-consumer", + "main": "index.ts", + "compatibility_date": "2025-06-17", + "compatibility_flags": ["nodejs_compat"], + "services": [{ "binding": "PRODUCER", "service": "cloudflare-tail-stream-producer" }], +} diff --git a/packages/cloudflare/src/instrumentations/worker/instrumentTail.ts b/packages/cloudflare/src/instrumentations/worker/instrumentTail.ts index 31ecd6674120..a303d417f169 100644 --- a/packages/cloudflare/src/instrumentations/worker/instrumentTail.ts +++ b/packages/cloudflare/src/instrumentations/worker/instrumentTail.ts @@ -1,4 +1,3 @@ -import type { TraceItem } from '@cloudflare/workers-types'; import type { AnyExportedHandler } from '../../types'; import type { env as cloudflareEnv, WorkerEntrypoint } from 'cloudflare:workers'; import { captureException, withIsolationScope } from '@sentry/core'; @@ -10,13 +9,29 @@ import { addCloudResourceContext } from '../../scope-utils'; import { init } from '../../sdk'; import { instrumentContext } from '../../utils/instrumentContext'; import { setInvocationState } from '../../utils/invocationContext'; +import { type UncheckedMethod } from '../../wrapMethodWithSentry'; import { instrumentEnv } from './instrumentEnv'; +type TailMethod = 'tail' | 'trace' | 'tailStream'; + +const TAIL_METHODS: TailMethod[] = ['tail', 'trace', 'tailStream']; + +const MECHANISM_TYPES: Record = { + tail: 'auto.faas.cloudflare.tail', + trace: 'auto.faas.cloudflare.trace', + tailStream: 'auto.faas.cloudflare.tail_stream', +}; + /** * Core tail handler logic - wraps execution with Sentry instrumentation. * Note: tail handlers don't create spans, just error capture. */ -function wrapTailHandler(options: CloudflareOptions, context: ExecutionContext, fn: () => unknown): unknown { +function wrapTailHandler( + options: CloudflareOptions, + context: ExecutionContext, + method: TailMethod, + fn: () => unknown, +): unknown { return withIsolationScope(async isolationScope => { const waitUntil = context.waitUntil.bind(context); @@ -30,7 +45,7 @@ function wrapTailHandler(options: CloudflareOptions, context: ExecutionContext, try { return await fn(); } catch (e) { - captureException(e, { mechanism: { handled: false, type: 'auto.faas.cloudflare.tail' } }); + captureException(e, { mechanism: { handled: false, type: MECHANISM_TYPES[method] } }); throw e; } finally { waitUntil(flushAndDispose(client)); @@ -39,49 +54,116 @@ function wrapTailHandler(options: CloudflareOptions, context: ExecutionContext, } /** - * Instruments a tail handler for ExportedHandler (env/ctx come from args). + * workerd calls `tailStream()` once with the onset event, then calls the + * function or object methods it returns for each later batch of events. + * Each of those calls runs as its own invocation. + */ +function wrapTailStreamEventHandler( + eventHandler: unknown, + options: CloudflareOptions, + context: ExecutionContext, +): unknown { + const wrap = (fn: UncheckedMethod, getThis: (thisArg: unknown) => unknown): UncheckedMethod => + new Proxy(fn, { + apply(target, thisArg, args) { + return wrapTailHandler(options, context, 'tailStream', () => Reflect.apply(target, getThis(thisArg), args)); + }, + }); + + if (typeof eventHandler === 'function') { + return wrap(eventHandler as UncheckedMethod, thisArg => thisArg); + } + + if (eventHandler && typeof eventHandler === 'object') { + const proxy: object = new Proxy(eventHandler, { + get(target, prop) { + // Getters and methods run with the raw object as `this`, so private + // fields work. workerd calls each method with the proxy as `this`. + // Rebinding it also keeps `this.helper()` in this invocation. + const value = Reflect.get(target, prop, target); + return typeof value === 'function' + ? wrap(value as UncheckedMethod, thisArg => (thisArg === proxy ? target : thisArg)) + : value; + }, + }); + return proxy; + } + + return eventHandler; +} + +function runTailMethod( + method: TailMethod, + options: CloudflareOptions, + context: ExecutionContext, + invoke: () => unknown, +): unknown { + if (method !== 'tailStream') { + return wrapTailHandler(options, context, method, invoke); + } + + return wrapTailHandler(options, context, method, async () => + wrapTailStreamEventHandler(await invoke(), options, context), + ); +} + +/** + * Instruments the `tail`, `trace` and `tailStream` handlers for + * ExportedHandler (env/ctx come from args). */ export function instrumentExportedHandlerTail( handler: T, optionsCallback: (env: typeof cloudflareEnv) => CloudflareOptions | undefined, ): void { - if (!('tail' in handler) || typeof handler.tail !== 'function') { - return; - } + for (const method of TAIL_METHODS) { + if (!(method in handler)) { + continue; + } - handler.tail = ensureInstrumented( - handler.tail, - original => - new Proxy(original, { - apply(target, thisArg, args: Parameters>) { - const [, env, ctx] = args; - const context = instrumentContext(ctx); - const options = getFinalOptions(optionsCallback(env), env); - args[1] = instrumentEnv(env, options); - args[2] = context; - - return wrapTailHandler(options, context, () => target.apply(thisArg, args)); - }, - }), - ); + const original = handler[method]; + if (typeof original !== 'function') { + continue; + } + + handler[method] = ensureInstrumented( + original, + original => + new Proxy(original, { + apply(target, thisArg, args: Parameters) { + const [, env, ctx] = args; + const context = instrumentContext(ctx); + const options = getFinalOptions(optionsCallback(env), env); + args[1] = instrumentEnv(env, options); + args[2] = context; + + return runTailMethod(method, options, context, () => target.apply(thisArg, args)); + }, + }), + ); + } } /** - * Instruments a tail method for WorkerEntrypoint (options/context already available). + * Instruments the `tail`, `trace` and `tailStream` methods for + * WorkerEntrypoint (options/context already available). */ export function instrumentWorkerEntrypointTail( instance: T, options: CloudflareOptions, context: ExecutionContext, ): void { - if (!instance.tail) { - return; - } + const methods = instance as Partial>; - const original = instance.tail.bind(instance); - instance.tail = new Proxy(original, { - apply(target, thisArg, args: [TraceItem[]]) { - return wrapTailHandler(options, context, () => Reflect.apply(target, thisArg, args)); - }, - }); + for (const method of TAIL_METHODS) { + const original = methods[method]; + if (!original) { + continue; + } + + methods[method] = new Proxy(original.bind(instance), { + apply(target, thisArg, args) { + return runTailMethod(method, options, context, () => Reflect.apply(target, thisArg, args)); + }, + }); + } } diff --git a/packages/cloudflare/test/instrumentations/instrumentWorkerEntrypoint.test.ts b/packages/cloudflare/test/instrumentations/instrumentWorkerEntrypoint.test.ts index 3c7f114099c0..875e03aab0db 100644 --- a/packages/cloudflare/test/instrumentations/instrumentWorkerEntrypoint.test.ts +++ b/packages/cloudflare/test/instrumentations/instrumentWorkerEntrypoint.test.ts @@ -112,6 +112,49 @@ describe('instrumentWorkerEntrypoint', () => { expect(await response.text()).toBe('ok'); }); + it('captures and re-throws errors thrown by the trace method', async () => { + const captureExceptionSpy = vi.spyOn(SentryCore, 'captureException'); + const error = new Error('test'); + const TestClass = class extends WorkerEntrypoint { + trace() { + throw error; + } + }; + const obj = Reflect.construct( + instrumentWorkerEntrypoint(vi.fn().mockReturnValue({}), TestClass as unknown as WorkerEntrypointConstructor), + [createMockExecutionContext(), {}], + ); + + await expect(obj.trace([])).rejects.toBe(error); + expect(captureExceptionSpy).toHaveBeenCalledTimes(1); + expect(captureExceptionSpy).toHaveBeenLastCalledWith(error, { + mechanism: { handled: false, type: 'auto.faas.cloudflare.trace' }, + }); + }); + + it('captures and re-throws errors thrown by the event handler that tailStream returns', async () => { + const captureExceptionSpy = vi.spyOn(SentryCore, 'captureException'); + const error = new Error('test'); + const TestClass = class extends WorkerEntrypoint { + tailStream() { + return () => { + throw error; + }; + } + }; + const obj = Reflect.construct( + instrumentWorkerEntrypoint(vi.fn().mockReturnValue({}), TestClass as unknown as WorkerEntrypointConstructor), + [createMockExecutionContext(), {}], + ); + + const eventHandler = await obj.tailStream({}); + await expect(eventHandler({})).rejects.toBe(error); + expect(captureExceptionSpy).toHaveBeenCalledTimes(1); + expect(captureExceptionSpy).toHaveBeenLastCalledWith(error, { + mechanism: { handled: false, type: 'auto.faas.cloudflare.tail_stream' }, + }); + }); + it('Does not instrument ctx and env properties', () => { const mockContext = createMockExecutionContext(); const mockEnv = {}; @@ -529,7 +572,7 @@ describe('instrumentWorkerEntrypoint', () => { await obj.alarm(); await obj.webSocketMessage(); - expect(initAndBind).toHaveBeenCalledTimes(3); + expect(initAndBind).toHaveBeenCalledTimes(5); }); }); diff --git a/packages/cloudflare/test/instrumentations/worker/instrumentTail.test.ts b/packages/cloudflare/test/instrumentations/worker/instrumentTail.test.ts index 014916e6f158..058cb435bebb 100644 --- a/packages/cloudflare/test/instrumentations/worker/instrumentTail.test.ts +++ b/packages/cloudflare/test/instrumentations/worker/instrumentTail.test.ts @@ -1,7 +1,7 @@ // Note: These tests run the handler in Node.js, which has some differences to the cloudflare workers runtime. // Although this is not ideal, this is the best we can do until we have a better way to test cloudflare workers. -import type { ExecutionContext, TraceItem } from '@cloudflare/workers-types'; +import type { ExecutionContext, TailStream, TraceItem } from '@cloudflare/workers-types'; import type { Event } from '@sentry/core'; import * as SentryCore from '@sentry/core'; import { beforeEach, describe, expect, onTestFinished, test, vi } from 'vitest'; @@ -275,3 +275,236 @@ describe('instrumentTail', () => { expect(flush).toHaveBeenCalledOnce(); }); }); + +describe('tail handler detection', () => { + test('does not add tail handlers to a handler whose proxy returns functions for unknown properties', () => { + const target = { fetch: () => new Response('ok') }; + const handler = new Proxy(target, { + get: (t, prop) => t[prop as keyof typeof t] ?? (() => undefined), + }); + + withSentry(() => ({}), handler); + + expect(Object.keys(target)).toEqual(['fetch']); + }); +}); + +describe('instrumentTrace', () => { + beforeEach(() => { + vi.clearAllMocks(); + resetSdk(); + }); + + test('creates a cloudflare client', async () => { + const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind'); + const handler = { + trace(_traces, _env, _context) { + return; + }, + } satisfies ExportedHandler; + + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN }), handler); + await wrappedHandler.trace?.(createMockTailEvent(), MOCK_ENV, createMockExecutionContext()); + + expect(initAndBindSpy).toHaveBeenCalledTimes(1); + expect(initAndBindSpy).toHaveBeenLastCalledWith(CloudflareClient, expect.any(Object)); + }); + + test('captures and re-throws errors thrown by the handler', async () => { + const captureExceptionSpy = vi.spyOn(SentryCore, 'captureException'); + const error = new Error('test'); + const handler = { + trace(_traces, _env, _context) { + throw error; + }, + } satisfies ExportedHandler; + + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN }), handler); + + let thrownError: unknown; + try { + await wrappedHandler.trace?.(createMockTailEvent(), MOCK_ENV, createMockExecutionContext()); + } catch (e) { + thrownError = e; + } + + expect(thrownError).toBe(error); + expect(captureExceptionSpy).toHaveBeenCalledTimes(1); + expect(captureExceptionSpy).toHaveBeenLastCalledWith(error, { + mechanism: { handled: false, type: 'auto.faas.cloudflare.trace' }, + }); + }); +}); + +describe('instrumentTailStream', () => { + const onsetEvent = {} as TailStream.TailEvent; + const outcomeEvent = {} as TailStream.TailEvent; + + beforeEach(() => { + vi.clearAllMocks(); + resetSdk(); + }); + + test('captures and re-throws errors thrown by the handler', async () => { + const captureExceptionSpy = vi.spyOn(SentryCore, 'captureException'); + const error = new Error('test'); + const handler = { + tailStream(_event, _env, _context) { + throw error; + }, + } satisfies ExportedHandler; + + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN }), handler); + + let thrownError: unknown; + try { + await wrappedHandler.tailStream?.(onsetEvent, MOCK_ENV, createMockExecutionContext()); + } catch (e) { + thrownError = e; + } + + expect(thrownError).toBe(error); + expect(captureExceptionSpy).toHaveBeenCalledTimes(1); + expect(captureExceptionSpy).toHaveBeenLastCalledWith(error, { + mechanism: { handled: false, type: 'auto.faas.cloudflare.tail_stream' }, + }); + }); + + test('passes events to the returned event handler with a client for each call', async () => { + const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind'); + const eventHandler = vi.fn(); + const handler = { + tailStream(_event, _env, _context) { + return eventHandler; + }, + } satisfies ExportedHandler; + + // A per-invocation client makes every instrumented call visible as its own init. + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN, cacheClient: false }), handler); + const returned = (await wrappedHandler.tailStream?.( + onsetEvent, + MOCK_ENV, + createMockExecutionContext(), + )) as TailStream.TailEventHandler; + await returned(outcomeEvent); + + expect(eventHandler).toHaveBeenCalledWith(outcomeEvent); + expect(initAndBindSpy).toHaveBeenCalledTimes(2); + }); + + test('captures and re-throws errors thrown by the returned event handler function', async () => { + const captureExceptionSpy = vi.spyOn(SentryCore, 'captureException'); + const error = new Error('test'); + const handler = { + tailStream(_event, _env, _context) { + return () => { + throw error; + }; + }, + } satisfies ExportedHandler; + + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN }), handler); + const returned = (await wrappedHandler.tailStream?.( + onsetEvent, + MOCK_ENV, + createMockExecutionContext(), + )) as TailStream.TailEventHandler; + + let thrownError: unknown; + try { + await returned(outcomeEvent); + } catch (e) { + thrownError = e; + } + + expect(thrownError).toBe(error); + expect(captureExceptionSpy).toHaveBeenCalledTimes(1); + expect(captureExceptionSpy).toHaveBeenLastCalledWith(error, { + mechanism: { handled: false, type: 'auto.faas.cloudflare.tail_stream' }, + }); + }); + + test('supports getters that read private fields on the returned event handler object', async () => { + class Collector { + #count = 0; + + get outcome(): () => number { + return () => ++this.#count; + } + } + + const handler = { + tailStream(_event, _env, _context) { + return new Collector(); + }, + } satisfies ExportedHandler; + + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN }), handler); + const returned = (await wrappedHandler.tailStream?.( + onsetEvent, + MOCK_ENV, + createMockExecutionContext(), + )) as unknown as Collector; + + await expect(returned.outcome.call(returned)).resolves.toBe(1); + }); + + test('does not start a nested invocation when an event handler method calls another method', async () => { + const initAndBindSpy = vi.spyOn(SentryCore, 'initAndBind'); + const handler = { + tailStream(_event, _env, _context) { + return { + outcome(this: { helper: () => void }) { + this.helper(); + }, + helper() {}, + }; + }, + } satisfies ExportedHandler; + + // A per-invocation client makes every instrumented call visible as its own init. + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN, cacheClient: false }), handler); + const returned = (await wrappedHandler.tailStream?.( + onsetEvent, + MOCK_ENV, + createMockExecutionContext(), + )) as TailStream.TailEventHandlerObject; + await returned.outcome?.(outcomeEvent); + + expect(initAndBindSpy).toHaveBeenCalledTimes(2); + }); + + test('captures and re-throws errors thrown by methods of the returned event handler object', async () => { + const captureExceptionSpy = vi.spyOn(SentryCore, 'captureException'); + const error = new Error('test'); + const handler = { + tailStream(_event, _env, _context) { + return { + outcome() { + throw error; + }, + }; + }, + } satisfies ExportedHandler; + + const wrappedHandler = withSentry(env => ({ dsn: env.SENTRY_DSN }), handler); + const returned = (await wrappedHandler.tailStream?.( + onsetEvent, + MOCK_ENV, + createMockExecutionContext(), + )) as TailStream.TailEventHandlerObject; + + let thrownError: unknown; + try { + await returned.outcome?.(outcomeEvent); + } catch (e) { + thrownError = e; + } + + expect(thrownError).toBe(error); + expect(captureExceptionSpy).toHaveBeenCalledTimes(1); + expect(captureExceptionSpy).toHaveBeenLastCalledWith(error, { + mechanism: { handled: false, type: 'auto.faas.cloudflare.tail_stream' }, + }); + }); +});