@opentelemetry/instrumentation-oracledb

This OpenTelemetry instrumentation package provides automatic span creation for oracledb queries with minimal configuration. In production use, it safely captures SQL statements and connection metadata without exposing credentials - connection strings are sanitized by default, which is crucial since Oracle connection configs often contain sensitive parameters. The instrumentation hooks cleanly into oracledb's callback and promise-based APIs.

Error handling is well-designed from a security perspective. Stack traces in spans don't leak connection details, and bind parameters are redacted by default unless you explicitly enable them. The library follows secure-by-default principles - you opt into more verbose logging rather than having to opt out. Integration with OpenTelemetry's context propagation works reliably for tracking queries across service boundaries.

The main limitation is dependency on the broader OpenTelemetry SDK ecosystem, which means you're pulling in a significant dependency tree. Updates sometimes lag behind oracledb client library changes, though the maintainers have been responsive to compatibility issues in my experience.

Getting started with this package is straightforward if you're already familiar with OpenTelemetry. The auto-instrumentation works as expected - just register the instrumentation and your Oracle DB queries automatically generate spans with query text, parameters, and timing. The integration is minimal code: typically just adding it to your instrumentation array alongside other OpenTelemetry instrumentations.

The main challenge is the learning curve isn't about this package specifically, but understanding OpenTelemetry's broader ecosystem. You need to configure exporters, resource detection, and sampling separately. Error messages when misconfigured tend to be generic OpenTelemetry errors rather than oracledb-specific guidance. Documentation is sparse - mostly just a README with basic usage - so you'll need to rely on the general OpenTelemetry docs and your understanding of how instrumentations work.

In practice, it does what it promises reliably. Query spans include useful attributes like db.statement and db.operation. I haven't encountered bugs in production, and it handles connection pooling correctly. Debugging requires enabling OpenTelemetry's diagnostic logging, which can be verbose but ultimately helpful.

The @opentelemetry/instrumentation-oracledb package does exactly what it promises with minimal fuss. Setup is straightforward—register the instrumentation and your Oracle database queries automatically get traced with spans containing SQL statements, connection info, and timing data. The automatic span creation works reliably across promise-based and callback-style oracledb usage patterns.

Type definitions are well-structured and integrate cleanly with the core OpenTelemetry types. The instrumentation config options are sensible, including hooks for sanitizing sensitive data from SQL queries before they're recorded in spans. Error handling is transparent—database errors propagate normally while still being captured in span status and events.

The main gotcha is documentation being scattered across the OpenTelemetry docs site rather than consolidated in the package README. You'll need to reference the general instrumentation docs and examples from other database instrumentations to understand all configuration options. Also, semantic conventions for database spans occasionally lag behind spec updates, requiring manual attribute mapping for newer conventions.