Add OpenTelemetry support

Author: sharadraju

doc/src/release_notes.rst

@@ -13,6 +13,9 @@ node-oracledb `v6.7.0 <https://github.com/oracle/node-oracledb/compare/v6.6.0...
 Common Changes
 ++++++++++++++
 
+#)  Added support to enable tracing with the OpenTelemetry
+    module for Oracle Database being created in the OpenTelemetry project.
+
 #)  Added support to connect to Oracle Database using wallets stored in
     Azure Key Vault and OCI Vault.
 

lib/connection.js

@@ -869,10 +869,15 @@ class Connection extends EventEmitter {
     let binds = [];
     let options = {};
 
+    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
+
     // process arguments
     if (nodbUtil.isObject(sql) && typeof sql.statement === 'string') {
       errors.assertArgCount(arguments, 1, 2);
       if (sql.values) {
+        if (this._impl._callLevelTraceData) {
+          this._impl._callLevelTraceData.values = sql.values;
+        }
         binds = await this._processExecuteBinds(sql.values);
       }
       sql = sql.statement;
@@ -883,18 +888,23 @@ class Connection extends EventEmitter {
       errors.assertArgCount(arguments, 1, 3);
       errors.assertParamValue(typeof sql === 'string', 1);
       if (arguments.length >= 2) {
+        if (this._impl._callLevelTraceData) {
+          this._impl._callLevelTraceData.values = a2;
+        }
         binds = await this._processExecuteBinds(a2);
       }
       if (arguments.length == 3) {
         options = this._verifyExecOpts(a3, false);
       }
     }
     this._addDefaultsToExecOpts(options);
-    errors.assert(this._impl, errors.ERR_INVALID_CONNECTION);
 
     // perform actual execute
     let result;
     try {
+      if (this._impl._callLevelTraceData) {
+        this._impl._callLevelTraceData.statement = sql;
+      }
       result = await this._impl.execute(sql, numIters, binds, options, false);
     } catch (err) {
       if (err.errorNum === 1406)
@@ -1035,6 +1045,63 @@ class Connection extends EventEmitter {
     return this._impl && this._impl.getDbName();
   }
 
+  //---------------------------------------------------------------------------
+  // hostName (READONLY)
+  //
+  // Property for identifying the hostName of the Oracle Database.
+  //---------------------------------------------------------------------------
+  get hostName() {
+    return this._impl && this._impl.getHostName();
+  }
+
+  //---------------------------------------------------------------------------
+  // port (READONLY)
+  //
+  // Property for identifying the port to which client is connected.
+  //---------------------------------------------------------------------------
+  get port() {
+    return this._impl && this._impl.getPort();
+  }
+
+  //---------------------------------------------------------------------------
+  // protocol (READONLY)
+  //
+  // Property for identifying the protocol used to connect to Oracle Database.
+  //---------------------------------------------------------------------------
+  get protocol() {
+    return this._impl && this._impl.getProtocol();
+  }
+
+  //---------------------------------------------------------------------------
+  // connectString (READONLY)
+  //
+  // User provided connectString to connect to Oracle Database.
+  //---------------------------------------------------------------------------
+  get connectString() {
+    return this._impl && this._impl._connectString;
+  }
+
+  //---------------------------------------------------------------------------
+  // user
+  //
+  // User property provided to connect to Oracle Database.
+  //---------------------------------------------------------------------------
+  get user() {
+    if (this.currentSchema.length) {
+      return this.currentSchema;
+    }
+    return this._impl && this._impl._user;
+  }
+
+  //---------------------------------------------------------------------------
+  // connectTraceConfig
+  //
+  // Property for getting the connection related config.
+  //---------------------------------------------------------------------------
+  get connectTraceConfig() {
+    return this._impl && this._impl._getConnectTraceConfig();
+  }
+
   //---------------------------------------------------------------------------
   // getDbObjectClass()
   //

lib/impl/aqQueue.js

@@ -27,8 +27,9 @@
 'use strict';
 
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class AqQueueImpl {
+class AqQueueImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

lib/impl/base.js

@@ -0,0 +1,45 @@
+// Copyright (c) 2024, Oracle and/or its affiliates.
+
+//-----------------------------------------------------------------------------
+//
+// This software is dual-licensed to you under the Universal Permissive License
+// (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
+// 2.0 as shown at http://www.apache.org/licenses/LICENSE-2.0. You may choose
+// either license.
+//
+// If you elect to accept the software under the Apache License, Version 2.0,
+// the following applies:
+//
+// 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.
+//
+//-----------------------------------------------------------------------------
+
+'use strict';
+
+class BaseImpl {
+
+  //---------------------------------------------------------------------------
+  // _getConnectTraceConfig()
+  //
+  // Retrieves connect trace config from connection object.
+  //---------------------------------------------------------------------------
+  _getConnectTraceConfig() {
+    const connImpl = this._getConnImpl();
+    if (connImpl) {
+      return connImpl._getConnectTraceConfig();
+    }
+  }
+
+}
+
+module.exports = BaseImpl;

lib/impl/connection.js

@@ -69,6 +69,32 @@ class ConnectionImpl {
     return this;
   }
 
+  //---------------------------------------------------------------------------
+  // _getConnectTraceConfig()
+  //
+  // returns the necessary connection config used for debug/trace.
+  // ---------------------------------------------------------------------------
+  _getConnectTraceConfig() {
+    let traceConfig;
+
+    if (this._pool) {
+      traceConfig = this._pool._getConnectTraceConfig();
+    } else {
+      traceConfig = {connectString: this._connectString, user: this._user};
+    }
+    traceConfig.serviceName = this.getServiceName();
+    traceConfig.instanceName = this.getInstanceName();
+    traceConfig.pdbName = this.getDbName();
+
+    // Thick mode doesnt have these properties for now.
+    if (settings.thin) {
+      traceConfig.hostName = this.getHostName();
+      traceConfig.port = this.getPort();
+      traceConfig.protocol = this.getProtocol();
+    }
+    return traceConfig;
+  }
+
   //---------------------------------------------------------------------------
   // _getDbObjectType()
   //
@@ -589,6 +615,33 @@ class ConnectionImpl {
     errors.throwNotImplemented("unsubscribing from events");
   }
 
+  //---------------------------------------------------------------------------
+  // getHostName()
+  //
+  // Returns the Oracle Database host name associated with the connection.
+  //---------------------------------------------------------------------------
+  getHostName() {
+    errors.throwNotImplemented("getting HostName");
+  }
+
+  //---------------------------------------------------------------------------
+  // getPort()
+  //
+  // Returns the Oracle Database port number associated with the connection.
+  //---------------------------------------------------------------------------
+  getPort() {
+    errors.throwNotImplemented("getting Port");
+  }
+
+  //---------------------------------------------------------------------------
+  // getProtocol()
+  //
+  // Returns the protocol associated with the connection.
+  //---------------------------------------------------------------------------
+  getProtocol() {
+    errors.throwNotImplemented("getting Protocol");
+  }
+
 }
 
 // export just the class

lib/impl/lob.js

@@ -28,8 +28,9 @@
 
 const ConnectionImpl = require('./connection.js');
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class LobImpl {
+class LobImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

lib/impl/pool.js

@@ -174,6 +174,21 @@ class PoolImpl {
     errors.throwNotImplemented("getting the pool statement cache size");
   }
 
+  //---------------------------------------------------------------------------
+  // _getConnectTraceConfig()
+  //
+  // Returns the necessary connection config used by pool for debug/trace.
+  //---------------------------------------------------------------------------
+  _getConnectTraceConfig() {
+    return {
+      connectString: this._connectString,
+      user: this._user,
+      poolMin: this.getPoolMin(),
+      poolMax: this.getPoolMax(),
+      poolIncrement: this.getPoolIncrement()
+    };
+  }
+
   //---------------------------------------------------------------------------
   // getSodaMetaDataCache()
   //

lib/impl/resultset.js

@@ -34,9 +34,10 @@ const future = require('../future.js');
 const types = require('../types.js');
 const Lob = require('../lob.js');
 const oson = require('./datahandlers/oson.js');
+const BaseImpl = require('./base.js');
 
 // define implementation class
-class ResultSetImpl {
+class ResultSetImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _determineFetchType()

lib/impl/sodaCollection.js

@@ -27,8 +27,9 @@
 'use strict';
 
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class SodaCollectionImpl {
+class SodaCollectionImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()

lib/impl/sodaDatabase.js

@@ -27,8 +27,9 @@
 'use strict';
 
 const errors = require('../errors.js');
+const BaseImpl = require('./base.js');
 
-class SodaDatabaseImpl {
+class SodaDatabaseImpl extends BaseImpl {
 
   //---------------------------------------------------------------------------
   // _getConnImpl()