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-spans.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,8 @@
     "typescript": "5.0.4"
   },
   "dependencies": {
-    "@opentelemetry/instrumentation": "^0.201.0",
-    "@opentelemetry/semantic-conventions": "^1.27.0"
+    "@opentelemetry/instrumentation": "^0.201.1",
+    "@opentelemetry/semantic-conventions": "^1.33.1"
   },
   "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

@@ -23,8 +23,19 @@
   InstrumentationNodeModuleDefinition,
   InstrumentationNodeModuleFile,
   isWrapped,
+  SemconvStability,
+  semconvStabilityFromStr,
 } from '@opentelemetry/instrumentation';
+import * as utils from './utils';
+import { KnexInstrumentationConfig } from './types';
 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 +46,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 +54,15 @@
 };
 
 export class KnexInstrumentation extends InstrumentationBase<KnexInstrumentationConfig> {
+  private _semconvStability: SemconvStability;
+
   constructor(config: KnexInstrumentationConfig = {}) {
     super(PACKAGE_NAME, PACKAGE_VERSION, { ...DEFAULT_CONFIG, ...config });
+
+    this._semconvStability = semconvStabilityFromStr(
+      'database',
+      process.env.OTEL_SEMCONV_STABILITY_OPT_IN
+    );
   }
 
   override setConfig(config: KnexInstrumentationConfig = {}) {
@@ -122,6 +138,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 +151,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]: 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]: transport,
+          });
+        }
+        if (instrumentation._semconvStability & SemconvStability.STABLE) {
+          Object.assign(attributes, {
+            [ATTR_DB_SYSTEM_NAME]: utils.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/semconv.ts

@@ -0,0 +1,26 @@
+/*
+ * 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.
+ */
+
+/*
+ * This file contains a copy of unstable semantic convention definitions
+ * used by this package.
+ * @see https://github.com/open-telemetry/opentelemetry-js/tree/main/semantic-conventions#unstable-semconv
+ */
+
+/**
+ * Enum value "sqlite" for attribute {@link ATTR_DB_SYSTEM_NAME}.
+ */
+export const DB_SYSTEM_NAME_VALUE_SQLITE = 'sqlite' as const;

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

@@ -15,10 +15,8 @@
  */
 
 import { Exception } from '@opentelemetry/api';
-import {
-  DBSYSTEMVALUES_SQLITE,
-  DBSYSTEMVALUES_POSTGRESQL,
-} from '@opentelemetry/semantic-conventions';
+import { DB_SYSTEM_NAME_VALUE_POSTGRESQL } from '@opentelemetry/semantic-conventions';
+import { DB_SYSTEM_NAME_VALUE_SQLITE } from './semconv';
 
 type KnexError = Error & {
   code?: string;
@@ -57,8 +55,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) => {