- Remove Few Deprecated semantic convention constants.

Author: sudarshan12s

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

@@ -48,3 +48,10 @@ 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 = 'oracledb';

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

@@ -0,0 +1,55 @@
+/*
+ * 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.
+ *
+ * Copyright (c) 2024, Oracle and/or its affiliates.
+ * */
+
+/**
+ * The database management system (DBMS) product as identified
+ * by the client instrumentation.
+ *
+ */
+export const ATTR_DB_SYSTEM = 'db.system.name';
+
+/**
+ * The name of the database, fully qualified within the server address and port.
+ *
+ * @example FREEPDB1
+ * @example XEPDB1
+ *
+ * @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.
+ * 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 INSERT
+ * @example COMMIT
+ * @example SELECT
+ *
+ * @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.
+ *
+ * @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';

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

@@ -26,24 +26,25 @@ import {
   diag,
 } from '@opentelemetry/api';
 import {
-  SEMATTRS_DB_SYSTEM,
-  SEMATTRS_DB_NAME,
   SEMATTRS_DB_CONNECTION_STRING,
-  SEMATTRS_NET_PEER_NAME,
-  SEMATTRS_NET_PEER_PORT,
+  ATTR_SERVER_PORT,
+  ATTR_SERVER_ADDRESS,
   SEMATTRS_NET_TRANSPORT,
   SEMATTRS_DB_USER,
   SEMATTRS_DB_STATEMENT,
-  SEMATTRS_DB_OPERATION,
-  DBSYSTEMVALUES_ORACLE,
 } from '@opentelemetry/semantic-conventions';
+import {
+  ATTR_DB_SYSTEM,
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_OPERATION_NAME,
+} from './semconv';
 import * as oracledbTypes from 'oracledb';
 
 // Local modules.
 import { AttributeNames } from './constants';
 import { OracleInstrumentationConfig, SpanConnectionConfig } from './types';
 import { TraceSpanData, SpanCallLevelConfig } from './internal-types';
-import { SpanNames } from './constants';
+import { SpanNames, DB_SYSTEM_VALUE_ORACLE } from './constants';
 
 const newmoduleExports: any = oracledbTypes;
 
@@ -76,18 +77,18 @@ export class OracleTelemetryTraceHandler extends newmoduleExports.traceHandler
   // semantic standards and module custom keys.
   private _getConnectionSpanAttributes(config: SpanConnectionConfig) {
     return {
-      [SEMATTRS_DB_SYSTEM]: DBSYSTEMVALUES_ORACLE,
+      [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,
-      [SEMATTRS_DB_NAME]: config.serviceName,
+      [ATTR_DB_NAMESPACE]: config.serviceName,
       [SEMATTRS_DB_CONNECTION_STRING]: config.connectString,
-      [SEMATTRS_NET_PEER_NAME]: config.hostName,
-      [SEMATTRS_NET_PEER_PORT]: config.port,
+      [ATTR_SERVER_ADDRESS]: config.hostName,
+      [ATTR_SERVER_PORT]: config.port,
     };
   }
 
@@ -133,7 +134,7 @@ export class OracleTelemetryTraceHandler extends newmoduleExports.traceHandler
 
     if (callConfig.statement) {
       span.setAttribute(
-        SEMATTRS_DB_OPERATION,
+        ATTR_DB_OPERATION_NAME,
         // retrieve just the first word
         callConfig.statement.split(' ')[0].toUpperCase()
       );

plugins/node/opentelemetry-instrumentation-oracledb/test/oracle.test.ts

@@ -35,20 +35,27 @@ import {
 } from '@opentelemetry/sdk-trace-base';
 import * as assert from 'assert';
 import { OracleInstrumentation } from '../src';
-import { AttributeNames, SpanNames } from '../src/constants';
+import {
+  AttributeNames,
+  SpanNames,
+  DB_SYSTEM_VALUE_ORACLE,
+} from '../src/constants';
+
 import {
   SEMATTRS_DB_STATEMENT,
-  SEMATTRS_DB_SYSTEM,
-  SEMATTRS_DB_NAME,
-  SEMATTRS_DB_OPERATION,
-  SEMATTRS_NET_PEER_NAME,
+  ATTR_SERVER_ADDRESS,
   SEMATTRS_NET_TRANSPORT,
   SEMATTRS_DB_CONNECTION_STRING,
-  SEMATTRS_NET_PEER_PORT,
+  ATTR_SERVER_PORT,
   SEMATTRS_DB_USER,
-  DBSYSTEMVALUES_ORACLE,
 } from '@opentelemetry/semantic-conventions';
 
+import {
+  ATTR_DB_NAMESPACE,
+  ATTR_DB_SYSTEM,
+  ATTR_DB_OPERATION_NAME,
+} from '../src/semconv';
+
 const memoryExporter = new InMemorySpanExporter();
 let contextManager: AsyncHooksContextManager;
 const provider = new BasicTracerProvider();
@@ -103,26 +110,26 @@ let poolConnAttrList: Record<string, string | number>[]; // attributes per span
 let spanNamesList: string[]; // span names for rountrips and public API spans.
 
 const DEFAULT_ATTRIBUTES = {
-  [SEMATTRS_DB_SYSTEM]: DBSYSTEMVALUES_ORACLE,
-  [SEMATTRS_DB_NAME]: serviceName,
+  [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_ORACLE,
+  [ATTR_DB_NAMESPACE]: serviceName,
   [SEMATTRS_DB_CONNECTION_STRING]: CONFIG.connectString,
-  [SEMATTRS_NET_PEER_NAME]: hostname,
-  [SEMATTRS_NET_PEER_PORT]: pno,
+  [ATTR_SERVER_ADDRESS]: hostname,
+  [ATTR_SERVER_PORT]: pno,
   [SEMATTRS_DB_USER]: CONFIG.user,
   [SEMATTRS_NET_TRANSPORT]: 'TCP',
 };
 
 // for thick mode, we dont have support for
 // hostname, port and protocol.
 const DEFAULT_ATTRIBUTES_THICK = {
-  [SEMATTRS_DB_SYSTEM]: DBSYSTEMVALUES_ORACLE,
-  [SEMATTRS_DB_NAME]: serviceName,
+  [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_ORACLE,
+  [ATTR_DB_NAMESPACE]: serviceName,
   [SEMATTRS_DB_CONNECTION_STRING]: CONFIG.connectString,
   [SEMATTRS_DB_USER]: CONFIG.user,
 };
 
 const POOL_ATTRIBUTES = {
-  [SEMATTRS_DB_SYSTEM]: DBSYSTEMVALUES_ORACLE,
+  [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_ORACLE,
   [SEMATTRS_DB_CONNECTION_STRING]: CONFIG.connectString,
   [SEMATTRS_DB_USER]: CONFIG.user,
   [AttributeNames.ORACLE_POOL_MIN]: POOL_CONFIG.poolMin,
@@ -131,7 +138,7 @@ const POOL_ATTRIBUTES = {
 };
 
 const CONN_FAILED_ATTRIBUTES = {
-  [SEMATTRS_DB_SYSTEM]: DBSYSTEMVALUES_ORACLE,
+  [ATTR_DB_SYSTEM]: DB_SYSTEM_VALUE_ORACLE,
   [SEMATTRS_DB_CONNECTION_STRING]: CONFIG.connectString,
   [SEMATTRS_DB_USER]: CONFIG.user,
 };
@@ -170,14 +177,14 @@ function updateAttrSpanList(connection: oracledb.Connection) {
   let attributes: Record<string, string | number>;
   if (oracledb.thin) {
     attributes = { ...DEFAULT_ATTRIBUTES };
-    attributes[SEMATTRS_NET_PEER_NAME] = connAttributes[SEMATTRS_NET_PEER_NAME];
-    attributes[SEMATTRS_NET_PEER_PORT] = connAttributes[SEMATTRS_NET_PEER_PORT];
+    attributes[ATTR_SERVER_ADDRESS] = connAttributes[ATTR_SERVER_ADDRESS];
+    attributes[ATTR_SERVER_PORT] = connAttributes[ATTR_SERVER_PORT];
     attributes[SEMATTRS_NET_TRANSPORT] = connAttributes[SEMATTRS_NET_TRANSPORT];
   } else {
     attributes = { ...DEFAULT_ATTRIBUTES_THICK };
     numExecSpans = 1;
   }
-  attributes[SEMATTRS_DB_NAME] = connAttributes[SEMATTRS_DB_NAME];
+  attributes[ATTR_DB_NAMESPACE] = connAttributes[ATTR_DB_NAMESPACE];
 
   // initialize the span attributes list.
   connAttrList = [];
@@ -386,13 +393,13 @@ describe('oracledb', () => {
       connAttributes[AttributeNames.ORACLE_INSTANCE] = connection.instanceName;
     }
     if (connection.serviceName) {
-      connAttributes[SEMATTRS_DB_NAME] = connection.serviceName;
+      connAttributes[ATTR_DB_NAMESPACE] = connection.serviceName;
     }
     if (oracledb.thin && extendedConn.hostName) {
-      connAttributes[SEMATTRS_NET_PEER_NAME] = extendedConn.hostName;
+      connAttributes[ATTR_SERVER_ADDRESS] = extendedConn.hostName;
     }
     if (oracledb.thin && (extendedConn.port as number)) {
-      connAttributes[SEMATTRS_NET_PEER_PORT] = extendedConn.port;
+      connAttributes[ATTR_SERVER_PORT] = extendedConn.port;
     }
     if (oracledb.thin && extendedConn.protocol) {
       connAttributes[SEMATTRS_NET_TRANSPORT] = extendedConn.protocol;
@@ -406,24 +413,24 @@ describe('oracledb', () => {
 
     executeAttributes = {
       ...connAttributes,
-      [SEMATTRS_DB_OPERATION]: 'SELECT',
+      [ATTR_DB_OPERATION_NAME]: 'SELECT',
     };
     if (oracledb.thin) {
       // internal roundtrips don't have bind values.
       executeAttributesInternalRoundTripBinds = {
         ...connAttributes,
-        [SEMATTRS_DB_OPERATION]: 'SELECT',
+        [ATTR_DB_OPERATION_NAME]: 'SELECT',
         [SEMATTRS_DB_STATEMENT]: sqlWithBinds,
       };
     }
     attributesWithSensitiveDataNoBinds = {
       ...connAttributes,
-      [SEMATTRS_DB_OPERATION]: 'SELECT',
+      [ATTR_DB_OPERATION_NAME]: 'SELECT',
       [SEMATTRS_DB_STATEMENT]: sql,
     };
     attributesWithSensitiveDataBinds = {
       ...connAttributes,
-      [SEMATTRS_DB_OPERATION]: 'SELECT',
+      [ATTR_DB_OPERATION_NAME]: 'SELECT',
       [SEMATTRS_DB_STATEMENT]: sqlWithBinds,
       [AttributeNames.ORACLE_BIND_VALUES]: binds,
     };
@@ -1035,7 +1042,7 @@ describe('oracledb', () => {
 
         // update sql stmt, operation.
         const attrs = { ...attributesWithSensitiveDataNoBinds };
-        attrs[SEMATTRS_DB_OPERATION] = 'BEGIN';
+        attrs[ATTR_DB_OPERATION_NAME] = 'BEGIN';
         attrs[SEMATTRS_DB_STATEMENT] = sqlWithOutBinds;
 
         try {
@@ -1117,7 +1124,7 @@ describe('oracledb', () => {
             string | number | any[]
           > = {
             ...connAttributes,
-            [SEMATTRS_DB_OPERATION]: 'SELECT',
+            [ATTR_DB_OPERATION_NAME]: 'SELECT',
             [SEMATTRS_DB_STATEMENT]: sql,
             [AttributeNames.ORACLE_BIND_VALUES]: bindsM,
           };