Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat(oracledb): Add support for Oracle DB instrumentation #2612

Open
wants to merge 29 commits into
base: main
Choose a base branch
from

Conversation

sudarshan12s
Copy link

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..

Note:

  • As part of CI, i was getting regex ReDos for comment inside files. which can be ignored . I modified to make it safe..

Add Oracledb instrumentation
@sudarshan12s sudarshan12s requested a review from a team as a code owner December 20, 2024 17:52
Copy link

linux-foundation-easycla bot commented Dec 20, 2024

CLA Signed

The committers listed above are authorized under a signed CLA.

@sudarshan12s
Copy link
Author

sudarshan12s commented Jan 28, 2025

Please help me with steps for updating package-lock.json . This PR lock file package-lock.json differs from main and i am not able to keep it in sync easily..

I have fixed this discrepancy.

@JamieDanielson
Copy link
Member

@sudarshan12s as we discussed during SIG meeting yesterday, please review the requirements here for component ownership, as well as our preferred approach for long-term maintenance of instrumentation libraries.

@marcalff
Copy link
Member

@sudarshan12s as we discussed during SIG meeting yesterday, please review the requirements here for component ownership, as well as our preferred approach for long-term maintenance of instrumentation libraries.

To @JamieDanielson
Cc @open-telemetry/javascript-maintainers

Hi Jamie, All,

To become a member of CNCF, @sudarshan12s will need two sponsors for his application.

I am myself an Oracle employee, one of the maintainers of the opentelemetry-cpp repository, and can sponsor Sudarshan.

Could you, or someone in javascript-maintainers, be the second sponsor ?
I think it makes the most sense, since Sudarshan contribution(s) are in the js-contrib space.

Regards,
-- Marc

@@ -0,0 +1,55 @@
/*
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should this content be moved under constants.ts?

@pichlermarc
Copy link
Member

Hi @sudarshan12s. I was absent during last week's SIG meeting so I'm not sure if there was an agreement made to not apply the current guidelines, but there are rules and guidelines for new instrumentations. These were introduced since many instrumentations were abandoned in this repository and we would like to avoid this in the future as it diverts resources from development of OTel core components.

Before opening a PR, the following questions should be answered, see Jamie's link:

  • who's going to maintain it (2 people minimum, both must be members of the OTel org prior to opening the PR)
  • why not host it in a separate repo? (hosting it here has maintenance implications for the repo, the less we have to host here, the better the quality of other components like the API and SDK is going to be as we get to spend more time on that)

This is done in the form of an instrumentation request.

@sudarshan12s
Copy link
Author

Hi @sudarshan12s. I was absent during last week's SIG meeting so I'm not sure if there was an agreement made to not apply the current guidelines, but there are rules and guidelines for new instrumentations. These were introduced since many instrumentations were abandoned in this repository and we would like to avoid this in the future as it diverts resources from development of OTel core components.

Before opening a PR, the following questions should be answered, see Jamie's link:

  • who's going to maintain it (2 people minimum, both must be members of the OTel org prior to opening the PR)
  • why not host it in a separate repo? (hosting it here has maintenance implications for the repo, the less we have to host here, the better the quality of other components like the API and SDK is going to be as we get to spend more time on that)

This is done in the form of an instrumentation request.

Thanks @pichlermarc , Yes we were informed on the guidelines/procedure to be followed in the last SIG. I have updated the instrumentation request here with more details. Let me know if this looks fine. For becoming members of OTel org, @marcalff has agreed for first sponsor. Can someone from javascript-maintainers be the second sponsor.

* See the License for the specific language governing permissions and
* limitations under the License.
*
* Copyright (c) 2024, Oracle and/or its affiliates.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dyladan @open-telemetry/javascript-maintainers

is it ok to have copyright in opentelemetry files? just making sure...

* Copyright (c) 2024, Oracle and/or its affiliates.
* */

// Oracle specific attributes not covered by semantic conventions
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

suggestion: add a comment about these attributes being added to semconv as a different effort + link to PR if you have it

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am working on the PR for oracledb semconv.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link is also added in the code for the same.

additionalConfig?: any; // custom key/values associated with a function.
fn: Function; // Replaced with bind function associating the active context.
args?: any[]; // input arguments passed to the exported function.
userContext: InstrumentationContext;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

please add a short comment about this field, and how the driver uses it, so it's documented for future maintainers

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added following:

/**
   * This value is filled by instrumented module inside 'onEnterFn',
   * 'onBeginRoundTrip' hook functions, which is passed back by oracledb module
   * in 'onExitFn' and 'onEndRoundTrip' hook functions respectively.
   */

span: api.Span;
}

// Captures the entire span data
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can add a short comment documenting that this interface correlates to a js object that is exported from the instrumented package. preferably with a link

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added following:


// This corresponds to js object filled by the 'oracledb' module
// See: https://github.com/oracle/node-oracledb/blob/main/lib/traceHandler.js

ORACLE_IMPLICIT_RELEASE = 'db.oracle.implicit_release',
}

// Contains span names produced by instrumentation
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These span names actually correlates to the values being produced by the instrumented package itself, let's add it as a comment so people will know it's not arbitrary and will break if changed

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

comment is added as below

// These constants need to be in sync with what is generated by the
// 'oracledb' module.

);
}
if (traceContext.error) {
span.setStatus({
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

consider:

  span.recordException(traceContext.error);

which will log a span event for this error

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added it. Thanks.

tests are also modified to verify the event.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment