feat(oracledb): Add support for Oracle DB instrumentation

[sudarshan12s]

Add Oracledb instrumentation

Which problem is this PR solving?

Adding instrumentation support for node-oracledb applications connecting to Oracle database.

Short description of the changes

From node-oracledb version 6.7 onwards, oracledb module exports a class,
TraceHandlerBase which simulates interface kind of functionality with abstract methods to be overwritten by the derived class.

The current OT module derives this class TraceHandlerBase and implements abstract methods; It uses setTraceInstance method of oracledb module to register this new derived class OracleTelemetryTraceHandler
These methods are invoked by oracledb module providing the traceContext which is used to dump the data in to the span after converting to standard span attributes.

Following are the abstract methods implemented:

• onEnterFn -> It gets invoked by oracledb module when application invokes getConnection to create a connection to
  database or execute method to run a sql. It is invoked before invoking the public API calls made by application.
• onExitFn -> It gets invoked after the public API call is completed with success/failure.
• onBeginRoundTrip -> It gets invoked before round trip to database which was triggered as part of public API.
• onEndRoundTrip -> It gets invoked after round trip to database completes which was triggered as part of public API..

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: sudarshan12s / name: Sudarshan Soma (bf73ff5, 759ae13, 604f833, badc18a, ae1b7ac, 0290b81, 8ceff01, 91136ce, 6219bc4, f41f62c, e076936, d25ee8e, 3774f0d, 07c76fd, 34cd418, 440db83, 93d21e1, 2b310c5, 34ef02d, e19e1ea, 0e25652, 7f00bf6, e1698e1, c7fcb17, 91d65e4, 3ae4d72, 92c1c80, 6faff54, f670ac0, 77a08a7, 13e79db, d155fb8, 0704e73, f98c7a4, 4c36312, 5c4f37f, fa0463b, c299caa, 30a2367, 90db232, 382680c, 34afcad, a06b40f, 5c98035, 7cccc2e, 5faff20, c8e0be6, a0367cc, 5defed8, 4a154e5, 365d523, f8ff501, 2296e18, 988eab2)

[sudarshan12s]

Did another round of review and added few more comments.
Currently marking as "RequestChanges" due to the following 2 issues:

1. the copyright to oracle should be addressed (not sure in what way) @open-telemetry/javascript-maintainers
2. the instrumentation must not import from the instrumented package.

Thanks again

I have addressed the second point by including types , Please see.

I have removed the copyrights from src/. It is only added in component_owners.yml

[dyladan]

https://github.com/cncf/foundation/blob/main/copyright-notices.md#what-if-i-want-my-copyright-notice-included

[blumamir]

LGTM.

adding the relevant part from OpenTelemetry community regarding the copyright notice for future reference:

https://github.com/cncf/foundation/blob/main/copyright-notices.md#what-if-i-want-my-copyright-notice-included

[blumamir]

nit: instead of creating an if with >300 lines of code, we can revert the check and exist fast:

Suggested change

	if (traceHandlerBase) {
	if (!traceHandlerBase) {
	return undefined;
	}
	// else - all the code below, not nested and no indentation.

[sudarshan12s]

Done.

[sudarshan12s]

Hey @opentelemetry/javascript-approvers, I've incorporated the feedback received so far. If anyone else would like to take a look, I'd appreciate additional inputs!

Thanks.

[maryliag]

I don't think this PR should be merged until the Semantic Conventions PR for it is merged, since the definition can change there and you don't want to have something merged that is already out of date even before it gets released. And on that topic, why these attributes were not added to the semantic convention?
I imagine the goal is to have a similar instrumentation for oracle in the other SDKs, but how will Java or .NET know what names to use if they're not defined in the Semantic convention. They will have no idea that it was already implemented in JS and they should follow here. This is why the Semantic Conventions are so important. So please add a complete definition there with all attributes you're using in this instrumentation 😄

Also, as I mentioned in the SIG, really try to use already existing name attributes, for example, we have several attributes for pool already, so there is no need to create specific with oracle in the name.
You should check if we don't have for the others.

[sudarshan12s]

Thanks, @maryliag! I've started making the changes based on the inputs suggested in the semantic conventions PR.

I’ll use the existing attributes and retain only one entry in constants.ts, as it is specific to Oracle DRCP:
ORACLE_IMPLICIT_RELEASE = 'oracle.db.implicit_release',

For pool attributes, I plan to map them as follows:

oracledb.pool.max -> db.client.connection.max  
oracledb.pool.min -> db.client.connection.min  

I also requested clarification on whether db.client.connection.max and db.client.connection.min can be used in DB spans when the oracledb.createPool API is called, in addition to being included in metrics. They will not be dumped in subsequent DB queries.

For now, I’ve removed oracledb.pool_incr (I have not seen in existing attributes) but can add it back to the semantic conventions and instrumentation once I receive clarification on the above.

[sudarshan12s]

I have incorporated the changes based on the semantic conventions PR feedback received so far. The attribute oracle.db.implicit_release is still under review.

[sudarshan12s]

The semantic conventions PR has been merged. I've updated the implementation to incorporate these conventions—please take a look.

Below is an example showing span attributes aligned with the conventions:

For a SQL query like 'select :name from dual', where :name is a placeholder, the following attributes would be recorded:

spanName-> oracledb.Connection.execute:SELECT FREE|FREEPDB1|freepdb1 (It has Fnname:operationName db.namespace)
db.operation.name ='SELECT'
db.operation.parameter.name ='0'
db.query.text = 'select :name from dual'
db.system.name ='oracle.db'
db.namespace = 'FREE|FREEPDB1|freepdb1'. (It has instanceName | pdbname | serviceName)