@opentelemetry/instrumentation-oracledb

OpenTelemetry OracleDB Instrumentation for Node.js

This module provides automatic instrumentation for the oracledb module.

If total installation size is not constrained, it is recommended to use the @opentelemetry/auto-instrumentations-node bundle with @opentelemetry/sdk-node for the most seamless instrumentation experience.

Compatible with OpenTelemetry JS API and SDK 1.0+.

Installation

npm install --save @opentelemetry/instrumentation-oracledb

Supported Versions

• oracledb versions >=6.7.0 <8

Usage

OpenTelemetry OracleInstrumentation allows the user to automatically collect trace data and export them to the backend of choice, to give observability to distributed systems when working with oracledb. This module works with both Thin and Thick modes of the oracledb package, although there may be some caveats with Thick Mode now, which are listed in a later paragraph.

To enable a specific instrumentation, pass it to registerInstrumentations(). This is commonly done via NodeSDK for fully setting up all OpenTelemetry SDK components:

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { OracleInstrumentation } = require('@opentelemetry/instrumentation-oracledb');

const sdk = new NodeSDK({
  instrumentations: [
    new OracleInstrumentation(),
  ],
});
sdk.start();
process.once('beforeExit', async () => { await sdk.shutdown(); });

Caveats with oracledb Thick mode:

• RoundTrip Spans will not appear for Thick Mode
• Hostname will not be available in Thick Mode

This instrumentation supports both Thin and Thick mode in oracledb.

Span Types Created

This instrumentation creates spans for connection establishment, query execution, and LOB operations.

Span Name	Description	When Created
oracledb.getConnection	Standalone connection acquisition	When oracledb.getConnection() is called
oracledb.createPool	Pool creation	When oracledb.createPool() is called
oracledb.Pool.getConnection	Pool connection acquisition	When pool.getConnection() is called
oracledb.Connection.execute:<OPERATION> <db.namespace>	SQL execution	When connection.execute() is called
oracledb.Connection.executeMany:<OPERATION> <db.namespace>	Batch SQL execution	When connection.executeMany() is called
oracledb.Connection.close	Connection close	When connection.close() is called
oracledb.Connection.createLob	Temporary LOB creation	When connection.createLob() is called
oracledb.Lob.getData	LOB data read	When lob.getData() is called

For Thin mode, additional internal round-trip spans will be emitted, such as:

• oracledb.FastAuthMessage
• oracledb.AuthMessage
• oracledb.ProtocolMessage
• oracledb.DataTypeMessage
• oracledb.ExecuteMessage
• oracledb.LogOffMessage
• oracledb.LobOpMessage

OracleDB Instrumentation Options

Options	Type	Default	Description
enhancedDatabaseReporting	boolean	false	If true, adds SQL bind values as db.operation.parameter.<key> attributes. When enabled, it also records db.query.text. This can capture sensitive data and should be used with care.
dbStatementDump	boolean	false	If true, records the SQL statement as db.query.text.
requestHook	OracleInstrumentationExecutionRequestHook	undefined	Hook for adding custom span attributes based on the query input and connection metadata.
responseHook	OracleInstrumentationExecutionResponseHook	undefined	Hook for adding custom span attributes based on the database response.
requireParentSpan	boolean	false	If true, only creates spans when there is an active parent span.
propagateTraceContextToSessionAction	boolean	false	If true, injects W3C Trace Context into the Oracle V$SESSION.ACTION field so database-side tracing can be correlated with application spans.

OracleDB-specific Notes

• Thin mode emits internal round-trip spans. Thick mode does not.
• Thick mode does not expose the same low-level network metadata, so attributes such as server.address, server.port, and network.transport are missing.
• Oracle connection metadata such as oracle.db.name, oracle.db.instance.name, oracle.db.pdb, oracle.db.domain, and the final effective oracle.db.service are only available after connection metadata has been resolved by the driver.
• Failed logins may still include the attempted service name, which is useful for debugging connection issues.

Semantic Conventions

This instrumentation now emits the current Oracle database semantic conventions directly.

This includes:

• db.namespace using Oracle DB_UNIQUE_NAME
• removal of db.user
• Oracle-specific attributes such as oracle.db.domain, oracle.db.instance.name, oracle.db.name, oracle.db.pdb, and oracle.db.service when available

This is a breaking semantic change from the older OracleDB instrumentation behavior, where db.namespace used a concatenated <instance>|<pdb>|<service> value and db.user was emitted.

The Oracle-specific oracle.db.* attributes are currently Release Candidate in the semantic conventions.

Attributes collected

Breaking semantic changes:

Previous behavior	Current behavior	Short Description
db.user	Removed	Database user name
db.namespace="<instance>|<pdb>|<service>"	db.namespace="<dbUniqueName>"	Oracle database identifier now uses DB_UNIQUE_NAME.

Other emitted attributes:

Attribute	Short Description
db.system.name	Database product identifier
network.transport	Network transport
server.address	Remote database host
server.port	Remote database port
db.query.text	SQL text when dbStatementDump or enhancedDatabaseReporting is enabled

Attribute	Short Description
oracle.db.name	Database name
oracle.db.instance.name	Oracle instance name
oracle.db.pdb	Pluggable database name
oracle.db.domain	Database domain
oracle.db.service	Effective Oracle service name

Useful links

• For more information on OpenTelemetry, visit: https://opentelemetry.io/
• For more about OpenTelemetry JavaScript: https://github.com/open-telemetry/opentelemetry-js
• For help or feedback on this project, join us in GitHub Discussions

License

Apache 2.0 - See LICENSE for more information.