# @opentelemetry/instrumentation-oracledb

> OpenTelemetry instrumentation for `oracledb` database client for Oracle DB

Latest version **0.48.0** (published 2026-10-06) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @opentelemetry/instrumentation-oracledb
pnpm add @opentelemetry/instrumentation-oracledb
yarn add @opentelemetry/instrumentation-oracledb
bun add @opentelemetry/instrumentation-oracledb
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.48.0 |
| Published | 2026-10-06 |
| First published | 2025-05-07 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | ^18.19.0 \|\| >=20.6.0 |
| Dependencies | 3 |
| Unpacked size | 122.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 931 |
| Author | OpenTelemetry Authors |
| Maintainers | dyladan, pichlermarc, overbalance, npmjs-account, trentm, martinkuba |
| Keywords | instrumentation, nodejs, opentelemetry, plugin, oracledb, profiling, tracing |

## Links

- npm: https://www.npmjs.com/package/@opentelemetry/instrumentation-oracledb
- Repository: https://github.com/open-telemetry/opentelemetry-js-contrib
- Homepage: https://github.com/open-telemetry/opentelemetry-js-contrib/tree/main/packages/instrumentation-oracledb#readme
- Issues: https://github.com/open-telemetry/opentelemetry-js-contrib/issues
- npm.io page: https://npm.io/package/@opentelemetry/instrumentation-oracledb

## Dependencies (3)

- [@opentelemetry/core](https://npm.io/package/@opentelemetry/core.md) ^2.9.0
- [@opentelemetry/instrumentation](https://npm.io/package/@opentelemetry/instrumentation.md) ^0.223.0
- [@opentelemetry/semantic-conventions](https://npm.io/package/@opentelemetry/semantic-conventions.md) ^1.34.0

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 0.48.0 (latest) — 2026-10-06
- 0.47.0 — 2026-08-31
- 0.46.0 — 2026-07-23
- 0.45.0 — 2026-07-03
- 0.44.0 — 2026-06-11
- 0.43.0 — 2026-05-13
- 0.42.0 — 2026-05-06
- 0.41.0 — 2026-04-29
- 0.40.0 — 2026-04-17
- 0.39.0 — 2026-03-26
- 0.38.0 — 2026-03-04
- 0.37.0 — 2026-02-17
- 0.36.0 — 2026-01-22
- 0.35.0 — 2026-01-15
- 0.34.1 — 2025-12-17
- … 11 more at https://npm.io/package/@opentelemetry/instrumentation-oracledb/versions

## README

# OpenTelemetry OracleDB Instrumentation for Node.js

[![NPM Published Version][npm-img]][npm-url]
[![Apache License][license-image]][license-image]

This module provides automatic instrumentation for the [`oracledb`](https://www.npmjs.com/package/oracledb) module.

If total installation size is not constrained, it is recommended to use the
[`@opentelemetry/auto-instrumentations-node`](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node)
bundle with
[`@opentelemetry/sdk-node`](https://www.npmjs.com/package/@opentelemetry/sdk-node)
for the most seamless instrumentation experience.

Compatible with OpenTelemetry JS API and SDK `1.0+`.

## Installation

```bash
npm install --save @opentelemetry/instrumentation-oracledb
```

## Supported Versions

- [`oracledb`](https://www.npmjs.com/package/oracledb) versions `>=6.7.0 <8`

> **Note:** Metrics are only emitted when using `oracledb` versions `>=7.0.0`.

## 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](https://www.npmjs.com/package/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:

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

### Metrics

Metrics are emitted for `oracledb` versions `>=7.0.0`, because the driver
metrics APIs used by this instrumentation are available from that version
onwards.

| Metric | Instrument | Unit | Description |
| ------ | ---------- | ---- | ----------- |
| `db.client.operation.duration` | Histogram | `s` | Duration of database client operations. |
| `db.client.connection.count` | UpDownCounter | `{connection}` | Number of pool connections currently in the state described by `db.client.connection.state`. |
| `db.client.connection.pending_requests` | UpDownCounter | `{request}` | Number of requests currently waiting for a pool connection. |
| `db.client.connection.timeouts` | Counter | `{timeout}` | Number of connection requests that timed out while waiting for a pool connection. |

The `db.client.operation.duration` metric includes these attributes when
available:

| Attribute | Description |
| --------- | ----------- |
| `db.system.name` | Always `oracle.db`. |
| `db.namespace` | Oracle database identifier. |
| `server.address` | Remote database host. |
| `server.port` | Remote database port. |
| `db.operation.name` | Parsed SQL operation name, such as `SELECT`, `PLSQL`, `BATCH INSERT`, or `BATCH PLSQL`. |
| `error.type` | Oracle error code when the operation fails. |

Pool metrics are updated when the driver reports pool lifecycle events,
including pool growth, shrink, acquire, release, wait, request timeout, and
close. `db.client.connection.count` emits one datapoint per pool state using
`db.client.connection.state` with values `idle` and `used`. Pool metrics include
`db.client.connection.pool.name`.

Pool names should be unique within the instrumented application. This
instrumentation uses `poolAlias` as `db.client.connection.pool.name` when it is
set. If `poolAlias` is not set, it falls back to the pool `connectString`, and
then to `default`. Applications that create multiple pools with the same
connection string should set distinct `poolAlias` values so those pools are
reported separately.

## 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][discussions-url]

## License

Apache 2.0 - See [LICENSE][license-url] for more information.

[discussions-url]: https://github.com/open-telemetry/opentelemetry-js/discussions
[license-url]: https://github.com/open-telemetry/opentelemetry-js-contrib/blob/main/LICENSE
[license-image]: https://img.shields.io/badge/license-Apache_2.0-green.svg?style=flat
[npm-url]: https://www.npmjs.com/package/@opentelemetry/instrumentation-oracledb
[npm-img]: https://badge.fury.io/js/%40opentelemetry%2Finstrumentation-oracledb.svg

---
_Source: https://npm.io/package/@opentelemetry/instrumentation-oracledb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._