From 364e9a7e6bb6b11c9813f96edcdfc8e93ed70061 Mon Sep 17 00:00:00 2001 From: Mike Peralta Date: Wed, 13 May 2026 15:35:41 -0400 Subject: [PATCH] Add oracle instance scoping configuration page Co-Authored-By: Claude Sonnet 4.6 (1M context) --- config/_default/menus/main.en.yaml | 5 + .../architecture/oracle.md | 175 ++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 content/en/database_monitoring/architecture/oracle.md diff --git a/config/_default/menus/main.en.yaml b/config/_default/menus/main.en.yaml index b50ecdb5347..310d0e547a8 100644 --- a/config/_default/menus/main.en.yaml +++ b/config/_default/menus/main.en.yaml @@ -4635,6 +4635,11 @@ menu: parent: dbm identifier: dbm_setup_architecture weight: 2 + - name: Oracle Configurations + url: database_monitoring/architecture/oracle/ + parent: dbm_setup_architecture + identifier: dbm_architecture_oracle + weight: 4 - name: Setting Up Postgres url: database_monitoring/setup_postgres/ parent: dbm diff --git a/content/en/database_monitoring/architecture/oracle.md b/content/en/database_monitoring/architecture/oracle.md new file mode 100644 index 00000000000..ccc0550310f --- /dev/null +++ b/content/en/database_monitoring/architecture/oracle.md @@ -0,0 +1,175 @@ +--- +title: Oracle Configurations +description: Configure Oracle instance scoping for Database Monitoring using PDB-level, CDB listener, and CDB$ROOT approaches. +further_reading: +- link: "/database_monitoring/architecture/" + tag: "Documentation" + text: "DBM Setup Architectures" +- link: "/database_monitoring/setup_oracle/" + tag: "Documentation" + text: "Setting up Oracle" +--- + +## Overview + +Each check instance in the Datadog Agent configuration creates one Database Monitoring (DBM) instance. The [database_identifier](/database_monitoring/guide/database_identifier/) template determines what the Agent considers a distinct DBM instance. + +The key configuration lever is `service_name`, which determines whether you connect to `CDB$ROOT` or a specific PDB. + +Available template variables: `$resolved_hostname`, `$server`, `$port`, `$service_name`, `$cdb_name` (from `v$database`), plus any key from tags. + +Common users (C## prefix, created with `CONTAINER=ALL`) are required for multitenant monitoring. + +For non-multitenant Oracle (pre-12c or non-CDB), use host-level scoping with `$resolved_hostname`. + +**Scenario**: `oracle-prod.example.com` with two Oracle CDBs: + +| CDB | Port | PDBs | +|---|---|---| +| ORCL | 1521 | CRMDB, ERPDB | +| FINDB | 1522 | ACCOUNTS | + +## Option 1: PDB level (recommended) + +
Use PDB-level scoping ($cdb_name-$service_name). Connecting through each PDB's service name gives isolated DBM data scoped to that PDB's session activity. Add a CDB$ROOT entry alongside PDB entries if you also need server-level Oracle metrics visible only from CDB$ROOT.
+ +One entry per PDB using the PDB-specific service name. Each connection scopes directly into that PDB. Metrics, query samples, and explain plans reflect only that PDB's activity. + +Based on the example scenario above, this counts as three DBM instances. + +```yaml +instances: + - server: oracle-prod.example.com:1521 + service_name: CRMDB + username: c##datadog + password: "" + dbm: true + database_identifier: + template: "$cdb_name-$service_name" # → "orcl-CRMDB" + + - server: oracle-prod.example.com:1521 + service_name: ERPDB + username: c##datadog + password: "" + dbm: true + database_identifier: + template: "$cdb_name-$service_name" # → "orcl-ERPDB" + + - server: oracle-prod.example.com:1522 + service_name: ACCOUNTS + username: c##datadog + password: "" + dbm: true + database_identifier: + template: "$cdb_name-$service_name" # → "findb-ACCOUNTS" +``` + +The Agent automatically adds a `pdb:` tag when it detects a PDB connection. + +## Option 2: CDB listener level + +
Use CDB listener level when you need to monitor all PDBs through a single connection per CDB. All PDBs are visible through CDB_* views from CDB$ROOT.
+ +One entry per CDB listener (port). Both CDBs are covered with distinct identifiers. + +Based on the example scenario above, this counts as two DBM instances. + +```yaml +instances: + - server: oracle-prod.example.com:1521 + service_name: ORCL + username: c##datadog + password: "" + dbm: true + database_identifier: + template: "$resolved_hostname:$port" # → "oracle-prod.example.com:1521" + + - server: oracle-prod.example.com:1522 + service_name: FINDB + username: c##datadog + password: "" + dbm: true + database_identifier: + template: "$resolved_hostname:$port" # → "oracle-prod.example.com:1522" +``` + +## Option 3: CDB$ROOT level + +
Use CDB$ROOT level when logical container names are preferred over network addresses in identifiers. Coverage is the same as Option 2.
+ +Same connections as Option 2, but the identifier uses `$cdb_name` to reflect the logical container name rather than the network address. + +Based on the example scenario above, this counts as two DBM instances. + +```yaml +instances: + - server: oracle-prod.example.com:1521 + service_name: ORCL + username: c##datadog + password: "" + dbm: true + database_identifier: + template: "$cdb_name" # → "orcl" + + - server: oracle-prod.example.com:1522 + service_name: FINDB + username: c##datadog + password: "" + dbm: true + database_identifier: + template: "$cdb_name" # → "findb" +``` + +`service_name` is the scope selector: CDB service name connects to `CDB$ROOT`, PDB service name connects to that PDB. `$cdb_name` is resolved live from `v$database.NAME`. + +## Managed services + +### Oracle Autonomous Database + +Oracle Autonomous Database (ADB) requires mutual TLS (mTLS) through an Oracle Wallet. Use predefined service names representing workload profiles (`_high`, `_medium`, `_low`, `_tp`, `_tpurgent`). + +```yaml +instances: + - server: adb.example.oraclecloud.com:1522 + service_name: mydb_high + username: ADMIN + password: "" + protocol: TCPS + wallet: /path/to/wallet_mydb + dbm: true + database_identifier: + template: "$resolved_hostname:$port" +``` + +### Oracle Exadata + +Exadata is a hardware platform. Apply the scoping approach based on the Oracle architecture deployed on it: CDB/PDB → PDB level; RAC → one entry per node; standalone → host level. + +### Oracle RAC (Real Application Clusters) + +Connect to each RAC node individually through its local listener. Never use the SCAN address. It may route to a different node between check cycles. + +```yaml +instances: + # RAC Node 1 + - server: rac-node1.example.com:1521 + service_name: ORCL + username: c##datadog + password: "" + dbm: true + reported_hostname: rac-node1 + database_identifier: + template: "$cdb_name-node1" + + # RAC Node 2 + - server: rac-node2.example.com:1521 + service_name: ORCL + username: c##datadog + password: "" + dbm: true + reported_hostname: rac-node2 + database_identifier: + template: "$cdb_name-node2" +``` + +{{< partial name="whats-next/whats-next.html" >}}