- Incorporate semantic conventions suggestions.

Author: sudarshan12s

plugins/node/opentelemetry-instrumentation-oracledb/src/OracleTelemetryTraceHandler.ts

@@ -31,16 +31,18 @@ import {
   ATTR_SERVER_ADDRESS,
   SEMATTRS_NET_TRANSPORT,
   SEMATTRS_DB_USER,
-  SEMATTRS_DB_STATEMENT,
 } from '@opentelemetry/semantic-conventions';
 import {
   ATTR_DB_SYSTEM,
   ATTR_DB_NAMESPACE,
   ATTR_DB_OPERATION_NAME,
+  ATTR_DB_STATEMENT,
+  ATTR_DB_OPERATION_PARAMETER,
 } from './semconv';
 
 import type * as oracleDBTypes from 'oracledb';
 type TraceHandlerBaseCtor = new () => any;
+const OUT_BIND = 3003; // bindinfo direction value.
 
 // Local modules.
 import { AttributeNames } from './constants';
@@ -98,19 +100,31 @@ export function getOracleTelemetryTraceHandlerClass(
         );
       }
 
+      // It returns db.namespace as mentioned in semantic conventions
+      // Ex: ORCL1|PDB1|db_high.adb.oraclecloud.com
+      private _getDBNameSpace(
+        instanceName?: string,
+        pdbName?: string,
+        serviceName?: string
+      ): string | undefined {
+        if (instanceName == null && pdbName == null && serviceName == null) {
+          return undefined;
+        }
+        return `${instanceName ?? ''}|${pdbName ?? ''}|${serviceName ?? ''}`;
+      }
+
       // Returns the connection related Attributes for
       // semantic standards and module custom keys.
       private _getConnectionSpanAttributes(config: SpanConnectionConfig) {
         return {
           [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_ORACLE,
           [SEMATTRS_NET_TRANSPORT]: config.protocol,
           [SEMATTRS_DB_USER]: config.user,
-          [AttributeNames.ORACLE_INSTANCE]: config.instanceName,
-          [AttributeNames.ORACLE_PDBNAME]: config.pdbName,
-          [AttributeNames.ORACLE_POOL_MIN]: config.poolMin,
-          [AttributeNames.ORACLE_POOL_MAX]: config.poolMax,
-          [AttributeNames.ORACLE_POOL_INCR]: config.poolIncrement,
-          [ATTR_DB_NAMESPACE]: config.serviceName,
+          [ATTR_DB_NAMESPACE]: this._getDBNameSpace(
+            config.instanceName,
+            config.pdbName,
+            config.serviceName
+          ),
           [SEMATTRS_DB_CONNECTION_STRING]: config.connectString,
           [ATTR_SERVER_ADDRESS]: config.hostName,
           [ATTR_SERVER_PORT]: config.port,
@@ -126,36 +140,68 @@ export function getOracleTelemetryTraceHandlerClass(
         );
       }
 
-      // Transforms the bind values array into string values.
+      // Transforms the bind values array or bindinfo into an object
+      // 'db.operation.parameter'.
+      // Ex:
+      //   db.operation.parameter.0 = "someval" // for bind by position
+      //   db.operation.parameter.name = "someval" // for bind by name
       // It is only called if config 'enhancedDatabaseReporting' is true.
       private _getValues(values: any) {
-        let convertedValues;
+        const convertedValues: Record<string, string> = {};
+
         try {
           if (Array.isArray(values)) {
-            // bind by position
-            convertedValues = values.map(value => {
-              if (value == null) {
-                return 'null';
-              } else if (
-                value instanceof Buffer ||
-                this._isLobInstance(value)
-              ) {
-                return value.toString();
-              } else if (typeof value === 'object') {
-                return JSON.stringify(value);
-              } else {
-                // number, string, boolean,
-                return value.toString();
+            // 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;
               }
             });
-            return convertedValues;
+          } else if (values && typeof values === 'object') {
+            // Handle named parameters
+            for (const [paramName, value] of Object.entries(values)) {
+              const key = `${ATTR_DB_OPERATION_PARAMETER}.${paramName}`;
+              let inVal: any = value;
+
+              if (inVal && typeof inVal === 'object') {
+                // Check bind info if present.
+                if (inVal.dir === OUT_BIND) {
+                  // outbinds
+                  convertedValues[key] = '';
+                  continue;
+                }
+                if ('val' in inVal) {
+                  inVal = inVal.val;
+                }
+              }
+              const extractedValue = this._extractValue(inVal);
+              if (extractedValue !== undefined) {
+                convertedValues[key] = extractedValue;
+              }
+            }
           }
         } catch (e) {
           diag.error('failed to stringify bind values:', values, e);
         }
         return convertedValues;
       }
 
+      private _extractValue(value: any): string | undefined {
+        if (value == null) {
+          return 'null';
+        }
+        if (value instanceof Buffer || this._isLobInstance(value)) {
+          return value.toString();
+        }
+        if (typeof value === 'object') {
+          return JSON.stringify(value);
+        }
+        // number, string, boolean,
+        return value.toString();
+      }
+
       // Updates the call level attributes in span.
       // roundTrip flag will skip dumping bind values for
       // internal roundtrip spans generated for oracledb exported functions.
@@ -176,14 +222,14 @@ export function getOracleTelemetryTraceHandlerClass(
             this._instrumentConfig.dbStatementDump ||
             this._instrumentConfig.enhancedDatabaseReporting
           ) {
-            span.setAttribute(SEMATTRS_DB_STATEMENT, callConfig.statement);
+            span.setAttribute(ATTR_DB_STATEMENT, callConfig.statement);
             if (
               this._instrumentConfig.enhancedDatabaseReporting &&
               !roundTrip
             ) {
               const values = this._getValues(callConfig.values);
               if (values) {
-                span.setAttribute(AttributeNames.ORACLE_BIND_VALUES, values);
+                span.setAttributes(values);
               }
             }
           }
@@ -233,13 +279,30 @@ export function getOracleTelemetryTraceHandlerClass(
         }
       }
 
-      // Updates the spanName with suffix, serviceName seperated by delimiter, space
-      // Ex: 'oracledb.Pool.getConnection freepdb'
-      // This function is called when connectLevelConfig has serviceName populated.
+      // Updates the spanName following the format
+      // {FunctionName:[sqlCommand] db.namespace}
+      // Ex: 'oracledb.Pool.getConnection:[SELECT] ORCL1|PDB1|db_high.adb.oraclecloud.com'
+      // This function is called when connectLevelConfig has required paramters populated.
       private _updateSpanName(traceContext: TraceSpanData) {
-        const dbName = traceContext.connectLevelConfig?.serviceName ?? '';
-        traceContext.userContext.span.updateName(
-          `${traceContext.operation}${dbName ? ` ${dbName}` : ''}`
+        const { connectLevelConfig, callLevelConfig, userContext, operation } =
+          traceContext;
+        if (
+          ![
+            SpanNames.EXECUTE,
+            SpanNames.EXECUTE_MANY,
+            SpanNames.EXECUTE_MSG,
+          ].includes(operation as SpanNames)
+        ) {
+          // Ignore for connection establishment functions.
+          return;
+        }
+
+        const { instanceName, pdbName, serviceName } = connectLevelConfig;
+        const dbName = this._getDBNameSpace(instanceName, pdbName, serviceName);
+        const sqlCommand =
+          callLevelConfig?.statement?.split(' ')[0].toUpperCase() || '';
+        userContext.span.updateName(
+          `${operation}:${sqlCommand}${dbName && ` ${dbName}`}`
         );
       }
 

plugins/node/opentelemetry-instrumentation-oracledb/src/constants.ts

@@ -19,13 +19,7 @@
 // Oracle specific attributes not covered by standard semantic conventions.
 // See: https://github.com/open-telemetry/semantic-conventions/pull/1911
 export enum AttributeNames {
-  ORACLE_BIND_VALUES = 'oracledb.bind_values',
-  ORACLE_POOL_MIN = 'oracledb.pool_min',
-  ORACLE_POOL_MAX = 'oracledb.pool_max',
-  ORACLE_POOL_INCR = 'oracledb.pool_incr',
-  ORACLE_INSTANCE = 'oracledb.instance',
-  ORACLE_PDBNAME = 'oracledb.pdbname',
-  ORACLE_IMPLICIT_RELEASE = 'oracledb.implicit_release',
+  ORACLE_IMPLICIT_RELEASE = 'oracle.db.implicit_release',
 }
 
 // Contains span names produced by instrumentation

plugins/node/opentelemetry-instrumentation-oracledb/src/semconv.ts

@@ -24,14 +24,15 @@
 export const ATTR_DB_SYSTEM = 'db.system.name';
 
 /**
- * The servicename associated with the connection.
+ * The database associated with the connection, qualified by the instance name, database name and service name.
  *
- * @example FREEPDB1
- * @example inventory.example.org
+ * @example ORCL1|PDB1|db_high.adb.oraclecloud.com
+ * @example ORCL1|DB1|db_low.adb.oraclecloud.com
  *
- * @note If a database system has multiple namespace components, they **SHOULD** be concatenated (potentially using database system specific conventions) from most general to most specific namespace component, and more specific namespaces **SHOULD NOT** be captured without the more general namespaces, to ensure that "startswith" queries for the more general namespaces will be valid.
- * Semantic conventions for individual database systems **SHOULD** document what `db.namespace` means in the context of that system.
- * It is **RECOMMENDED** to capture the value as provided by the application without attempting to do any case normalization.
+ * @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`.
@@ -53,3 +54,42 @@ export const ATTR_DB_NAMESPACE = 'db.namespace';
  * @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';
+
+/**
+ * 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
+ *
+ * @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))
+ *
+ * @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`.
+ */
+export const ATTR_DB_OPERATION_PARAMETER = 'db.operation.parameter';