feat(server-utils): Migrate FirebaseInstrumentation to orchestrion (#22141)

Rewrites the `Firebase` integration off `InstrumentationBase` to an
orchestrion diagnostics-channel listener in `@sentry/server-utils`,
following the mysql
([#20900](<#20900>))
and graphql (#21885) migrations. The
channel-based integration reuses the OTel `Firebase` name, so opting in
via `experimentalUseDiagnosticsChannelInjection()` swaps it in 1:1 for
the OTel one (which stays the default).

**Firestore** — subscribes to
`orchestrion:@firebase/firestore:{add,get,set,delete}-doc` (injected
into firestore's lite `addDoc`/`getDocs`/`setDoc`/`deleteDoc`) and emits
the same `db.query` client spans via `bindTracingChannelToSpan`, with a
distinct `auto.firebase.orchestrion.firestore` origin.

**firebase-functions** — the `onX(...)` provider functions *register* a
handler and return synchronously, so the span can't be bound to the
registration call. Instead the channel `start` subscriber rewraps the
handler argument (orchestrion forwards the mutated args array to the
real call), so the returned cloud function opens a `SERVER` span + error
boundary on invocation, with `auto.firebase.orchestrion.functions`
origin.

The `node-firebase` e2e firestore suite additionally runs with
`E2E_ORCHESTRION=true` to assert the orchestrion origin.

Closes #20919

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-authored-by: Nicolas Hrubec <nico.hrubec@sentry.io>

Author: nicohrubec

dev-packages/e2e-tests/test-applications/node-firebase/firestore-app/src/init.ts

@@ -1,10 +1,22 @@
 import * as Sentry from '@sentry/node';
 
+// When `E2E_ORCHESTRION=true`, exercise the diagnostics-channel injection path (the orchestrion-based
+// `Firebase` integration) instead of the OTel one. Opting in before `init()` is enough: this file is
+// imported before `app.ts` imports `firebase/firestore/lite`, so the channel-injection hooks are
+// installed before firestore loads.
+const useOrchestrion = process.env.E2E_ORCHESTRION === 'true';
+
+if (useOrchestrion) {
+  Sentry.experimentalUseDiagnosticsChannelInjection();
+}
+
 Sentry.init({
   dsn: 'https://public@dsn.ingest.sentry.io/1337',
   release: '1.0',
   tracesSampleRate: 1.0,
-  integrations: [Sentry.firebaseIntegration()],
+  integrations: useOrchestrion
+    ? [Sentry.diagnosticsChannelInjectionIntegrations().firebaseIntegration()]
+    : [Sentry.firebaseIntegration()],
   defaultIntegrations: false,
   tunnel: `http://localhost:3031/`, // proxy server
 });

dev-packages/e2e-tests/test-applications/node-firebase/package.json

@@ -11,7 +11,8 @@
     "test": "playwright test",
     "clean": "npx rimraf node_modules **/node_modules pnpm-lock.yaml **/dist *-debug.log test-results",
     "test:build": "pnpm install && pnpm build",
-    "test:assert": "pnpm firebase emulators:exec --project demo-functions 'pnpm test'"
+    "test:assert": "pnpm firebase emulators:exec --project demo-functions 'pnpm test'",
+    "test:assert:orchestrion": "E2E_ORCHESTRION=true pnpm test:assert"
   },
   "dependencies": {
     "@types/node": "^22.13.14",
@@ -26,5 +27,13 @@
   },
   "volta": {
     "extends": "../../package.json"
+  },
+  "sentryTest": {
+    "variants": [
+      {
+        "assert-command": "pnpm test:assert:orchestrion",
+        "label": "node-firebase (Orchestrion)"
+      }
+    ]
   }
 }

dev-packages/e2e-tests/test-applications/node-firebase/tests/transactions.test.ts

@@ -1,105 +1,47 @@
 import { expect, test } from '@playwright/test';
 import { waitForTransaction } from '@sentry-internal/test-utils';
 
-const spanAddDoc = expect.objectContaining({
-  description: 'addDoc cities',
-  data: expect.objectContaining({
+// The same suite runs against both the OTel integration and (with `E2E_ORCHESTRION=true`) the
+// orchestrion diagnostics-channel one. The spans are identical apart from the origin — and the
+// orchestrion spans are Sentry-native, so they carry no OTel-only `otel.kind` attribute.
+const orchestrion = process.env.E2E_ORCHESTRION === 'true';
+const origin = orchestrion ? 'auto.firebase.orchestrion.firestore' : 'auto.firebase.otel.firestore';
+
+function firestoreSpan(operation: string): unknown {
+  const data: Record<string, unknown> = {
     'db.collection.name': 'cities',
     'db.namespace': '[DEFAULT]',
-    'db.operation.name': 'addDoc',
+    'db.operation.name': operation,
     'db.system.name': 'firebase.firestore',
     'firebase.firestore.options.projectId': 'sentry-15d85',
     'firebase.firestore.type': 'collection',
-    'otel.kind': 'CLIENT',
     'server.address': '127.0.0.1',
     'server.port': 8080,
-    'sentry.origin': 'auto.firebase.otel.firestore',
+    'sentry.origin': origin,
     'sentry.op': 'db.query',
-  }),
-  op: 'db.query',
-  origin: 'auto.firebase.otel.firestore',
-  parent_span_id: expect.any(String),
-  trace_id: expect.any(String),
-  span_id: expect.any(String),
-  timestamp: expect.any(Number),
-  start_timestamp: expect.any(Number),
-  status: 'ok',
-});
-
-const spanSetDocs = expect.objectContaining({
-  description: 'setDoc cities',
-  data: expect.objectContaining({
-    'db.collection.name': 'cities',
-    'db.namespace': '[DEFAULT]',
-    'db.operation.name': 'setDoc',
-    'db.system.name': 'firebase.firestore',
-    'firebase.firestore.options.projectId': 'sentry-15d85',
-    'firebase.firestore.type': 'collection',
-    'otel.kind': 'CLIENT',
-    'server.address': '127.0.0.1',
-    'server.port': 8080,
-    'sentry.origin': 'auto.firebase.otel.firestore',
-    'sentry.op': 'db.query',
-  }),
-  op: 'db.query',
-  origin: 'auto.firebase.otel.firestore',
-  parent_span_id: expect.any(String),
-  trace_id: expect.any(String),
-  span_id: expect.any(String),
-  timestamp: expect.any(Number),
-  start_timestamp: expect.any(Number),
-  status: 'ok',
-});
-
-const spanGetDocs = expect.objectContaining({
-  description: 'getDocs cities',
-  data: expect.objectContaining({
-    'db.collection.name': 'cities',
-    'db.namespace': '[DEFAULT]',
-    'db.operation.name': 'getDocs',
-    'db.system.name': 'firebase.firestore',
-    'firebase.firestore.options.projectId': 'sentry-15d85',
-    'firebase.firestore.type': 'collection',
-    'otel.kind': 'CLIENT',
-    'server.address': '127.0.0.1',
-    'server.port': 8080,
-    'sentry.origin': 'auto.firebase.otel.firestore',
-    'sentry.op': 'db.query',
-  }),
-  op: 'db.query',
-  origin: 'auto.firebase.otel.firestore',
-  parent_span_id: expect.any(String),
-  trace_id: expect.any(String),
-  span_id: expect.any(String),
-  timestamp: expect.any(Number),
-  start_timestamp: expect.any(Number),
-  status: 'ok',
-});
+  };
+  if (!orchestrion) {
+    data['otel.kind'] = 'CLIENT';
+  }
+
+  return expect.objectContaining({
+    description: `${operation} cities`,
+    data: expect.objectContaining(data),
+    op: 'db.query',
+    origin,
+    parent_span_id: expect.any(String),
+    trace_id: expect.any(String),
+    span_id: expect.any(String),
+    timestamp: expect.any(Number),
+    start_timestamp: expect.any(Number),
+    status: 'ok',
+  });
+}
 
-const spanDeleteDoc = expect.objectContaining({
-  description: 'deleteDoc cities',
-  data: expect.objectContaining({
-    'db.collection.name': 'cities',
-    'db.namespace': '[DEFAULT]',
-    'db.operation.name': 'deleteDoc',
-    'db.system.name': 'firebase.firestore',
-    'firebase.firestore.options.projectId': 'sentry-15d85',
-    'firebase.firestore.type': 'collection',
-    'otel.kind': 'CLIENT',
-    'server.address': '127.0.0.1',
-    'server.port': 8080,
-    'sentry.origin': 'auto.firebase.otel.firestore',
-    'sentry.op': 'db.query',
-  }),
-  op: 'db.query',
-  origin: 'auto.firebase.otel.firestore',
-  parent_span_id: expect.any(String),
-  trace_id: expect.any(String),
-  span_id: expect.any(String),
-  timestamp: expect.any(Number),
-  start_timestamp: expect.any(Number),
-  status: 'ok',
-});
+const spanAddDoc = firestoreSpan('addDoc');
+const spanSetDocs = firestoreSpan('setDoc');
+const spanGetDocs = firestoreSpan('getDocs');
+const spanDeleteDoc = firestoreSpan('deleteDoc');
 
 test('should add, set, get and delete document', async ({ baseURL, page }) => {
   const serverTransactionPromise = waitForTransaction('node-firebase', span => {

packages/nextjs/src/config/turbopack/constructTurbopackConfig.ts

@@ -1,6 +1,10 @@
 import { debug } from '@sentry/core';
 import * as path from 'path';
-import { getOrchestrionLoaderPath, getSentryInstrumentations } from '@sentry/server-utils/orchestrion/webpack';
+import {
+  getOrchestrionLoaderPath,
+  getSentryInstrumentations,
+  serializeInstrumentations,
+} from '@sentry/server-utils/orchestrion/webpack';
 import type { VercelCronsConfig } from '../../common/types';
 import type { RouteManifest } from '../manifest/types';
 import type {
@@ -141,8 +145,10 @@ function maybeAddOrchestrionRule(
       loaders: [
         {
           loader: getOrchestrionLoaderPath(),
-          // `instrumentations` is JSON-serializable
-          options: { instrumentations: getSentryInstrumentations() as unknown as JSONValue[] },
+          // Turbopack JSON-serializes loader options, so a RegExp `filePath` must be encoded first.
+          options: {
+            instrumentations: serializeInstrumentations(getSentryInstrumentations()) as unknown as JSONValue[],
+          },
         },
       ],
     },

packages/nextjs/test/config/turbopack/constructTurbopackConfig.test.ts

@@ -1307,6 +1307,47 @@ describe('componentAnnotation with turbopackReactComponentAnnotation', () => {
   });
 });
 
+describe('orchestrion diagnostics-channel injection', () => {
+  function getOrchestrionOptions(result: ReturnType<typeof constructTurbopackConfig>): {
+    instrumentations: Array<{ module: { name: string; filePath: unknown } }>;
+  } {
+    const rule = result.rules!['*.{js,mjs,cjs}'] as {
+      loaders: Array<{ options: { instrumentations: Array<{ module: { name: string; filePath: unknown } }> } }>;
+    };
+    return rule.loaders[0]!.options;
+  }
+
+  it('serializes a RegExp filePath so it survives Turbopack JSON loader options', () => {
+    const result = constructTurbopackConfig({
+      userNextConfig: {},
+      userSentryOptions: { _experimental: { useDiagnosticsChannelInjection: true } },
+      nextJsVersion: '16.0.0',
+    });
+
+    const firestore = getOrchestrionOptions(result).instrumentations.find(i => i.module.name === '@firebase/firestore');
+
+    expect(firestore).toBeDefined();
+    expect(firestore!.module.filePath).toEqual({
+      type: 'RegExp',
+      source: expect.any(String),
+      flags: expect.any(String),
+    });
+    expect(firestore!.module.filePath).not.toBeInstanceOf(RegExp);
+    // A raw RegExp would `JSON.stringify` to `{}`, dropping the match entirely.
+    expect(JSON.parse(JSON.stringify(firestore!.module.filePath))).not.toEqual({});
+  });
+
+  it('does not add the orchestrion rule when injection is not opted in', () => {
+    const result = constructTurbopackConfig({
+      userNextConfig: {},
+      userSentryOptions: {},
+      nextJsVersion: '16.0.0',
+    });
+
+    expect(result.rules!['*.{js,mjs,cjs}']).toBeUndefined();
+  });
+});
+
 describe('safelyAddTurbopackRule', () => {
   const mockRule = {
     loaders: [

packages/server-utils/src/integrations/tracing-channel/firebase/firestore-types.ts

@@ -0,0 +1,44 @@
+// Minimal structural types inlined from `firebase/app` and `firebase/firestore`, kept just wide enough
+// for the attributes the subscriber reads off a Firestore reference. Inlined (rather than imported) so
+// `@sentry/server-utils` needs no firebase dependency.
+
+export interface FirebaseOptions {
+  [key: string]: unknown;
+  apiKey?: string;
+  projectId?: string;
+  appId?: string;
+  messagingSenderId?: string;
+  storageBucket?: string;
+}
+
+export interface FirebaseApp {
+  name: string;
+  options: FirebaseOptions;
+}
+
+export interface FirestoreSettings {
+  host?: string;
+}
+
+interface FirestoreLike {
+  app: FirebaseApp;
+  toJSON: () => { settings?: FirestoreSettings };
+}
+
+export interface DocumentReference {
+  id: string;
+  firestore: FirestoreLike;
+  type: string;
+  path: string;
+  parent: CollectionReference | null;
+}
+
+export interface CollectionReference {
+  id: string;
+  firestore: FirestoreLike;
+  type: string;
+  path: string;
+  parent: DocumentReference | null;
+}
+
+export type FirestoreReference = CollectionReference | DocumentReference;