feat(instrumentation-knex): Use newer semantic conventions

plugins/node/opentelemetry-instrumentation-knex/README.md

@@ -54,21 +54,38 @@ registerInstrumentations({
 
 ## 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 package uses `@opentelemetry/semantic-conventions` version `1.33+`, which implements Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md)
+
+This package is capable of emitting both Semantic Convention [Version 1.7.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.7.0/semantic_conventions/README.md) and [Version 1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md)
+It is controlled using the environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`, which is a comma separated list of values.
+The values `database` and `database/dup` control this instrumentation.
+See details for the behavior of each of these values below.
+If neither `database` or `database/dup` is included in `OTEL_SEMCONV_STABILITY_OPT_IN`, the old experimental semantic conventions will be used by default.
+
+### Upgrading Semantic Conventions
+
+When upgrading to the new semantic conventions, it is recommended to do so in the following order:
+
+1. Upgrade `@opentelemetry/instrumentation-knex` to the latest version
+2. Set `OTEL_SEMCONV_STABILITY_OPT_IN=database/dup` to emit both old and new semantic conventions
+3. Modify alerts, dashboards, metrics, and other processes to expect the new semantic conventions
+4. Set `OTEL_SEMCONV_STABILITY_OPT_IN=database` to emit only the new semantic conventions
+
+This will cause both the old and new semantic conventions to be emitted during the transition period.
 
 Attributes collected:
 
-| Attribute               | Short Description                                                              |
-| ----------------------- | ------------------------------------------------------------------------------ |
-| `db.name`               | This attribute is used to report the name of the database being accessed.      |
-| `db.operation`          | The name of the operation being executed.                                      |
-| `db.sql.table`          | The name of the primary table that the operation is acting upon.               |
-| `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.                                                            |
-| `net.transport`         | Transport protocol used.                                                       |
+| v1.7.0 semconv  | v1.23.0 semconv      | Short Description                                                           |
+|-----------------|----------------------|-----------------------------------------------------------------------------|
+| `db.name`       | `db.namespace`       | This attribute is used to report the name of the database being accessed.   |
+| `db.operation`  | `db.operation.name`  | The name of the operation being executed.                                   |
+| `db.sql.table`  | `db.collection.name` | The name of the primary table that the operation is acting upon.            |
+| `db.statement`  | `db.query.text`      | The database statement being executed.                                      |
+| `db.system`     | `db.system.name`     | An identifier for the database management system (DBMS) product being used. |
+| `db.user`       | (not included)       | Username for accessing the database.                                        |
+| `net.peer.name` | `server.address`     | Remote hostname or similar.                                                 |
+| `net.peer.port` | `server.port`        | Remote port number.                                                         |
+| `net.transport` | (not included)       | Transport protocol used.                                                    |
 
 ## Useful links
 

plugins/node/opentelemetry-instrumentation-knex/package.json

@@ -56,8 +56,9 @@
     "typescript": "5.0.4"
   },
   "dependencies": {
+    "@opentelemetry/core": "^2.0.0",
     "@opentelemetry/instrumentation": "^0.200.0",
-    "@opentelemetry/semantic-conventions": "^1.27.0"
+    "@opentelemetry/semantic-conventions": "^1.33.0"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/plugins/node/opentelemetry-instrumentation-knex#readme"
 }

plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts

@@ -24,7 +24,19 @@
   InstrumentationNodeModuleFile,
   isWrapped,
 } from '@opentelemetry/instrumentation';
+import * as utils from './utils';
+import { mapSystem } from './utils';
+import { KnexInstrumentationConfig } from './types';
+import { SemconvStability } from './internal-types';
+import { getStringListFromEnv } from '@opentelemetry/core';
 import {
+  ATTR_DB_COLLECTION_NAME,
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_OPERATION_NAME,
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+  ATTR_SERVER_ADDRESS,
+  ATTR_SERVER_PORT,
   SEMATTRS_DB_NAME,
   SEMATTRS_DB_OPERATION,
   SEMATTRS_DB_SQL_TABLE,
@@ -35,8 +47,6 @@
   SEMATTRS_NET_PEER_PORT,
   SEMATTRS_NET_TRANSPORT,
 } from '@opentelemetry/semantic-conventions';
-import * as utils from './utils';
-import { KnexInstrumentationConfig } from './types';
 
 const contextSymbol = Symbol('opentelemetry.instrumentation-knex.context');
 const DEFAULT_CONFIG: KnexInstrumentationConfig = {
@@ -45,8 +55,21 @@
 };
 
 export class KnexInstrumentation extends InstrumentationBase<KnexInstrumentationConfig> {
+  private _semconvStability: SemconvStability = SemconvStability.OLD;
+
   constructor(config: KnexInstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, { ...DEFAULT_CONFIG, ...config });
+
+    for (const entry of getStringListFromEnv('OTEL_SEMCONV_STABILITY_OPT_IN') ??
+      []) {
+      if (entry.toLowerCase() === 'database/dup') {
+        // database/dup takes highest precedence. If it is found, there is no need to read the rest of the list
+        this._semconvStability = SemconvStability.DUPLICATE;
+        break;
+      } else if (entry.toLowerCase() === 'database') {
+        this._semconvStability = SemconvStability.STABLE;
+      }
+    }
   }
 
   override setConfig(config: KnexInstrumentationConfig = {}) {
@@ -122,6 +145,7 @@
 
   private createQueryWrapper(moduleVersion?: string) {
     const instrumentation = this;
+
     return function wrapQuery(original: (...args: any[]) => any) {
       return function wrapped_logging_method(this: any, query: any) {
         const config = this.client.config;
@@ -134,24 +158,43 @@
           config?.connection?.filename || config?.connection?.database;
         const { maxQueryLength } = instrumentation.getConfig();
 
-        const attributes: api.SpanAttributes = {
+        const attributes: api.Attributes = {
           'knex.version': moduleVersion,
-          [SEMATTRS_DB_SYSTEM]: utils.mapSystem(config.client),
-          [SEMATTRS_DB_SQL_TABLE]: table,
-          [SEMATTRS_DB_OPERATION]: operation,
-          [SEMATTRS_DB_USER]: config?.connection?.user,
-          [SEMATTRS_DB_NAME]: name,
-          [SEMATTRS_NET_PEER_NAME]: config?.connection?.host,
-          [SEMATTRS_NET_PEER_PORT]: config?.connection?.port,
-          [SEMATTRS_NET_TRANSPORT]:
-            config?.connection?.filename === ':memory:' ? 'inproc' : undefined,
         };
+        const transport =
+          config?.connection?.filename === ':memory:' ? 'inproc' : undefined;
+
+        if (instrumentation._semconvStability & SemconvStability.OLD) {
+          Object.assign(attributes, {
+            [SEMATTRS_DB_SYSTEM]: mapSystem(config.client),
+            [SEMATTRS_DB_SQL_TABLE]: table,
+            [SEMATTRS_DB_OPERATION]: operation,
+            [SEMATTRS_DB_USER]: config?.connection?.user,
+            [SEMATTRS_DB_NAME]: name,
+            [SEMATTRS_NET_PEER_NAME]: config?.connection?.host,
+            [SEMATTRS_NET_PEER_PORT]: config?.connection?.port,
+            [SEMATTRS_NET_TRANSPORT]: transport,
+          });
+        }
+        if (instrumentation._semconvStability & SemconvStability.STABLE) {
+          Object.assign(attributes, {
+            [ATTR_DB_SYSTEM_NAME]: mapSystem(config.client),
+            [ATTR_DB_COLLECTION_NAME]: table,
+            [ATTR_DB_OPERATION_NAME]: operation,
+            [ATTR_DB_NAMESPACE]: name,
+            [ATTR_SERVER_ADDRESS]: config?.connection?.host,
+            [ATTR_SERVER_PORT]: config?.connection?.port,
+          });
+        }
         if (maxQueryLength) {
           // filters both undefined and 0
-          attributes[SEMATTRS_DB_STATEMENT] = utils.limitLength(
-            query?.sql,
-            maxQueryLength
-          );
+          const queryText = utils.limitLength(query?.sql, maxQueryLength);
+          if (instrumentation._semconvStability & SemconvStability.STABLE) {
+            attributes[ATTR_DB_QUERY_TEXT] = queryText;
+          }
+          if (instrumentation._semconvStability & SemconvStability.OLD) {
+            attributes[SEMATTRS_DB_STATEMENT] = queryText;
+          }
         }
 
         const parentContext =

plugins/node/opentelemetry-instrumentation-knex/src/internal-types.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright The OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+export const enum SemconvStability {
+  /** Emit only stable semantic conventions */
+  STABLE = 0x1,
+  /** Emit only old semantic conventions*/
+  OLD = 0x2,
+  /** Emit both stable and old semantic conventions*/
+  DUPLICATE = 0x1 | 0x2,
+}

plugins/node/opentelemetry-instrumentation-knex/src/utils.ts

@@ -16,8 +16,8 @@
 
 import { Exception } from '@opentelemetry/api';
 import {
-  DBSYSTEMVALUES_SQLITE,
-  DBSYSTEMVALUES_POSTGRESQL,
+  DB_SYSTEM_NAME_VALUE_POSTGRESQL,
+  DB_SYSTEM_NAME_VALUE_SQLITE,
 } from '@opentelemetry/semantic-conventions';
 
 type KnexError = Error & {
@@ -57,8 +57,8 @@ export function otelExceptionFromKnexError(
 }
 
 const systemMap = new Map([
-  ['sqlite3', DBSYSTEMVALUES_SQLITE],
-  ['pg', DBSYSTEMVALUES_POSTGRESQL],
+  ['sqlite3', DB_SYSTEM_NAME_VALUE_SQLITE],
+  ['pg', DB_SYSTEM_NAME_VALUE_POSTGRESQL],
 ]);
 
 export const mapSystem = (knexSystem: string) => {