From 98fac09a3897a50c7af7b28df1102a3b5770f95f Mon Sep 17 00:00:00 2001 From: David Luna Date: Fri, 19 Apr 2024 23:48:07 +0200 Subject: [PATCH] refactor(instr-mysql2): use exported strings for attributes (#2115) - Update @opentelemetry/semantic-conventions to ^1.22 - Replace SemanticAttributes.* with exported strings SEMATTRS_* - Update README with new semantic convention package version and key Refs: #2025 --- package-lock.json | 4 +- .../README.md | 16 ++++++++ .../package.json | 2 +- .../src/instrumentation.ts | 13 +++--- .../src/utils.ts | 40 +++++++++---------- .../test/mysql.test.ts | 31 +++++++------- 6 files changed, 58 insertions(+), 48 deletions(-) diff --git a/package-lock.json b/package-lock.json index adb9293cdf..eaf2bb882c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -38231,7 +38231,7 @@ "license": "Apache-2.0", "dependencies": { "@opentelemetry/instrumentation": "^0.50.0", - "@opentelemetry/semantic-conventions": "^1.0.0", + "@opentelemetry/semantic-conventions": "^1.22.0", "@opentelemetry/sql-common": "^0.40.0" }, "devDependencies": { @@ -46621,7 +46621,7 @@ "@opentelemetry/contrib-test-utils": "^0.38.0", "@opentelemetry/instrumentation": "^0.50.0", "@opentelemetry/sdk-trace-base": "^1.8.0", - "@opentelemetry/semantic-conventions": "^1.0.0", + "@opentelemetry/semantic-conventions": "^1.22.0", "@opentelemetry/sql-common": "^0.40.0", "@types/mocha": "7.0.2", "@types/node": "18.6.5", diff --git a/plugins/node/opentelemetry-instrumentation-mysql2/README.md b/plugins/node/opentelemetry-instrumentation-mysql2/README.md index 04f15355ef..a0f3c73658 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql2/README.md +++ b/plugins/node/opentelemetry-instrumentation-mysql2/README.md @@ -49,6 +49,22 @@ You can set the following instrumentation options: | `responseHook` | `MySQL2InstrumentationExecutionResponseHook` (function) | Function for adding custom attributes from db response | | `addSqlCommenterCommentToQueries` | `boolean` | If true, adds [sqlcommenter](https://github.com/open-telemetry/opentelemetry-sqlcommenter) specification compliant comment to queries with tracing context (default false). _NOTE: A comment will not be added to queries that already contain `--` or `/* ... */` in them, even if these are not actually part of comments_ | +## Semantic Conventions + +This package uses `@opentelemetry/semantic-conventions` version `1.22+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md) + +Attributes collected: + +| Attribute | Short Description | +| ----------------------- | ------------------------------------------------------------------------------ | +| `db.connection_string` | The connection string used to connect to the database. | +| `db.name` | This attribute is used to report the name of the database being accessed. | +| `db.statement` | The database statement being executed. | +| `db.system` | An identifier for the database management system (DBMS) product being used. | +| `db.user` | Username for accessing the database. | +| `net.peer.name` | Remote hostname or similar. | +| `net.peer.port` | Remote port number. | + ## Useful links - For more information on OpenTelemetry, visit: diff --git a/plugins/node/opentelemetry-instrumentation-mysql2/package.json b/plugins/node/opentelemetry-instrumentation-mysql2/package.json index b20fb7aaf6..5d7d885d02 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql2/package.json +++ b/plugins/node/opentelemetry-instrumentation-mysql2/package.json @@ -62,7 +62,7 @@ }, "dependencies": { "@opentelemetry/instrumentation": "^0.50.0", - "@opentelemetry/semantic-conventions": "^1.0.0", + "@opentelemetry/semantic-conventions": "^1.22.0", "@opentelemetry/sql-common": "^0.40.0" }, "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-mysql2#readme" diff --git a/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts index ea792f8025..2d79311bcb 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts +++ b/plugins/node/opentelemetry-instrumentation-mysql2/src/instrumentation.ts @@ -22,8 +22,9 @@ import { safeExecuteInTheMiddle, } from '@opentelemetry/instrumentation'; import { - DbSystemValues, - SemanticAttributes, + DBSYSTEMVALUES_MYSQL, + SEMATTRS_DB_STATEMENT, + SEMATTRS_DB_SYSTEM, } from '@opentelemetry/semantic-conventions'; import { addSqlCommenterComment } from '@opentelemetry/sql-common'; import type * as mysqlTypes from 'mysql2'; @@ -40,7 +41,7 @@ type formatType = typeof mysqlTypes.format; export class MySQL2Instrumentation extends InstrumentationBase { static readonly COMMON_ATTRIBUTES = { - [SemanticAttributes.DB_SYSTEM]: DbSystemValues.MYSQL, + [SEMATTRS_DB_SYSTEM]: DBSYSTEMVALUES_MYSQL, }; constructor(config?: MySQL2InstrumentationConfig) { @@ -115,11 +116,7 @@ export class MySQL2Instrumentation extends InstrumentationBase { attributes: { ...MySQL2Instrumentation.COMMON_ATTRIBUTES, ...getConnectionAttributes(this.config), - [SemanticAttributes.DB_STATEMENT]: getDbStatement( - query, - format, - values - ), + [SEMATTRS_DB_STATEMENT]: getDbStatement(query, format, values), }, }); diff --git a/plugins/node/opentelemetry-instrumentation-mysql2/src/utils.ts b/plugins/node/opentelemetry-instrumentation-mysql2/src/utils.ts index 82333c109f..cfd9f2ef0f 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql2/src/utils.ts +++ b/plugins/node/opentelemetry-instrumentation-mysql2/src/utils.ts @@ -14,8 +14,14 @@ * limitations under the License. */ -import { SpanAttributes } from '@opentelemetry/api'; -import { SemanticAttributes } from '@opentelemetry/semantic-conventions'; +import { Attributes } from '@opentelemetry/api'; +import { + SEMATTRS_DB_CONNECTION_STRING, + SEMATTRS_DB_NAME, + SEMATTRS_DB_USER, + SEMATTRS_NET_PEER_NAME, + SEMATTRS_NET_PEER_PORT, +} from '@opentelemetry/semantic-conventions'; /* Following types declare an expectation on mysql2 types and define a subset we @@ -42,35 +48,27 @@ interface Config { connectionConfig?: Config; } /** - * Get an SpanAttributes map from a mysql connection config object + * Get an Attributes map from a mysql connection config object * * @param config ConnectionConfig */ -export function getConnectionAttributes(config: Config): SpanAttributes { +export function getConnectionAttributes(config: Config): Attributes { const { host, port, database, user } = getConfig(config); const portNumber = parseInt(port, 10); if (!isNaN(portNumber)) { return { - [SemanticAttributes.NET_PEER_NAME]: host, - [SemanticAttributes.NET_PEER_PORT]: portNumber, - [SemanticAttributes.DB_CONNECTION_STRING]: getJDBCString( - host, - port, - database - ), - [SemanticAttributes.DB_NAME]: database, - [SemanticAttributes.DB_USER]: user, + [SEMATTRS_NET_PEER_NAME]: host, + [SEMATTRS_NET_PEER_PORT]: portNumber, + [SEMATTRS_DB_CONNECTION_STRING]: getJDBCString(host, port, database), + [SEMATTRS_DB_NAME]: database, + [SEMATTRS_DB_USER]: user, }; } return { - [SemanticAttributes.NET_PEER_NAME]: host, - [SemanticAttributes.DB_CONNECTION_STRING]: getJDBCString( - host, - port, - database - ), - [SemanticAttributes.DB_NAME]: database, - [SemanticAttributes.DB_USER]: user, + [SEMATTRS_NET_PEER_NAME]: host, + [SEMATTRS_DB_CONNECTION_STRING]: getJDBCString(host, port, database), + [SEMATTRS_DB_NAME]: database, + [SEMATTRS_DB_USER]: user, }; } diff --git a/plugins/node/opentelemetry-instrumentation-mysql2/test/mysql.test.ts b/plugins/node/opentelemetry-instrumentation-mysql2/test/mysql.test.ts index 4c7a4bab23..7b2bfe74ee 100644 --- a/plugins/node/opentelemetry-instrumentation-mysql2/test/mysql.test.ts +++ b/plugins/node/opentelemetry-instrumentation-mysql2/test/mysql.test.ts @@ -18,8 +18,13 @@ import * as semver from 'semver'; import { context, trace, SpanStatusCode } from '@opentelemetry/api'; import { AsyncHooksContextManager } from '@opentelemetry/context-async-hooks'; import { - DbSystemValues, - SemanticAttributes, + DBSYSTEMVALUES_MYSQL, + SEMATTRS_DB_NAME, + SEMATTRS_DB_STATEMENT, + SEMATTRS_DB_SYSTEM, + SEMATTRS_DB_USER, + SEMATTRS_NET_PEER_NAME, + SEMATTRS_NET_PEER_PORT, } from '@opentelemetry/semantic-conventions'; import * as testUtils from '@opentelemetry/contrib-test-utils'; import { @@ -177,10 +182,7 @@ describe('mysql2@2.x', () => { query.on('end', () => { const spans = memoryExporter.getFinishedSpans(); assert.strictEqual(spans[0].name, 'SELECT'); - assert.strictEqual( - spans[0].attributes[SemanticAttributes.DB_STATEMENT], - sql - ); + assert.strictEqual(spans[0].attributes[SEMATTRS_DB_STATEMENT], sql); done(); }); }); @@ -198,7 +200,7 @@ describe('mysql2@2.x', () => { const spans = memoryExporter.getFinishedSpans(); assert.strictEqual(spans[0].name, 'SELECT'); assert.strictEqual( - spans[0].attributes[SemanticAttributes.DB_STATEMENT], + spans[0].attributes[SEMATTRS_DB_STATEMENT], query.sql ); done(); @@ -1215,16 +1217,13 @@ function assertSpan( values?: any, errorMessage?: string ) { + assert.strictEqual(span.attributes[SEMATTRS_DB_SYSTEM], DBSYSTEMVALUES_MYSQL); + assert.strictEqual(span.attributes[SEMATTRS_DB_NAME], database); + assert.strictEqual(span.attributes[SEMATTRS_NET_PEER_PORT], port); + assert.strictEqual(span.attributes[SEMATTRS_NET_PEER_NAME], host); + assert.strictEqual(span.attributes[SEMATTRS_DB_USER], user); assert.strictEqual( - span.attributes[SemanticAttributes.DB_SYSTEM], - DbSystemValues.MYSQL - ); - assert.strictEqual(span.attributes[SemanticAttributes.DB_NAME], database); - assert.strictEqual(span.attributes[SemanticAttributes.NET_PEER_PORT], port); - assert.strictEqual(span.attributes[SemanticAttributes.NET_PEER_NAME], host); - assert.strictEqual(span.attributes[SemanticAttributes.DB_USER], user); - assert.strictEqual( - span.attributes[SemanticAttributes.DB_STATEMENT], + span.attributes[SEMATTRS_DB_STATEMENT], mysqlTypes.format(sql, values) ); if (errorMessage) {