chore(instrumentation-oracledb): update semconv constants to match experimental values (#3106)

Closes: #3083

Author: sudarshan12s

package-lock.json

@@ -74,7 +74,7 @@
   },
   "dependencies": {
     "@opentelemetry/instrumentation": "^0.206.0",
-    "@opentelemetry/semantic-conventions": "^1.27.0",
+    "@opentelemetry/semantic-conventions": "^1.34.0",
     "@types/oracledb": "6.5.2"
   },
   "homepage": "https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-oracledb#readme"

packages/instrumentation-oracledb/package.json

@@ -26,17 +26,18 @@ import {
   diag,
 } from '@opentelemetry/api';
 import {
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_QUERY_TEXT,
+  ATTR_DB_SYSTEM_NAME,
+  ATTR_DB_OPERATION_NAME,
   ATTR_SERVER_PORT,
   ATTR_SERVER_ADDRESS,
   ATTR_NETWORK_TRANSPORT,
 } from '@opentelemetry/semantic-conventions';
 import {
-  ATTR_DB_SYSTEM,
-  ATTR_DB_NAMESPACE,
-  ATTR_DB_OPERATION_NAME,
-  ATTR_DB_STATEMENT,
-  ATTR_DB_OPERATION_PARAMETER,
   ATTR_DB_USER,
+  ATTR_DB_OPERATION_PARAMETER,
+  DB_SYSTEM_NAME_VALUE_ORACLE_DB,
 } from './semconv';
 
 import type * as oracleDBTypes from 'oracledb';
@@ -46,7 +47,7 @@ const OUT_BIND = 3003; // bindinfo direction value.
 // Local modules.
 import { OracleInstrumentationConfig, SpanConnectionConfig } from './types';
 import { TraceSpanData, SpanCallLevelConfig } from './internal-types';
-import { SpanNames, DB_SYSTEM_VALUE_ORACLE } from './constants';
+import { SpanNames } from './constants';
 
 // It dynamically retrieves the TraceHandlerBase class from the oracledb module
 // (if available) while avoiding direct imports that could cause issues if
@@ -111,7 +112,7 @@ export function getOracleTelemetryTraceHandlerClass(
     // semantic standards and module custom keys.
     private _getConnectionSpanAttributes(config: SpanConnectionConfig) {
       return {
-        [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_ORACLE,
+        [ATTR_DB_SYSTEM_NAME]: DB_SYSTEM_NAME_VALUE_ORACLE_DB,
         [ATTR_NETWORK_TRANSPORT]: config.protocol,
         [ATTR_DB_USER]: config.user,
         [ATTR_DB_NAMESPACE]: this._getDBNameSpace(
@@ -147,16 +148,16 @@ export function getOracleTelemetryTraceHandlerClass(
         if (Array.isArray(values)) {
           // Handle indexed (positional) parameters
           values.forEach((value, index) => {
-            const key = `${ATTR_DB_OPERATION_PARAMETER}.${index}`;
             const extractedValue = this._extractValue(value);
             if (extractedValue !== undefined) {
-              convertedValues[key] = extractedValue;
+              convertedValues[ATTR_DB_OPERATION_PARAMETER(`${index}`)] =
+                extractedValue;
             }
           });
         } else if (values && typeof values === 'object') {
           // Handle named parameters
           for (const [paramName, value] of Object.entries(values)) {
-            const key = `${ATTR_DB_OPERATION_PARAMETER}.${paramName}`;
+            const key = ATTR_DB_OPERATION_PARAMETER(paramName);
             let inVal: any = value;
 
             if (inVal && typeof inVal === 'object') {
@@ -216,7 +217,7 @@ export function getOracleTelemetryTraceHandlerClass(
           this._instrumentConfig.dbStatementDump ||
           this._instrumentConfig.enhancedDatabaseReporting
         ) {
-          span.setAttribute(ATTR_DB_STATEMENT, callConfig.statement);
+          span.setAttribute(ATTR_DB_QUERY_TEXT, callConfig.statement);
           if (this._instrumentConfig.enhancedDatabaseReporting && !roundTrip) {
             const values = this._getValues(callConfig.values);
             if (values) {

packages/instrumentation-oracledb/src/OracleTelemetryTraceHandler.ts

@@ -38,10 +38,3 @@ export enum SpanNames {
   LOB_MESSAGE = 'oracledb.LobOpMessage',
   LOB_GETDATA = 'oracledb.Lob.getData',
 }
-
-/*
- * The semantic conventions defined DBSYSTEMVALUES_ORACLE as oracle, hence
- * defining the new constant to explicitly mention db.
- *
- */
-export const DB_SYSTEM_VALUE_ORACLE = 'oracle.db';

packages/instrumentation-oracledb/src/constants.ts

@@ -16,86 +16,46 @@
  * Copyright (c) 2025, Oracle and/or its affiliates.
  * */
 
-/**
- * The database management system (DBMS) product as identified
- * by the client instrumentation.
- *
+/*
+ * 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
  */
-export const ATTR_DB_SYSTEM = 'db.system.name';
 
 /**
- * The database associated with the connection, qualified by the instance name, database name and service name.
+ * A database operation parameter, with `<key>` being the parameter name, and the attribute value being a string representation of the parameter value.
  *
- * @example ORCL1|PDB1|db_high.adb.oraclecloud.com
- * @example ORCL1|DB1|db_low.adb.oraclecloud.com
- *
- * @note It **SHOULD** be set to the combination of instance name, database name and
- * service name following the `{instance_name}|{database_name}|{service_name}` pattern.
- * For CDB architecture, database name would be pdb name. For Non-CDB, it would be
- * **DB_NAME** parameter.
- * This attribute has stability level RELEASE CANDIDATE.
- *
- * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
- */
-export const ATTR_DB_NAMESPACE = 'db.namespace';
-
-/**
- * The name of the operation or command being executed.
+ * @example someval
+ * @example 55
  *
- * @example INSERT
- * @example COMMIT
- * @example SELECT
+ * @note For example, a client-side maximum number of rows to read from the database
+ * **MAY** be recorded as the `db.operation.parameter.max_rows` attribute.
  *
- * @note It is **RECOMMENDED** to capture the value as provided by the application without attempting to do any case normalization.
- * If the operation name is parsed from the query text, it **SHOULD** be the first operation name found in the query.
- * For batch operations, if the individual operations are known to have the same operation name then that operation name **SHOULD** be used prepended by `BATCH `, otherwise `db.operation.name` **SHOULD** be `BATCH` or some other database system specific term if more applicable.
- * This attribute has stability level RELEASE CANDIDATE.
+ * `db.query.text` parameters **SHOULD** be captured using `db.query.parameter.<key>`
+ * instead of `db.operation.parameter.<key>`.
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_DB_OPERATION_NAME = 'db.operation.name';
+export const ATTR_DB_OPERATION_PARAMETER = (key: string) =>
+  `db.operation.parameter.${key}`;
 
 /**
- * The database query being executed.
- *
- * @example SELECT * FROM wuser_table where username = :1 // bind by position
- * @example SELECT * FROM wuser_table where username = :name // bind by name
- * @example SELECT * FROM wuser_table where username = 'John' // literals
+ * Deprecated, no replacement at this time.
  *
- * @note For sanitization see [Sanitization of `db.query.text`](../database/database-spans.md#sanitization-of-dbquerytext).
- * For batch operations, if the individual operations are known to have the same query text then
- * that query text **SHOULD** be used, otherwise all of the individual query texts **SHOULD**
- * be concatenated with separator `; ` or some other database system specific separator if more applicable.
- *
- * Non-parameterized or Parameterized query text **SHOULD NOT** be collected by default unless
- * explicitly configured and sanitized to exclude sensitive data, e.g. by redacting all
- * literal values present in the query text. See Sanitization of `db.query.text`.
- *
- * Parameterized query text MUST also NOT be collected by default unless explicitly configured.
- * The query parameter values themselves are opt-in, see [`db.operation.parameter.<key>`](../attributes-registry/db.md))
+ * @example readonly_user
+ * @example reporting_user
  *
  * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
- */
-export const ATTR_DB_STATEMENT = 'db.query.text';
-
-/**
- * A database operation parameter, with <key> being the parameter name,
- * and the attribute value being a string representation of the parameter value.
  *
- * @example someval
- * @example 55
- *
- * @note  If a parameter has no name and instead is referenced only by index, then
- * <key> **SHOULD** be the 0-based index. If `db.query.text` is also captured, then
- * `db.operation.parameter.<key>` **SHOULD** match up with the parameterized placeholders
- * present in db.query.text
- *
- * @experimental This attribute is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
+ * @deprecated Removed, no replacement at this time.
  */
-export const ATTR_DB_OPERATION_PARAMETER = 'db.operation.parameter';
+export const ATTR_DB_USER = 'db.user' as const;
 
 /**
- * Username for accessing the database.
+ * Enum value "oracle.db" for attribute {@link ATTR_DB_SYSTEM_NAME}.
+ *
+ * [Oracle Database](https://www.oracle.com/database/)
  *
+ * @experimental This enum value is experimental and is subject to breaking changes in minor releases of `@opentelemetry/semantic-conventions`.
  */
-export const ATTR_DB_USER = 'db.user';
+export const DB_SYSTEM_NAME_VALUE_ORACLE_DB = 'oracle.db' as const;