feat(instrumentation-knex): Use newer semantic conventions

deejay1 · deejay1 · commit f6f9e4c3f806 · 2025-04-14T16:46:46.000+02:00
diff --git a/plugins/node/opentelemetry-instrumentation-knex/README.md b/plugins/node/opentelemetry-instrumentation-knex/README.md
@@ -54,7 +54,28 @@ 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.27+`, 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.32.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.32.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.
+
+### ### Legacy Behavior (default)
+
+Enabled when `OTEL_SEMCONV_STABILITY_OPT_IN` contains `database/dup` or DOES NOT CONTAIN `database`.
 
 Attributes collected:
 
@@ -70,6 +91,25 @@ Attributes collected:
 | `net.peer.port`         | Remote port number.                                                            |
 | `net.transport`         | Transport protocol used.                                                       |
 
+### RC Semantic Conventions 1.32
+
+Enabled when `OTEL_SEMCONV_STABILITY_OPT_IN` contains `database` OR `database/dup`.
+This is the recommended configuration, and will soon become the default behavior.
+
+Attributes collected:
+
+| Attribute            | Short Description                                                           |
+|----------------------|-----------------------------------------------------------------------------|
+| `db.namespace`       | This attribute is used to report the name of the database being accessed.   |
+| `db.operation.name`  | The name of the operation being executed.                                   |
+| `db.collection.name` | The name of the primary table that the operation is acting upon.            |
+| `db.query.text`      | 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.                                        |
+| `server.address`     | Remote hostname or similar.                                                 |
+| `server.port`        | Remote port number.                                                         |
+| `network.transport`  | Transport protocol used.                                                    |
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
diff --git a/plugins/node/opentelemetry-instrumentation-knex/package.json b/plugins/node/opentelemetry-instrumentation-knex/package.json
@@ -33,7 +33,9 @@
   "files": [
     "build/src/**/*.js",
     "build/src/**/*.js.map",
-    "build/src/**/*.d.ts"
+    "build/src/**/*.d.ts",
+    "LICENSE",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"
diff --git a/plugins/node/opentelemetry-instrumentation-knex/src/env.ts b/plugins/node/opentelemetry-instrumentation-knex/src/env.ts
@@ -0,0 +1,48 @@
+/*
+ * 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.
+ */
+
+/**
+ * Retrieves a string from an environment variable.
+ * - Returns `undefined` if the environment variable is empty, unset, or contains only whitespace.
+ *
+ * @param {string} key - The name of the environment variable to retrieve.
+ * @returns {string | undefined} - The string value or `undefined`.
+ */
+export function getStringFromEnv(key: string): string | undefined {
+  const raw = process.env[key];
+  if (raw == null || raw.trim() === '') {
+    return undefined;
+  }
+  return raw;
+}
+
+/**
+ * Retrieves a list of strings from an environment variable.
+ * - Uses ',' as the delimiter.
+ * - Trims leading and trailing whitespace from each entry.
+ * - Excludes empty entries.
+ * - Returns `undefined` if the environment variable is empty or contains only whitespace.
+ * - Returns an empty array if all entries are empty or whitespace.
+ *
+ * @param {string} key - The name of the environment variable to retrieve.
+ * @returns {string[] | undefined} - The list of strings or `undefined`.
+ */
+export function getStringListFromEnv(key: string): string[] | undefined {
+  return getStringFromEnv(key)
+    ?.split(',')
+    .map(v => v.trim())
+    .filter(s => s !== '');
+}
diff --git a/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts b/plugins/node/opentelemetry-instrumentation-knex/src/instrumentation.ts
@@ -24,7 +24,14 @@ import {
   InstrumentationNodeModuleFile,
   isWrapped,
 } from '@opentelemetry/instrumentation';
+import * as utils from './utils';
+import { KnexInstrumentationConfig } from './types';
+import { SemconvStability } from './internal-types';
+import { getStringListFromEnv } from './env';
 import {
+  ATTR_NETWORK_TRANSPORT,
+  ATTR_SERVER_ADDRESS,
+  ATTR_SERVER_PORT,
   SEMATTRS_DB_NAME,
   SEMATTRS_DB_OPERATION,
   SEMATTRS_DB_SQL_TABLE,
@@ -35,8 +42,15 @@ import {
   SEMATTRS_NET_PEER_PORT,
   SEMATTRS_NET_TRANSPORT,
 } from '@opentelemetry/semantic-conventions';
-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_DB_USER,
+} from './semconv';
+import { mapSystem } from './utils';
 
 const contextSymbol = Symbol('opentelemetry.instrumentation-knex.context');
 const DEFAULT_CONFIG: KnexInstrumentationConfig = {
@@ -45,8 +59,21 @@ const DEFAULT_CONFIG: KnexInstrumentationConfig = {
 };
 
 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 +149,10 @@ export class KnexInstrumentation extends InstrumentationBase<KnexInstrumentation
 
   private createQueryWrapper(moduleVersion?: string) {
     const instrumentation = this;
+
+    // We need to bind it here, because `this` is not the same in the wrapper
+    const semConv = this._semconvStability;
+
     return function wrapQuery(original: (...args: any[]) => any) {
       return function wrapped_logging_method(this: any, query: any) {
         const config = this.client.config;
@@ -134,24 +165,45 @@ export class KnexInstrumentation extends InstrumentationBase<KnexInstrumentation
           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 ((semConv & SemconvStability.OLD) === 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 ((semConv & SemconvStability.STABLE) === SemconvStability.STABLE) {
+          Object.assign(attributes, {
+            [ATTR_DB_SYSTEM_NAME]: mapSystem(config.client),
+            [ATTR_DB_COLLECTION_NAME]: table,
+            [ATTR_DB_OPERATION_NAME]: operation,
+            [ATTR_DB_USER]: config?.connection?.user,
+            [ATTR_DB_NAMESPACE]: name,
+            [ATTR_SERVER_ADDRESS]: config?.connection?.host,
+            [ATTR_SERVER_PORT]: config?.connection?.port,
+            [ATTR_NETWORK_TRANSPORT]: transport,
+          });
+        }
         if (maxQueryLength) {
           // filters both undefined and 0
-          attributes[SEMATTRS_DB_STATEMENT] = utils.limitLength(
-            query?.sql,
-            maxQueryLength
-          );
+          const queryText = utils.limitLength(query?.sql, maxQueryLength);
+          if (semConv & SemconvStability.STABLE) {
+            attributes[ATTR_DB_QUERY_TEXT] = queryText;
+          }
+          if (semConv & SemconvStability.OLD) {
+            attributes[SEMATTRS_DB_STATEMENT] = queryText;
+          }
         }
 
         const parentContext =
diff --git a/plugins/node/opentelemetry-instrumentation-knex/src/internal-types.ts b/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,
+}
diff --git a/plugins/node/opentelemetry-instrumentation-knex/src/semconv.ts b/plugins/node/opentelemetry-instrumentation-knex/src/semconv.ts
@@ -0,0 +1,30 @@
+/*
+ * 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 ATTR_DB_NAMESPACE = 'db.namespace';
+export const ATTR_DB_OPERATION_NAME = 'db.operation.name';
+export const ATTR_DB_SYSTEM_NAME = 'db.system.name';
+export const ATTR_DB_COLLECTION_NAME = 'db.collection.name';
+export const ATTR_DB_USER = 'db.user';
+export const ATTR_DB_QUERY_TEXT = 'db.query.text';
+/**
+ * Enum value "sqlite" for attribute {@link ATTR_DB_SYSTEM_NAME}.
+ */
+export const DB_SYSTEM_NAME_VALUE_SQLITE = 'sqlite' as const;
+/**
+ * Enum value "postgresql" for attribute {@link ATTR_DB_SYSTEM_NAME}.
+ */
+export const DB_SYSTEM_NAME_VALUE_POSTGRESQL = 'postgresql' as const;
diff --git a/plugins/node/opentelemetry-instrumentation-knex/src/utils.ts b/plugins/node/opentelemetry-instrumentation-knex/src/utils.ts
@@ -16,9 +16,9 @@
 
 import { Exception } from '@opentelemetry/api';
 import {
-  DBSYSTEMVALUES_SQLITE,
-  DBSYSTEMVALUES_POSTGRESQL,
-} from '@opentelemetry/semantic-conventions';
+  DB_SYSTEM_NAME_VALUE_POSTGRESQL,
+  DB_SYSTEM_NAME_VALUE_SQLITE,
+} from './semconv';
 
 type KnexError = Error & {
   code?: string;
@@ -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) => {
