feat(node): Rewrite knex instrumentation to orchestrion tracing channels (#22237)

Migrates the knex integration off the vendored `InstrumentationBase`
monkey-patch onto a `node:diagnostics_channel` subscriber whose channels
are injected by the orchestrion code transform. The vendored OTel path
stays as the fallback when orchestrion isn't injected.

closes #20757

Author: logaretm

dev-packages/node-integration-tests/suites/tracing/knex/mysql2/test.ts

@@ -1,9 +1,11 @@
 import { describe, expect } from 'vitest';
+import { isOrchestrionEnabled } from '../../../../utils';
 import { createEsmAndCjsTests, describeWithDockerCompose } from '../../../../utils/runner';
 
 describeWithDockerCompose('knex auto instrumentation', { workingDirectory: [__dirname] }, () => {
   // Update this if another knex version is installed
   const KNEX_VERSION = '2.5.1';
+  const ORIGIN = isOrchestrionEnabled() ? 'auto.db.orchestrion.knex' : 'auto.db.otel.knex';
 
   describe('with `mysql2` client', () => {
     createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
@@ -17,30 +19,30 @@ describeWithDockerCompose('knex auto instrumentation', { workingDirectory: [__di
                 'db.system': 'mysql2',
                 'db.name': 'tests',
                 'db.user': 'root',
-                'sentry.origin': 'auto.db.otel.knex',
+                'sentry.origin': ORIGIN,
                 'sentry.op': 'db',
                 'net.peer.name': 'localhost',
                 'net.peer.port': 3307,
               }),
               status: 'ok',
               description:
                 'create table `User` (`id` int unsigned not null auto_increment primary key, `createdAt` timestamp(3) not null default CURRENT_TIMESTAMP(3), `email` text not null, `name` text not null)',
-              origin: 'auto.db.otel.knex',
+              origin: ORIGIN,
             }),
             expect.objectContaining({
               data: expect.objectContaining({
                 'knex.version': KNEX_VERSION,
                 'db.system': 'mysql2',
                 'db.name': 'tests',
                 'db.user': 'root',
-                'sentry.origin': 'auto.db.otel.knex',
+                'sentry.origin': ORIGIN,
                 'sentry.op': 'db',
                 'net.peer.name': 'localhost',
                 'net.peer.port': 3307,
               }),
               status: 'ok',
               description: 'insert into `User` (`email`, `name`) values (?, ?)',
-              origin: 'auto.db.otel.knex',
+              origin: ORIGIN,
             }),
 
             expect.objectContaining({
@@ -52,12 +54,12 @@ describeWithDockerCompose('knex auto instrumentation', { workingDirectory: [__di
                 'db.name': 'tests',
                 'db.statement': 'select * from `User`',
                 'db.user': 'root',
-                'sentry.origin': 'auto.db.otel.knex',
+                'sentry.origin': ORIGIN,
                 'sentry.op': 'db',
               }),
               status: 'ok',
               description: 'select * from `User`',
-              origin: 'auto.db.otel.knex',
+              origin: ORIGIN,
             }),
           ]),
         };

dev-packages/node-integration-tests/suites/tracing/knex/pg/test.ts

@@ -1,9 +1,11 @@
 import { describe, expect } from 'vitest';
+import { isOrchestrionEnabled } from '../../../../utils';
 import { createEsmAndCjsTests, describeWithDockerCompose } from '../../../../utils/runner';
 
 describe('knex auto instrumentation', () => {
   // Update this if another knex version is installed
   const KNEX_VERSION = '2.5.1';
+  const ORIGIN = isOrchestrionEnabled() ? 'auto.db.orchestrion.knex' : 'auto.db.otel.knex';
 
   describeWithDockerCompose('with `pg` client', { workingDirectory: [__dirname] }, () => {
     createEsmAndCjsTests(__dirname, 'scenario.mjs', 'instrument.mjs', (createRunner, test) => {
@@ -16,30 +18,30 @@ describe('knex auto instrumentation', () => {
                 'knex.version': KNEX_VERSION,
                 'db.system': 'postgresql',
                 'db.name': 'tests',
-                'sentry.origin': 'auto.db.otel.knex',
+                'sentry.origin': ORIGIN,
                 'sentry.op': 'db',
                 'net.peer.name': 'localhost',
                 'net.peer.port': 5445,
               }),
               status: 'ok',
               description:
                 'create table "User" ("id" serial primary key, "createdAt" timestamptz(3) not null default CURRENT_TIMESTAMP(3), "email" text not null, "name" text not null)',
-              origin: 'auto.db.otel.knex',
+              origin: ORIGIN,
             }),
             expect.objectContaining({
               data: expect.objectContaining({
                 'knex.version': KNEX_VERSION,
                 'db.system': 'postgresql',
                 'db.name': 'tests',
-                'sentry.origin': 'auto.db.otel.knex',
+                'sentry.origin': ORIGIN,
                 'sentry.op': 'db',
                 'net.peer.name': 'localhost',
                 'net.peer.port': 5445,
               }),
               status: 'ok',
               // In the knex-otel spans, the placeholders (e.g., `$1`) are replaced by a `?`.
               description: 'insert into "User" ("email", "name") values (?, ?)',
-              origin: 'auto.db.otel.knex',
+              origin: ORIGIN,
             }),
 
             expect.objectContaining({
@@ -50,12 +52,12 @@ describe('knex auto instrumentation', () => {
                 'db.system': 'postgresql',
                 'db.name': 'tests',
                 'db.statement': 'select * from "User"',
-                'sentry.origin': 'auto.db.otel.knex',
+                'sentry.origin': ORIGIN,
                 'sentry.op': 'db',
               }),
               status: 'ok',
               description: 'select * from "User"',
-              origin: 'auto.db.otel.knex',
+              origin: ORIGIN,
             }),
 
             expect.objectContaining({
@@ -66,12 +68,12 @@ describe('knex auto instrumentation', () => {
                 'db.system': 'postgresql',
                 'db.name': 'tests',
                 'db.statement': 'select * from "DoesNotExist"',
-                'sentry.origin': 'auto.db.otel.knex',
+                'sentry.origin': ORIGIN,
                 'sentry.op': 'db',
               }),
               status: 'internal_error',
               description: 'select * from "DoesNotExist"',
-              origin: 'auto.db.otel.knex',
+              origin: ORIGIN,
             }),
           ]),
         };

packages/deno/src/index.ts

@@ -115,6 +115,7 @@ export { denoMysqlIntegration } from './integrations/mysql';
 export { denoPostgresIntegration } from './integrations/postgres';
 export { denoAmqplibIntegration } from './integrations/amqplib';
 export { denoDataloaderIntegration } from './integrations/dataloader';
+export { denoKnexIntegration } from './integrations/knex';
 export { denoContextIntegration } from './integrations/context';
 export { globalHandlersIntegration } from './integrations/globalhandlers';
 export { normalizePathsIntegration } from './integrations/normalizepaths';

packages/deno/src/integrations/knex.ts

@@ -0,0 +1,34 @@
+import { knexChannelIntegration } from '@sentry/server-utils/orchestrion';
+import type { Integration, IntegrationFn } from '@sentry/core';
+import { defineIntegration, extendIntegration } from '@sentry/core';
+import { setAsyncLocalStorageAsyncContextStrategy } from '../async';
+
+const INTEGRATION_NAME = 'DenoKnex' as const;
+
+/**
+ * Create spans for `knex` queries under Deno.
+ *
+ * `knex` channels are injected by the orchestrion runtime hook at load time.
+ * The `@sentry/deno/import` loader must be active for this integration to
+ * record anything.
+ *
+ * The channel-subscription logic is shared with the other server runtimes in
+ * `@sentry/server-utils`. This just installs Deno's
+ * `AsyncLocalStorage` context strategy (so spans nest under the active
+ * span and survive knex's internal callback dispatch) before delegating.
+ */
+const _denoKnexIntegration = (() => {
+  const inner = knexChannelIntegration();
+
+  return extendIntegration(inner, {
+    name: INTEGRATION_NAME,
+    setupOnce() {
+      setAsyncLocalStorageAsyncContextStrategy();
+    },
+  });
+}) satisfies IntegrationFn;
+
+export const denoKnexIntegration = defineIntegration(_denoKnexIntegration) as () => Integration & {
+  name: 'DenoKnex';
+  setupOnce: () => void;
+};

packages/node/src/integrations/tracing/knex/index.ts

@@ -2,6 +2,7 @@ import { KnexInstrumentation } from './vendored/instrumentation';
 import type { IntegrationFn } from '@sentry/core';
 import { defineIntegration } from '@sentry/core';
 import { generateInstrumentOnce } from '@sentry/node-core';
+import { isOrchestrionInjected, knexChannelIntegration } from '@sentry/server-utils/orchestrion';
 
 const INTEGRATION_NAME = 'Knex' as const;
 
@@ -11,7 +12,14 @@ const _knexIntegration = (() => {
   return {
     name: INTEGRATION_NAME,
     setupOnce() {
-      instrumentKnex();
+      // Prefer the diagnostics-channel subscriber when orchestrion injected its channels; otherwise
+      // fall back to the vendored OTel instrumentation. `isOrchestrionInjected()` is only reliable by
+      // `setupOnce` (the runtime injection runs during `Sentry.init()`, after integrations are built).
+      if (isOrchestrionInjected()) {
+        knexChannelIntegration().setupOnce?.();
+      } else {
+        instrumentKnex();
+      }
     },
   };
 }) satisfies IntegrationFn;