feat(cloudflare): Bootstrap Mastra observability in bundled workers (#24381)

Adds Cloudflare coverage for Mastra — the most common non-Node way users
run Mastra — as a Vite + workerd e2e app (`cloudflare-mastra`), and
fixes the one thing that stopped it working with zero config.

On Cloudflare the Mastra integration couldn't bootstrap Mastra's
observability pipeline: it resolves `@mastra/observability` via
`createRequire`, which has no on-disk `node_modules` in workerd, so
users had to construct and wire up an `Observability` themselves. Now
`@sentry/cloudflare/vite` splices a static `import * as ns from
'@mastra/observability'` into Sentry's own Mastra integration module —
only when the package resolves — and records the namespace on a generic
`__SENTRY_ORCHESTRION__.providedModules` marker; the integration reads
it there before falling back to `createRequire`. Mastra tracing on
Cloudflare now works with no observability config, matching the Node DX.
The import lands in Sentry's module (not user code), stays statically
analyzable (no lazy `import()`/`createRequire` in the bundle), and
no-ops when Mastra isn't used.

**Requires `@mastra/observability` to be an app dependency.** The SDK
never installs or bundles it — it is Mastra's tracing engine (the span
factory), and without it Mastra emits only no-op spans, so there is
nothing to capture. This is **not** new or Cloudflare-specific: it is
equally required on Node, where the integration bootstraps from the
`@mastra/observability` the app already has. On Cloudflare the Vite
plugin's injection is additionally gated on it resolving at build time;
if it is absent the plugin no-ops and no spans are produced (same net
effect as Node).

The e2e app mirrors the `node-mastra` assertions (agent/model/tool
`gen_ai` spans, tool-error capture, orchestrion `dataloader` nesting, an
`http.server` span) against the Cloudflare instrumentation path, where
orchestrion runs at build time. Its tool/dataloader assertions run
against a live model via the existing `E2E_OPENROUTER_API_KEY`; the
`manual-route` test needs no key.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: mydea

dev-packages/e2e-tests/test-applications/cloudflare-mastra/.gitignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+.wrangler
+.dev.vars
+pnpm-lock.yaml
+*.tsbuildinfo
+results.junit.xml
+test-results
+playwright-report

dev-packages/e2e-tests/test-applications/cloudflare-mastra/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "cloudflare-mastra",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build",
+    "preview": "vite preview --port 4111",
+    "typecheck": "tsc --noEmit",
+    "clean": "npx rimraf node_modules dist .wrangler pnpm-lock.yaml",
+    "test:build": "pnpm install && pnpm build",
+    "test:assert": "pnpm test:prod",
+    "test:prod": "TEST_ENV=production playwright test"
+  },
+  "dependencies": {
+    "@mastra/core": "~1.65.0",
+    "@mastra/memory": "~1.28.3",
+    "@mastra/observability": "~1.17.6",
+    "@openrouter/ai-sdk-provider": "~3.0.0",
+    "@sentry/cloudflare": "file:../../packed/sentry-cloudflare-packed.tgz",
+    "ai": "~7.0.97",
+    "dataloader": "~2.2.3",
+    "zod": "4.5.4"
+  },
+  "devDependencies": {
+    "@cloudflare/vite-plugin": "1.52.0",
+    "@cloudflare/workers-types": "^4.20260426.0",
+    "@playwright/test": "~1.63.0",
+    "@sentry-internal/test-utils": "link:../../../test-utils",
+    "typescript": "^5.5.2",
+    "vite": "7.3.5",
+    "wrangler": "^4.86.0",
+    "ws": "^8.18.3"
+  },
+  "volta": {
+    "node": "24.15.0",
+    "extends": "../../package.json"
+  },
+  "sentryTest": {
+    "optional": true
+  }
+}

dev-packages/e2e-tests/test-applications/cloudflare-mastra/playwright.config.ts

@@ -0,0 +1,22 @@
+import { getPlaywrightConfig } from '@sentry-internal/test-utils';
+
+const testEnv = process.env.TEST_ENV;
+
+if (!testEnv) {
+  throw new Error('No test env defined');
+}
+
+const APP_PORT = 4111;
+
+const config = getPlaywrightConfig(
+  {
+    startCommand: 'pnpm preview',
+    port: APP_PORT,
+  },
+  // Each test drives a real OpenRouter tool-calling turn (two model calls) and then
+  // waits for the Mastra spans to flush, which does not fit the default 30s timeout
+  // when the provider is slow.
+  { timeout: 90_000 },
+);
+
+export default config;

dev-packages/e2e-tests/test-applications/cloudflare-mastra/src/env.d.ts

@@ -0,0 +1,4 @@
+interface Env {
+  E2E_TEST_DSN: string;
+  E2E_OPENROUTER_API_KEY: string;
+}

dev-packages/e2e-tests/test-applications/cloudflare-mastra/src/index.ts

@@ -0,0 +1,64 @@
+import { Mastra } from '@mastra/core';
+import { InMemoryStore } from '@mastra/core/storage';
+import { createWeatherAgent, WEATHER_AGENT } from './mastra/agents/weather-agent';
+
+// This file deliberately contains NO `Sentry.*` calls and no import of
+// `@sentry/cloudflare`: `sentryCloudflareVitePlugin()` reads wrangler.toml and wraps
+// this default export with `withSentry` at build time, sourcing options from
+// `instrument.server.ts` next to this entry.
+
+// Built lazily on the first request, then reused across invocations in the isolate.
+//
+// Order matters: the Sentry Mastra integration subscribes to `@mastra/core`'s
+// build-time diagnostics channels during the injected `withSentry` wrapper's
+// (per-request) `init`. The `Mastra` constructor is what fires the channel the
+// exporter attaches on, so it must run *after* init — i.e. inside `fetch`, never at
+// module top level (which would construct it before any subscriber exists). Importing
+// `@mastra/core` at the top is fine: that only evaluates the module (registering the
+// channel-subscriber factory on the global marker the wrapper reads), it does not
+// construct a `Mastra`.
+let mastra: Mastra | undefined;
+
+function getMastra(apiKey: string): Mastra {
+  if (!mastra) {
+    mastra = new Mastra({
+      agents: { [WEATHER_AGENT]: createWeatherAgent(apiKey) },
+      storage: new InMemoryStore(),
+    });
+  }
+  return mastra;
+}
+
+interface GeneratePayload {
+  message: string;
+  thread?: string;
+  resource?: string;
+}
+
+export default {
+  async fetch(request: Request, env: Env): Promise<Response> {
+    const url = new URL(request.url);
+
+    if (url.pathname === '/manual-route') {
+      return Response.json({ ok: true });
+    }
+
+    if (url.pathname === '/generate' && request.method === 'POST') {
+      const { message, thread, resource } = (await request.json()) as GeneratePayload;
+
+      const agent = getMastra(env.E2E_OPENROUTER_API_KEY).getAgent(WEATHER_AGENT);
+
+      // The nested `memory: { thread, resource }` shape is the modern `generate` path —
+      // it is what makes Mastra stamp the thread id onto the spans (→
+      // `gen_ai.conversation.id`). Top-level `threadId`/`resourceId` would route to the
+      // deprecated `generateLegacy` path, which the AI instrumentation does not cover.
+      const result = await agent.generate(message, {
+        ...(thread ? { memory: { thread, resource: resource ?? 'e2e-user' } } : {}),
+      });
+
+      return Response.json({ text: result.text });
+    }
+
+    return new Response('Not found', { status: 404 });
+  },
+} satisfies ExportedHandler<Env>;

dev-packages/e2e-tests/test-applications/cloudflare-mastra/src/instrument.server.ts

@@ -0,0 +1,10 @@
+// The auto-instrument plugin (`sentryCloudflareVitePlugin`) picks this file up by
+// convention — it sits next to the worker entry named in wrangler's `main` — and
+// imports its default export as the options callback for the `withSentry` wrapper it
+// injects into the entry at build time.
+export default (env: Env) => ({
+  dsn: env.E2E_TEST_DSN,
+  environment: 'qa',
+  tunnel: 'http://localhost:3031/', // proxy server
+  tracesSampleRate: 1.0,
+});

dev-packages/e2e-tests/test-applications/cloudflare-mastra/src/mastra/agents/weather-agent.ts

@@ -0,0 +1,38 @@
+import { createOpenRouter } from '@openrouter/ai-sdk-provider';
+import { Agent } from '@mastra/core/agent';
+import { InMemoryStore } from '@mastra/core/storage';
+import { Memory } from '@mastra/memory';
+import { countItemsTool } from '../tools/count-items';
+import { failNowTool } from '../tools/fail-now';
+import { getWeatherTool } from '../tools/get-weather';
+
+export const WEATHER_AGENT = 'weatherAgent';
+
+export function createWeatherAgent(apiKey: string): Agent {
+  // Call OpenRouter directly (rather than the default Vercel AI Gateway) so the e2e
+  // test needs only a single OpenRouter key, reusing `E2E_OPENROUTER_API_KEY`.
+  const openrouter = createOpenRouter({ apiKey });
+
+  // `InMemoryStore` is a pure-JS store (no libsql/native) so it runs in workerd,
+  // unlike the `@mastra/libsql` store the Node app uses. Mastra requires a storage
+  // provider before `generate(..., { memory: { thread, resource } })` is accepted,
+  // and that thread id is what the Sentry exporter maps to `gen_ai.conversation.id`.
+  const memory = new Memory({ storage: new InMemoryStore() });
+
+  return new Agent({
+    // `id` (registry key + REST `:agentId`), `name` (used for `gen_ai.agent.name`)
+    // are kept identical so the generate call and span assertions line up.
+    id: WEATHER_AGENT,
+    name: WEATHER_AGENT,
+    instructions: [
+      'You are a concise assistant used by an automated end-to-end test.',
+      'When the user asks about the weather in a place, call the `get_weather` tool for that place and answer in one short sentence using its result.',
+      'When the user asks you to trigger a failure, call the `fail_now` tool.',
+      'When the user asks you to count items, call the `count_items` tool with the item names.',
+      'Do not ask follow-up questions.',
+    ].join('\n'),
+    model: openrouter('openai/gpt-4o-mini'),
+    tools: { get_weather: getWeatherTool, fail_now: failNowTool, count_items: countItemsTool },
+    memory,
+  });
+}

dev-packages/e2e-tests/test-applications/cloudflare-mastra/src/mastra/tools/count-items.ts

@@ -0,0 +1,18 @@
+import { createTool } from '@mastra/core/tools';
+import DataLoader from 'dataloader';
+import { z } from 'zod';
+
+// Uses the orchestrion-instrumented `dataloader` inside a tool, to prove the build-time
+// orchestrion transform (via `@sentry/cloudflare/vite`) works for a non-Mastra package
+// driven through the agent's tool-call flow.
+export const countItemsTool = createTool({
+  id: 'count_items',
+  description: 'Count the number of letters in each given name. Call this when asked to count items.',
+  inputSchema: z.object({ names: z.array(z.string()).min(1) }),
+  outputSchema: z.object({ counts: z.array(z.number()) }),
+  async execute(inputData) {
+    const loader = new DataLoader<string, number>(async keys => keys.map(key => key.length));
+    const counts = await Promise.all(inputData.names.map(name => loader.load(name)));
+    return { counts };
+  },
+});

dev-packages/e2e-tests/test-applications/cloudflare-mastra/src/mastra/tools/fail-now.ts

@@ -0,0 +1,12 @@
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+export const failNowTool = createTool({
+  id: 'fail_now',
+  description: 'Always throws an error. Call this when the user asks to trigger a failure.',
+  inputSchema: z.object({}),
+  outputSchema: z.object({}),
+  async execute() {
+    throw new Error('Intentional Mastra tool failure');
+  },
+});

dev-packages/e2e-tests/test-applications/cloudflare-mastra/src/mastra/tools/get-weather.ts

@@ -0,0 +1,16 @@
+import { createTool } from '@mastra/core/tools';
+import { z } from 'zod';
+
+export const getWeatherTool = createTool({
+  id: 'get_weather',
+  description: 'Get the current weather for a city.',
+  inputSchema: z.object({ city: z.string().min(1) }),
+  outputSchema: z.object({
+    city: z.string(),
+    condition: z.string(),
+    temperatureC: z.number(),
+  }),
+  async execute(inputData) {
+    return { city: inputData.city, condition: 'Sunny', temperatureC: 22 };
+  },
+});