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

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;