feat(instrumentation-mysql2): support net.* and database semconv migration (#3137)

This adds support for using `OTEL_SEMCONV_STABILITY_OPT_IN` for controlled migration to stable `net.*` and `db.*` semconv. The `net.*` attributes are controlled by the `http[/dup]` token in `OTEL_SEMCONV_STABILITY_OPT_IN` (as [discussed here](open-telemetry/opentelemetry-js#5663 (comment))) and `db.*` with the `database[/dup]` token.

Refs: open-telemetry/opentelemetry-js#5663
Refs: #2953
Co-authored-by: Marylia Gutierrez <maryliag@gmail.com>

Author: trentm

package-lock.json

@@ -54,19 +54,30 @@ You can set the following instrumentation options:
 
 ## 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)
+This instrumentation implements Semantic Conventions (semconv) v1.7.0. Since then, networking (in semconv v1.23.1) and database (in semconv v1.33.0) semantic conventions were stabilized. As of `@opentelemetry/instrumentation-mysql2@0.53.0` support has been added for migrating to the stable semantic conventions using the `OTEL_SEMCONV_STABILITY_OPT_IN` environment variable as follows:
+
+1. Upgrade to the latest version of this instrumentation package.
+2. Set `OTEL_SEMCONV_STABILITY_OPT_IN=http/dup,database/dup` to emit both old and stable semantic conventions. (The `http` token is used to control the `net.*` attributes, the `database` token to control to `db.*` attributes.)
+3. Modify alerts, dashboards, metrics, and other processes in your Observability system to use the stable semantic conventions.
+4. Set `OTEL_SEMCONV_STABILITY_OPT_IN=http,database` to emit only the stable semantic conventions.
+
+By default, if `OTEL_SEMCONV_STABILITY_OPT_IN` includes neither of the above tokens, the old v1.7.0 semconv is used.
+The intent is to provide an approximate 6 month time window for users of this instrumentation to migrate to the new database and networking semconv, after which a new minor version will use the new semconv by default and drop support for the old semconv.
+See [the HTTP migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/http-migration/) and the [database migration guide](https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/) for details.
 
 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.                                                            |
+| Old semconv            | Stable semconv   | Description |
+| ---------------------- | ---------------- | ----------- |
+| `db.connection_string` | Removed          | The connection string used to connect to the database. |
+| `db.name`              | Removed, integrated into the new `db.namespace` | The name of the database. |
+| `db.system`            | `db.system.name` | 'mysql' |
+| `db.statement`         | `db.query.text`  | The database query being executed. |
+| `db.user`              | Removed          | User used to connect to the database. |
+| (not included)         | `db.namespace`   | The name of the database, fully qualified within the server address and port. |
+| `net.peer.port`        | `server.port`    | Remote port number. |
+| `net.peer.name`        | `server.address` | Remote hostname or similar. |
+
 
 ## Useful links
 

packages/instrumentation-mysql2/README.md

@@ -68,6 +68,7 @@
   },
   "dependencies": {
     "@opentelemetry/instrumentation": "^0.206.0",
+    "@opentelemetry/semantic-conventions": "^1.33.0",
     "@opentelemetry/sql-common": "^0.41.2"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-mysql2#readme"

packages/instrumentation-mysql2/package.json

@@ -21,6 +21,8 @@ import {
   InstrumentationNodeModuleFile,
   isWrapped,
   safeExecuteInTheMiddle,
+  SemconvStability,
+  semconvStabilityFromStr,
 } from '@opentelemetry/instrumentation';
 import {
   DB_SYSTEM_VALUE_MYSQL,
@@ -33,24 +35,41 @@ import { MySQL2InstrumentationConfig } from './types';
 import {
   getConnectionAttributes,
   getConnectionPrototypeToInstrument,
-  getDbStatement,
+  getQueryText,
   getSpanName,
   once,
 } from './utils';
 /** @knipignore */
 import { PACKAGE_NAME, PACKAGE_VERSION } from './version';
+import {
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+  DB_SYSTEM_NAME_VALUE_MYSQL,
+} from '@opentelemetry/semantic-conventions';
 
 type formatType = typeof mysqlTypes.format;
 
 const supportedVersions = ['>=1.4.2 <4'];
 
 export class MySQL2Instrumentation extends InstrumentationBase<MySQL2InstrumentationConfig> {
-  static readonly COMMON_ATTRIBUTES = {
-    [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_MYSQL,
-  };
+  private _netSemconvStability!: SemconvStability;
+  private _dbSemconvStability!: SemconvStability;
 
   constructor(config: MySQL2InstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, config);
+    this._setSemconvStabilityFromEnv();
+  }
+
+  // Used for testing.
+  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() {
@@ -139,19 +158,31 @@ export class MySQL2Instrumentation extends InstrumentationBase<MySQL2Instrumenta
         }
         const { maskStatement, maskStatementHook, responseHook } =
           thisPlugin.getConfig();
+
+        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,
-          attributes: {
-            ...MySQL2Instrumentation.COMMON_ATTRIBUTES,
-            ...getConnectionAttributes(this.config),
-            [ATTR_DB_STATEMENT]: getDbStatement(
-              query,
-              format,
-              values,
-              maskStatement,
-              maskStatementHook
-            ),
-          },
+          attributes,
         });
 
         if (

packages/instrumentation-mysql2/src/instrumentation.ts

@@ -24,6 +24,12 @@ import {
 } from './semconv';
 import type * as mysqlTypes from 'mysql2';
 import { MySQL2InstrumentationQueryMaskingHook } from './types';
+import { SemconvStability } from '@opentelemetry/instrumentation';
+import {
+  ATTR_DB_NAMESPACE,
+  ATTR_SERVER_ADDRESS,
+  ATTR_SERVER_PORT,
+} from '@opentelemetry/semantic-conventions';
 
 type formatType = typeof mysqlTypes.format;
 
@@ -51,29 +57,44 @@ interface Config {
   user?: string;
   connectionConfig?: Config;
 }
+
 /**
  * Get an Attributes map from a mysql connection config object
  *
  * @param config ConnectionConfig
  */
-export function getConnectionAttributes(config: Config): Attributes {
+export function getConnectionAttributes(
+  config: Config,
+  dbSemconvStability: SemconvStability,
+  netSemconvStability: SemconvStability
+): Attributes {
   const { host, port, database, user } = getConfig(config);
+
+  const attrs: Attributes = {};
+  if (dbSemconvStability & SemconvStability.OLD) {
+    attrs[ATTR_DB_CONNECTION_STRING] = getJDBCString(host, port, database);
+    attrs[ATTR_DB_NAME] = database;
+    attrs[ATTR_DB_USER] = user;
+  }
+  if (dbSemconvStability & SemconvStability.STABLE) {
+    attrs[ATTR_DB_NAMESPACE] = database;
+  }
+
   const portNumber = parseInt(port, 10);
-  if (!isNaN(portNumber)) {
-    return {
-      [ATTR_NET_PEER_NAME]: host,
-      [ATTR_NET_PEER_PORT]: portNumber,
-      [ATTR_DB_CONNECTION_STRING]: getJDBCString(host, port, database),
-      [ATTR_DB_NAME]: database,
-      [ATTR_DB_USER]: user,
-    };
+  if (netSemconvStability & SemconvStability.OLD) {
+    attrs[ATTR_NET_PEER_NAME] = host;
+    if (!isNaN(portNumber)) {
+      attrs[ATTR_NET_PEER_PORT] = portNumber;
+    }
   }
-  return {
-    [ATTR_NET_PEER_NAME]: host,
-    [ATTR_DB_CONNECTION_STRING]: getJDBCString(host, port, database),
-    [ATTR_DB_NAME]: database,
-    [ATTR_DB_USER]: user,
-  };
+  if (netSemconvStability & SemconvStability.STABLE) {
+    attrs[ATTR_SERVER_ADDRESS] = host;
+    if (!isNaN(portNumber)) {
+      attrs[ATTR_SERVER_PORT] = portNumber;
+    }
+  }
+
+  return attrs;
 }
 
 function getConfig(config: any) {
@@ -101,11 +122,9 @@ function getJDBCString(
 }
 
 /**
- * Conjures up the value for the db.statement attribute by formatting a SQL query.
- *
- * @returns the database statement being executed.
+ * Conjures up the value for the db.query.text attribute by formatting a SQL query.
  */
-export function getDbStatement(
+export function getQueryText(
   query: string | Query | QueryOptions,
   format?: formatType,
   values?: any[],

packages/instrumentation-mysql2/src/utils.ts

@@ -36,6 +36,8 @@ import {
 import * as assert from 'assert';
 import { MySQL2Instrumentation, MySQL2InstrumentationConfig } from '../src';
 
+process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http/dup,database/dup';
+
 const LIB_VERSION = testUtils.getPackageVersion('mysql2');
 const port = Number(process.env.MYSQL_PORT) || 33306;
 const database = process.env.MYSQL_DATABASE || 'test_db';
@@ -59,6 +61,14 @@ import type {
   Connection as ConnectionAsync,
   createConnection as createConnectionAsync,
 } from 'mysql2/promise';
+import {
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+  ATTR_SERVER_ADDRESS,
+  ATTR_SERVER_PORT,
+  DB_SYSTEM_NAME_VALUE_MYSQL,
+} from '@opentelemetry/semantic-conventions';
 
 interface Result extends RowDataPacket {
   solution: number;
@@ -435,6 +445,80 @@ describe('mysql2', () => {
       });
     });
 
+    describe('various values of OTEL_SEMCONV_STABILITY_OPT_IN', () => {
+      // Restore OTEL_SEMCONV_STABILITY_OPT_IN after we are done.
+      const _origOptInEnv = process.env.OTEL_SEMCONV_STABILITY_OPT_IN;
+      after(() => {
+        process.env.OTEL_SEMCONV_STABILITY_OPT_IN = _origOptInEnv;
+        (instrumentation as any)._setSemconvStabilityFromEnv();
+      });
+
+      const sql = 'SELECT 1+1 as solution';
+      const queryAndGetSpan = (): Promise<ReadableSpan> => {
+        return new Promise(resolve => {
+          const span = provider.getTracer('default').startSpan('test span');
+          context.with(trace.setSpan(context.active(), span), () => {
+            connection.query(sql, (err, res: RowDataPacket[]) => {
+              const spans = memoryExporter.getFinishedSpans();
+              assert.strictEqual(spans.length, 1);
+              resolve(spans[0]);
+            });
+          });
+        });
+      };
+
+      it('OTEL_SEMCONV_STABILITY_OPT_IN=(empty)', async () => {
+        process.env.OTEL_SEMCONV_STABILITY_OPT_IN = '';
+        (instrumentation as any)._setSemconvStabilityFromEnv();
+
+        const { attributes } = await queryAndGetSpan();
+
+        // old `db.*`
+        assert.strictEqual(attributes[ATTR_DB_SYSTEM], DB_SYSTEM_VALUE_MYSQL);
+        assert.strictEqual(attributes[ATTR_DB_NAME], database);
+        assert.strictEqual(attributes[ATTR_DB_USER], user);
+        assert.strictEqual(attributes[ATTR_DB_STATEMENT], format(sql));
+        // stable `db.*`
+        assert.strictEqual(attributes[ATTR_DB_SYSTEM_NAME], undefined);
+        assert.strictEqual(attributes[ATTR_DB_NAMESPACE], undefined);
+        assert.strictEqual(attributes[ATTR_DB_QUERY_TEXT], undefined);
+
+        // old `net.*`
+        assert.strictEqual(attributes[ATTR_NET_PEER_NAME], host);
+        assert.strictEqual(attributes[ATTR_NET_PEER_PORT], port);
+        // stable `net.*`
+        assert.strictEqual(attributes[ATTR_SERVER_ADDRESS], undefined);
+        assert.strictEqual(attributes[ATTR_SERVER_PORT], undefined);
+      });
+
+      it('OTEL_SEMCONV_STABILITY_OPT_IN=http,database', async () => {
+        process.env.OTEL_SEMCONV_STABILITY_OPT_IN = 'http,database';
+        (instrumentation as any)._setSemconvStabilityFromEnv();
+
+        const { attributes } = await queryAndGetSpan();
+
+        // old `db.*`
+        assert.strictEqual(attributes[ATTR_DB_SYSTEM], undefined);
+        assert.strictEqual(attributes[ATTR_DB_STATEMENT], undefined);
+        assert.strictEqual(attributes[ATTR_DB_NAME], undefined);
+        assert.strictEqual(attributes[ATTR_DB_USER], undefined);
+        // stable `db.*`
+        assert.strictEqual(
+          attributes[ATTR_DB_SYSTEM_NAME],
+          DB_SYSTEM_NAME_VALUE_MYSQL
+        );
+        assert.strictEqual(attributes[ATTR_DB_NAMESPACE], database);
+        assert.strictEqual(attributes[ATTR_DB_QUERY_TEXT], format(sql));
+
+        // old `net.*`
+        assert.strictEqual(attributes[ATTR_NET_PEER_NAME], undefined);
+        assert.strictEqual(attributes[ATTR_NET_PEER_PORT], undefined);
+        // stable `net.*`
+        assert.strictEqual(attributes[ATTR_SERVER_ADDRESS], host);
+        assert.strictEqual(attributes[ATTR_SERVER_PORT], port);
+      });
+    });
+
     describe('#Connection.execute', () => {
       it('should intercept connection.execute(text: string)', done => {
         const span = provider.getTracer('default').startSpan('test span');
@@ -1568,12 +1652,24 @@ function assertSpan(
   values?: any,
   errorMessage?: string
 ) {
+  // Assert both old and stable `db.*` semconv.
   assert.strictEqual(span.attributes[ATTR_DB_SYSTEM], DB_SYSTEM_VALUE_MYSQL);
   assert.strictEqual(span.attributes[ATTR_DB_NAME], database);
-  assert.strictEqual(span.attributes[ATTR_NET_PEER_PORT], port);
-  assert.strictEqual(span.attributes[ATTR_NET_PEER_NAME], host);
   assert.strictEqual(span.attributes[ATTR_DB_USER], user);
   assert.strictEqual(span.attributes[ATTR_DB_STATEMENT], format(sql, values));
+  assert.strictEqual(
+    span.attributes[ATTR_DB_SYSTEM_NAME],
+    DB_SYSTEM_NAME_VALUE_MYSQL
+  );
+  assert.strictEqual(span.attributes[ATTR_DB_NAMESPACE], database);
+  assert.strictEqual(span.attributes[ATTR_DB_QUERY_TEXT], format(sql, values));
+
+  // Assert both old and stable `net.*` semconv.
+  assert.strictEqual(span.attributes[ATTR_NET_PEER_NAME], host);
+  assert.strictEqual(span.attributes[ATTR_NET_PEER_PORT], port);
+  assert.strictEqual(span.attributes[ATTR_SERVER_ADDRESS], host);
+  assert.strictEqual(span.attributes[ATTR_SERVER_PORT], port);
+
   if (errorMessage) {
     assert.strictEqual(span.status.message, errorMessage);
     assert.strictEqual(span.status.code, SpanStatusCode.ERROR);