Skip to content

ref(node): Streamline mysql2 instrumentation #21509

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
logaretm merged 4 commits into from
Jun 15, 2026
Merged

ref(node): Streamline mysql2 instrumentation #21509

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b9b8594
ref(node): Streamline mysql2 instrumentation
logaretm Jun 12, 2026
f03121f
test(node): Cover mysql2 execute/error in real suite, drop fake patch…
logaretm Jun 15, 2026
33dea13
test(node): Fix mysql2 span descriptions to full statement
logaretm Jun 15, 2026
fd777c9
ref(node): Inline InstrumentationConfig, drop mysql2 vendored types file
logaretm Jun 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion .oxlintrc.base.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,9 @@
"**/integrations/tracing/fastify/vendored/**/*.ts"
],
"rules": {
"typescript/no-explicit-any": "off"
"typescript/no-explicit-any": "off",
"no-unsafe-member-access": "off",

@JPeer264 JPeer264 Jun 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

l: Is it necessary to add these (especially for all vendored integrations)?

@logaretm logaretm Jun 15, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was added in #21481 so depending on whichever gets merged first the other one will drop, this is a one time change only.

"no-this-alias": "off"
}
},
{
Expand Down
4 changes: 4 additions & 0 deletions dev-packages/node-integration-tests/suites/tracing/mysql2/scenario.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,10 @@ mysql
async _ => {
await connection.query('SELECT 1 + 1 AS solution');
await connection.query('SELECT NOW()', ['1', '2']);
// `execute` is instrumented the same way as `query`
await connection.execute('SELECT 42 AS answer');
// a failing query should produce a span with an error status
await connection.query('SELECT * FROM does_not_exist').catch(() => {});
},
);
});
25 changes: 25 additions & 0 deletions dev-packages/node-integration-tests/suites/tracing/mysql2/test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,10 @@ describe('mysql2 auto instrumentation', () => {
expect.objectContaining({
description: 'SELECT 1 + 1 AS solution',
op: 'db',
origin: 'auto.db.otel.mysql2',
data: expect.objectContaining({
'db.system': 'mysql',
'db.statement': 'SELECT 1 + 1 AS solution',
'net.peer.name': 'localhost',
'net.peer.port': 3306,
'db.user': 'root',
Expand All @@ -22,13 +24,36 @@ describe('mysql2 auto instrumentation', () => {
expect.objectContaining({
description: 'SELECT NOW()',
op: 'db',
origin: 'auto.db.otel.mysql2',
data: expect.objectContaining({
'db.system': 'mysql',
'db.statement': 'SELECT NOW()',
'net.peer.name': 'localhost',
'net.peer.port': 3306,
'db.user': 'root',
}),
}),
// `execute` is instrumented the same way as `query`
expect.objectContaining({
description: 'SELECT 42 AS answer',
op: 'db',
origin: 'auto.db.otel.mysql2',
data: expect.objectContaining({
'db.system': 'mysql',
'db.statement': 'SELECT 42 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.otel.mysql2',

@cursor cursor Bot Jun 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrong error status assertion

Medium Severity

The failing-query expectation uses status: 'internal_error', but instrumentation sets span status with message: err.message. For a missing table, MySQL supplies a concrete message, so getStatusMessage returns that text rather than internal_error.

Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 33dea13. Configure here.

data: expect.objectContaining({
'db.system': 'mysql',
'db.statement': 'SELECT * FROM does_not_exist',
}),
}),
]),
};

Expand Down
12 changes: 2 additions & 10 deletions packages/node/src/integrations/tracing/mysql2/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,19 +1,11 @@
import { MySQL2Instrumentation } from './vendored/instrumentation';
import type { IntegrationFn } from '@sentry/core';
import { defineIntegration } from '@sentry/core';
import { addOriginToSpan, generateInstrumentOnce } from '@sentry/node-core';
import { generateInstrumentOnce } from '@sentry/node-core';

const INTEGRATION_NAME = 'Mysql2';

export const instrumentMysql2 = generateInstrumentOnce(
INTEGRATION_NAME,
() =>
new MySQL2Instrumentation({
responseHook(span) {
addOriginToSpan(span, 'auto.db.otel.mysql2');
},
}),
);
export const instrumentMysql2 = generateInstrumentOnce(INTEGRATION_NAME, () => new MySQL2Instrumentation());

const _mysql2Integration = (() => {
return {
Expand Down
139 changes: 43 additions & 96 deletions packages/node/src/integrations/tracing/mysql2/vendored/instrumentation.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,75 +18,59 @@
* - Upstream version: @opentelemetry/instrumentation-mysql2@0.64.0
* - Types from 'mysql2' inlined as simplified interfaces
* - Minor TypeScript strictness adjustments for this repository's compiler settings
* - Refactored to use Sentry's span APIs instead of OpenTelemetry tracing APIs
*/
/* eslint-disable */

import * as api from '@opentelemetry/api';
import { SDK_VERSION } from '@sentry/core';
import {
InstrumentationBase,
InstrumentationNodeModuleDefinition,
isWrapped,
safeExecuteInTheMiddle,
SemconvStability,
semconvStabilityFromStr,
} from '@opentelemetry/instrumentation';

import { SpanKind } from '@opentelemetry/api';
import type { InstrumentationConfig } from '@opentelemetry/instrumentation';
import { InstrumentationBase, InstrumentationNodeModuleDefinition, isWrapped } from '@opentelemetry/instrumentation';
import type { SpanAttributes } from '@sentry/core';
import { SDK_VERSION, SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, SPAN_STATUS_ERROR, startInactiveSpan } from '@sentry/core';
import { InstrumentationNodeModuleFile } from '../../InstrumentationNodeModuleFile';
import { DB_SYSTEM_VALUE_MYSQL, ATTR_DB_STATEMENT, ATTR_DB_SYSTEM } from './semconv';
import { addSqlCommenterComment } from '../../utils/sql-common';
import type { Connection, Query, QueryOptions, QueryError, FieldPacket, FormatFunction } from './mysql2-types';
import { MySQL2InstrumentationConfig } from './types';
import type { Connection, FormatFunction, Query, QueryError, QueryOptions } from './mysql2-types';
import { ATTR_DB_STATEMENT, ATTR_DB_SYSTEM, DB_SYSTEM_VALUE_MYSQL } from './semconv';
import { getConnectionAttributes, getConnectionPrototypeToInstrument, getQueryText, getSpanName, once } from './utils';
import {
ATTR_DB_QUERY_TEXT,
ATTR_DB_SYSTEM_NAME,
DB_SYSTEM_NAME_VALUE_MYSQL,
} from '@opentelemetry/semantic-conventions';

const PACKAGE_NAME = '@sentry/instrumentation-mysql2';
const ORIGIN = 'auto.db.otel.mysql2';

@JPeer264 JPeer264 Jun 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

l: I don't think that we should add otel in it, as it comes from us - but it was here before - so it might be better to keep it as is and change it later?

Suggested change
const ORIGIN = 'auto.db.otel.mysql2';
const ORIGIN = 'auto.db.mysql2';

@mydea mydea Jun 15, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd opt to change all of these to something non-otel in v11, for now this indicates that it comes from otel instrumentation, which it still is (just our own)

@logaretm logaretm Jun 15, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yea, my goal was not to change anything in terms of output. So I try to keep all attrs intact.


const supportedVersions = ['>=1.4.2 <4'];

export class MySQL2Instrumentation extends InstrumentationBase<MySQL2InstrumentationConfig> {
private _netSemconvStability!: SemconvStability;
private _dbSemconvStability!: SemconvStability;
// The raw imported `mysql2` module exposes the `format` helper used to render
// parameterized queries. Typed shallowly since it is only read internally.
type MySQL2Module = { format?: FormatFunction; [key: string]: unknown };

constructor(config: MySQL2InstrumentationConfig = {}) {
export class MySQL2Instrumentation extends InstrumentationBase<InstrumentationConfig> {
public constructor(config: InstrumentationConfig = {}) {
super(PACKAGE_NAME, SDK_VERSION, config);
this._setSemconvStabilityFromEnv();
}

private _setSemconvStabilityFromEnv() {
this._netSemconvStability = semconvStabilityFromStr('http', process.env.OTEL_SEMCONV_STABILITY_OPT_IN);
this._dbSemconvStability = semconvStabilityFromStr('database', process.env.OTEL_SEMCONV_STABILITY_OPT_IN);
}

protected init() {
protected init(): InstrumentationNodeModuleDefinition[] {
let format: FormatFunction | undefined;
function setFormatFunction(moduleExports: any) {
function setFormatFunction(moduleExports: MySQL2Module): void {
if (!format && moduleExports.format) {
format = moduleExports.format;
}
}
const patch = (ConnectionPrototype: Connection) => {
const patch = (ConnectionPrototype: Connection): void => {
if (isWrapped(ConnectionPrototype.query)) {
this._unwrap(ConnectionPrototype, 'query');
}
this._wrap(ConnectionPrototype, 'query', this._patchQuery(format, false) as any);
this._wrap(ConnectionPrototype, 'query', this._patchQuery(format) as any);
if (isWrapped(ConnectionPrototype.execute)) {
this._unwrap(ConnectionPrototype, 'execute');
}
this._wrap(ConnectionPrototype, 'execute', this._patchQuery(format, true) as any);
this._wrap(ConnectionPrototype, 'execute', this._patchQuery(format) as any);
};
const unpatch = (ConnectionPrototype: Connection) => {
const unpatch = (ConnectionPrototype: Connection): void => {
this._unwrap(ConnectionPrototype, 'query');
this._unwrap(ConnectionPrototype, 'execute');
};
return [
new InstrumentationNodeModuleDefinition(
'mysql2',
supportedVersions,
(moduleExports: any) => {
(moduleExports: MySQL2Module) => {
setFormatFunction(moduleExports);
return moduleExports;
},
Expand All @@ -95,7 +79,7 @@ export class MySQL2Instrumentation extends InstrumentationBase<MySQL2Instrumenta
new InstrumentationNodeModuleFile(
'mysql2/promise.js',
supportedVersions,
(moduleExports: any) => {
(moduleExports: MySQL2Module) => {
setFormatFunction(moduleExports);
return moduleExports;
},
Expand All @@ -120,9 +104,9 @@ export class MySQL2Instrumentation extends InstrumentationBase<MySQL2Instrumenta
];
}

private _patchQuery(format: FormatFunction | undefined, isPrepared: boolean) {
private _patchQuery(format: FormatFunction | undefined) {
const thisPlugin = this;
return (originalQuery: Function): Function => {
const thisPlugin = this;
return function query(
this: Connection,
query: string | Query | QueryOptions,
Expand All @@ -135,61 +119,24 @@ export class MySQL2Instrumentation extends InstrumentationBase<MySQL2Instrumenta
} else if (arguments[2]) {
values = [_valuesOrCallback];
}
const { maskStatement, maskStatementHook, responseHook } = thisPlugin.getConfig();

@cursor cursor Bot Jun 15, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Error span status mismatches test

Medium Severity

Failed queries set the span status message to the raw MySQL err.message, while the new integration test expects status: 'internal_error'. Serialized span status uses that message verbatim, so the assertion and runtime behavior introduced in this change do not align.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit fd777c9. Configure here.

const attributes: api.Attributes = getConnectionAttributes(
this.config,
thisPlugin._dbSemconvStability,
thisPlugin._netSemconvStability,
);
const dbQueryText = getQueryText(query, format, values, maskStatement, maskStatementHook);
if (thisPlugin._dbSemconvStability & SemconvStability.OLD) {
attributes[ATTR_DB_SYSTEM] = DB_SYSTEM_VALUE_MYSQL;
attributes[ATTR_DB_STATEMENT] = dbQueryText;
}
if (thisPlugin._dbSemconvStability & SemconvStability.STABLE) {
attributes[ATTR_DB_SYSTEM_NAME] = DB_SYSTEM_NAME_VALUE_MYSQL;
attributes[ATTR_DB_QUERY_TEXT] = dbQueryText;
}

const span = thisPlugin.tracer.startSpan(getSpanName(query), {
kind: api.SpanKind.CLIENT,
const attributes: SpanAttributes = {
...getConnectionAttributes(this.config),
[ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_MYSQL,
[ATTR_DB_STATEMENT]: getQueryText(query, format, values),
[SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: ORIGIN,
};

const span = startInactiveSpan({
name: getSpanName(query),
kind: SpanKind.CLIENT,
Comment thread
logaretm marked this conversation as resolved.
attributes,
});
Comment on lines -151 to 158

@sentry sentry Bot Jun 15, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: The mysql2 instrumentation incorrectly uses the 'result' event to end spans for streaming queries, causing premature span closure for multi-row queries and span leaks for zero-row queries.
Severity: HIGH

Suggested Fix

To correctly measure the full duration of the streaming query, the event listener should be bound to the 'end' event instead of the 'result' event. Change .once('result', () => { endSpan(); }); to .once('end', () => { endSpan(); });. This ensures the span is only closed after all rows have been received.

Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.

Location:
packages/node/src/integrations/tracing/mysql2/vendored/instrumentation.ts#L151-L158

Potential issue: The `mysql2` instrumentation for streaming queries incorrectly uses the
`'result'` event to end a trace span. The `'result'` event fires for each row returned
by the query. For queries that return multiple rows, this causes the span to end
prematurely after the first row, resulting in an inaccurate duration measurement. For
queries that return zero rows, the `'result'` event never fires, causing the span to
never be closed and leading to a resource leak.

Did we get this right? 👍 / 👎 to inform future reviews.

@logaretm logaretm Jun 15, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

While this looks technically correct, we need to preserve the upstream instrumentation and track this individually later.


if (!isPrepared && thisPlugin.getConfig().addSqlCommenterCommentToQueries) {
arguments[0] = query =
typeof query === 'string'
? addSqlCommenterComment(span, query)
: Object.assign(query, {
sql: addSqlCommenterComment(span, query.sql),
});
}

const endSpan = once((err?: any, results?: any) => {
const endSpan = once((err?: QueryError | null) => {
if (err) {
span.setStatus({
code: api.SpanStatusCode.ERROR,
message: err.message,
});
} else {
if (typeof responseHook === 'function') {
safeExecuteInTheMiddle(
() => {
responseHook(span, {
queryResults: results,
});
},
err => {
if (err) {
thisPlugin._diag.warn('Failed executing responseHook', err);
}
},
true,
);
}
span.setStatus({ code: SPAN_STATUS_ERROR, message: err.message });
}

span.end();
});

Expand All @@ -204,8 +151,8 @@ export class MySQL2Instrumentation extends InstrumentationBase<MySQL2Instrumenta
.once('error', (err: any) => {
endSpan(err);
})
.once('result', (results: any) => {
endSpan(undefined, results);
.once('result', () => {
endSpan();
});

return streamableQuery;
Expand All @@ -222,11 +169,11 @@ export class MySQL2Instrumentation extends InstrumentationBase<MySQL2Instrumenta
};
}

private _patchCallbackQuery(endSpan: Function) {
private _patchCallbackQuery(endSpan: (err?: QueryError | null) => void) {
return (originalCallback: Function) => {
return function (err: QueryError | null, results?: any, _fields?: FieldPacket[]) {
endSpan(err, results);
return originalCallback(...arguments);
return function (...args: [err: QueryError | null, ...rest: unknown[]]) {
endSpan(args[0]);
return originalCallback(...args);
};
};
}
Expand Down
1 change: 0 additions & 1 deletion packages/node/src/integrations/tracing/mysql2/vendored/semconv.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,6 @@
* - Vendored from: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/15ef7506553f631ea4181391e0c5725a56f0d082/packages/instrumentation-mysql2
* - Upstream version: @opentelemetry/instrumentation-mysql2@0.64.0
*/
/* eslint-disable */

export const ATTR_DB_CONNECTION_STRING = 'db.connection_string' as const;
export const ATTR_DB_NAME = 'db.name' as const;
Expand Down
42 changes: 0 additions & 42 deletions packages/node/src/integrations/tracing/mysql2/vendored/types.ts
View file
Open in desktop

This file was deleted.

Loading
Loading