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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);

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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);

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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);

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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);

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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);

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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);

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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);

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.
+// The connect happens outside an active span, so the subscriber leaves it
+// uninstrumented and no connect transaction is emitted.
+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,99 @@
+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',
+ }),
+ ]),
+ };
+
+ 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_TRANSACTION })
+ .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: event => {
+ 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();
+ },
+ })
+ .start()
+ .completed();
+ }, 30_000);
+
+ test('never leaks raw values into db.query.text', async () => {
+ await createTestRunner()
+ .withDockerCompose({ workingDirectory: [__dirname] })
+ .expect({
+ transaction: event => {
+ 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');
+ }
+ }
+ },
+ })
+ .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 { redisIntegration, type RedisDiagnosticChannelsOptions } from './redis';
 export type { RedisDiagnosticChannelResponseHook } from './redis/redis-dc-subscriber';
 export { defaultDbStatementSerializer } from './redis/redis-statement-serializer';

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);