feat(mysql2): Instrument mysql2 >= 3.20.0 via native tracing channels

dev-packages/node-integration-tests/suites/tracing/mysql2-tracing-channel/docker-compose.yml

@@ -0,0 +1,19 @@
+services:
+  db:
+    image: mysql:8
+    restart: always
+    container_name: integration-tests-mysql2-dc
+    ports:
+      - '3308:3306'
+    environment:
+      MYSQL_ROOT_PASSWORD: password
+    healthcheck:
+      # `mysqladmin ping` reports "alive" even during MySQL's init bootstrap (it treats
+      # access-denied as alive), so `--wait` can return before the real server and root
+      # password are ready, and early connections get dropped ("server closed the
+      # connection"). Run an authenticated query instead so readiness gates on the real server.
+      test: ['CMD-SHELL', 'mysql -h 127.0.0.1 -uroot -ppassword -e "SELECT 1"']
+      interval: 2s
+      timeout: 3s
+      retries: 30
+      start_period: 10s

dev-packages/node-integration-tests/suites/tracing/mysql2-tracing-channel/instrument.mjs

@@ -0,0 +1,9 @@
+import * as Sentry from '@sentry/node';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  release: '1.0',
+  tracesSampleRate: 1.0,
+  transport: loggingTransport,
+});

dev-packages/node-integration-tests/suites/tracing/mysql2-tracing-channel/scenario.mjs

@@ -0,0 +1,56 @@
+import * as Sentry from '@sentry/node';
+import mysql from 'mysql2/promise';
+
+const CONNECT_CONFIG = {
+  user: 'root',
+  password: 'password',
+  host: 'localhost',
+  port: 3308,
+};
+
+// `docker compose up --wait` gates on the healthcheck, but MySQL keeps finalizing
+// for a short window afterwards and drops early handshakes ("server closed the
+// connection"). Retry the initial connect so the suite doesn't flake on that window.
+// A failed attempt still publishes on mysql2's `connect` channel, so the test asserts
+// its envelopes with `.unordered()` to tolerate the transient connect transaction.
+async function connectWithRetry(attempts = 15, delayMs = 500) {
+  let lastError;
+  for (let attempt = 0; attempt < attempts; attempt++) {
+    try {
+      return await mysql.createConnection(CONNECT_CONFIG);
+    } catch (error) {
+      lastError = error;
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+  }
+
+  throw lastError;
+}
+
+async function run() {
+  // Yield a microtick so the DC subscriber (deferred via Promise.resolve().then)
+  // is registered before mysql2 publishes on its native TracingChannels.
+  await Promise.resolve();
+
+  const connection = await connectWithRetry();
+
+  await Sentry.startSpan(
+    {
+      op: 'transaction',
+      name: 'Test Transaction',
+    },
+    async () => {
+      await connection.query('SELECT 1 + 1 AS solution');
+      // A literal value, to assert it is redacted out of `db.query.text`.
+      await connection.query("SELECT 'super-secret' AS leaked");
+      // `execute` keeps `?` placeholders (prepared statements).
+      await connection.execute('SELECT ? AS answer', [42]);
+      // A failing query should produce a span with an error status.
+      await connection.query('SELECT * FROM does_not_exist').catch(() => {});
+    },
+  );
+
+  await connection.end();
+}
+
+run();

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

@@ -0,0 +1,116 @@
+import { afterAll, expect } from 'vitest';
+import { conditionalTest } from '../../../utils';
+import { cleanupChildProcesses, createEsmAndCjsTests } from '../../../utils/runner';
+
+// mysql2 >= 3.20.0 publishes its operations via `node:diagnostics_channel`, so the SDK subscribes
+// to those channels (`subscribeMysql2DiagnosticChannels`) instead of monkey-patching. This suite
+// pins `^3.20.0` and asserts the diagnostics-channel path: stable OTel DB semconv attributes,
+// redacted query text, and that the legacy IITM patcher (gated to `< 3.20.0`) does NOT also fire.
+// `TracingChannel` is only reliable on Node >= 20, so this suite is skipped on older Node.
+conditionalTest({ min: 20 })('mysql2 tracing channel Test', () => {
+  afterAll(() => {
+    cleanupChildProcesses();
+  });
+
+  const expectedQuerySpan = (queryText: string) =>
+    expect.objectContaining({
+      description: queryText,
+      op: 'db',
+      origin: 'auto.db.mysql2.diagnostic_channel',
+      data: expect.objectContaining({
+        'sentry.origin': 'auto.db.mysql2.diagnostic_channel',
+        'db.system.name': 'mysql',
+        'db.operation.name': 'SELECT',
+        'db.query.text': queryText,
+        'server.address': 'localhost',
+        'server.port': 3308,
+      }),
+    });
+
+  const EXPECTED_TRANSACTION = {
+    transaction: 'Test Transaction',
+    spans: expect.arrayContaining([
+      expectedQuerySpan('SELECT ? + ? AS solution'),
+      // the inlined literal is redacted out of `db.query.text`
+      expectedQuerySpan('SELECT ? AS leaked'),
+      // `execute` keeps the `?` placeholder
+      expectedQuerySpan('SELECT ? AS answer'),
+      // a failing query produces a span with an error status
+      expect.objectContaining({
+        description: 'SELECT * FROM does_not_exist',
+        op: 'db',
+        status: 'internal_error',
+        origin: 'auto.db.mysql2.diagnostic_channel',
+      }),
+    ]),
+  };
+
+  const EXPECTED_CONNECT = {
+    transaction: 'mysql2.connect',
+  };
+
+  createEsmAndCjsTests(
+    __dirname,
+    'scenario.mjs',
+    'instrument.mjs',
+    (createTestRunner, test) => {
+      test('subscribes to mysql2 >= 3.20.0 diagnostics channels with stable semconv attributes', async () => {
+        await createTestRunner()
+          .withDockerCompose({ workingDirectory: [__dirname] })
+          .expect({ transaction: EXPECTED_CONNECT })
+          .expect({ transaction: EXPECTED_TRANSACTION })
+          // The scenario retries the initial connect (MySQL drops early handshakes right
+          // after the healthcheck passes), and each failed attempt emits a `mysql2.connect`
+          // transaction, so envelope order isn't guaranteed.
+          .unordered()
+          .start()
+          .completed();
+      }, 30_000);
+
+      test('does not double-instrument: the legacy IITM mysql2 patcher does not fire on 3.20.0+', async () => {
+        await createTestRunner()
+          .withDockerCompose({ workingDirectory: [__dirname] })
+          .expect({ transaction: EXPECTED_CONNECT })
+          .expect({
+            transaction: event => {
+              // With `.unordered()`, pin the assertion to the query transaction so a stray
+              // connect transaction (from a retried handshake) can't satisfy it.
+              expect(event.transaction).toBe('Test Transaction');
+              const spans = event.spans || [];
+              // The monkey-patch path (origin `auto.db.otel.mysql2`) must be inactive on 3.20.0+.
+              expect(spans.find(span => span.origin === 'auto.db.otel.mysql2')).toBeUndefined();
+              // ...while the diagnostics-channel path is active.
+              expect(spans.find(span => span.origin === 'auto.db.mysql2.diagnostic_channel')).toBeDefined();
+            },
+          })
+          .unordered()
+          .start()
+          .completed();
+      }, 30_000);
+
+      test('never leaks raw values into db.query.text', async () => {
+        await createTestRunner()
+          .withDockerCompose({ workingDirectory: [__dirname] })
+          .expect({ transaction: EXPECTED_CONNECT })
+          .expect({
+            transaction: event => {
+              // With `.unordered()`, pin the assertion to the query transaction so an empty
+              // connect transaction (from a retried handshake) can't vacuously satisfy it.
+              expect(event.transaction).toBe('Test Transaction');
+              const spans = event.spans || [];
+              for (const span of spans) {
+                const queryText = span.data?.['db.query.text'];
+                if (typeof queryText === 'string') {
+                  expect(queryText).not.toContain('super-secret');
+                }
+              }
+            },
+          })
+          .unordered()
+          .start()
+          .completed();
+      }, 30_000);
+    },
+    { additionalDependencies: { mysql2: '^3.20.0' } },
+  );
+});

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

@@ -1,19 +1,22 @@
 import { MySQL2Instrumentation } from './vendored/instrumentation';
 import type { IntegrationFn } from '@sentry/core';
-import { defineIntegration } from '@sentry/core';
+import { defineIntegration, extendIntegration } from '@sentry/core';
 import { generateInstrumentOnce } from '@sentry/node-core';
+import { mysql2Integration as mysql2ChannelIntegration } from '@sentry/server-utils';
 
 const INTEGRATION_NAME = 'Mysql2' as const;
 
 export const instrumentMysql2 = generateInstrumentOnce(INTEGRATION_NAME, () => new MySQL2Instrumentation());
 
 const _mysql2Integration = (() => {
-  return {
+  // The diagnostics_channel subscription (mysql2 >= 3.20.0) lives in server-utils so it is shared
+  // across server runtimes; we extend it here to also run the vendored OTel patcher for mysql2 < 3.20.0.
+  return extendIntegration(mysql2ChannelIntegration(), {
     name: INTEGRATION_NAME,
     setupOnce() {
       instrumentMysql2();
     },
-  };
+  });
 }) satisfies IntegrationFn;
 
 /**

packages/node/src/integrations/tracing/mysql2/vendored/instrumentation.ts

@@ -29,7 +29,10 @@ import { getConnectionAttributes, getConnectionPrototypeToInstrument, getQueryTe
 const PACKAGE_NAME = '@sentry/instrumentation-mysql2';
 const ORIGIN = 'auto.db.otel.mysql2';
 
-const supportedVersions = ['>=1.4.2 <4'];
+// mysql2 >= 3.20.0 publishes via diagnostics_channel and is instrumented by
+// `subscribeMysql2DiagnosticChannels` instead, so this IITM patcher must not
+// overlap it — otherwise every query would emit two mysql2 spans.
+const supportedVersions = ['>=1.4.2 <3.20.0'];
 
 // The raw imported `mysql2` module exposes the `format` helper used to render
 // parameterized queries. Typed shallowly since it is only read internally.

packages/server-utils/src/index.ts

@@ -5,6 +5,7 @@
  */
 
 export { mongooseIntegration } from './mongoose';
+export { mysql2Integration } from './mysql2';
 export {
   IOREDIS_DC_CHANNEL_COMMAND,
   IOREDIS_DC_CHANNEL_CONNECT,

packages/server-utils/src/mysql2/index.ts

@@ -0,0 +1,30 @@
+import { defineIntegration, type IntegrationFn, waitForTracingChannelBinding } from '@sentry/core';
+import * as dc from 'node:diagnostics_channel';
+import { subscribeMysql2DiagnosticChannels } from './mysql2-dc-subscriber';
+
+const _mysql2Integration = (() => {
+  return {
+    name: 'Mysql2',
+    setupOnce() {
+      // Bail on Node <= 18.18.0, where `tracingChannel` does not exist.
+      if (!dc.tracingChannel) {
+        return;
+      }
+
+      // Subscribe to mysql2's native tracing channels (mysql2 >= 3.20.0).
+      // This is a no-op on versions that don't publish to the channels, so it is always safe to call.
+      waitForTracingChannelBinding(() => {
+        subscribeMysql2DiagnosticChannels(dc.tracingChannel);
+      });
+    },
+  };
+}) satisfies IntegrationFn;
+
+/**
+ * Auto-instrument the [mysql2](https://www.npmjs.com/package/mysql2) library via its native
+ * `node:diagnostics_channel` tracing channels (mysql2 >= 3.20.0).
+ *
+ * On older mysql2 versions the channels are never published to, so this integration is inert and
+ * the vendored OTel instrumentation (gated to `< 3.20.0`) handles instrumentation instead.
+ */
+export const mysql2Integration = defineIntegration(_mysql2Integration);