Documentation Grafana Cloud Instrument and send data Grafana Alloy Reference Components prometheus prometheus.exporter.oracledb

prometheus.exporter.oracledb

The prometheus.exporter.oracledb component embeds the oracledb_exporter to collect statistics from one or more Oracle databases.

You can specify multiple prometheus.exporter.oracledb components by giving them different labels.

Prerequisites

prometheus.exporter.oracledb needs the Oracle Client libraries on the system that runs Alloy, and a database user that can read Oracle system views. You set up both outside Alloy before you configure the component.

Oracle Instant Client Basic

When you run the standalone binary, you must install the Oracle Instant Client Basic for your operating system. The exporter only requires the basic version.

Environment variables

Set the following environment variables so Alloy can find the Oracle Client libraries:

• LD_LIBRARY_PATH: The Oracle Instant Client library directory on Linux.
• DYLD_LIBRARY_PATH: The Oracle Instant Client library directory on macOS.
• ORACLE_BASE: The base directory for Oracle installations. Optional.
• ORACLE_HOME: The location of the Oracle Instant Client installation. Optional.
• TNS_ADMIN: The location of your Oracle wallet directory. Set this when you use wallet authentication. Optional.

Database user permissions

The database user in the connection string must have permissions to query Oracle system views. The user requires the SELECT_CATALOG_ROLE role, or SELECT privilege on specific system views.

Refer to the Oracle AI Database Metrics Exporter Installation guide for the complete list of required permissions.

Usage

Alloy Copy

prometheus.exporter.oracledb "<LABEL>" {
  database {
    name              = "<DATABASE_NAME>"
    connection_string = "<CONNECTION_STRING>"
  }
}

Arguments

You can use the following arguments with prometheus.exporter.oracledb:

The exporter collects a built-in set of metrics. Set default_metrics to replace the built-in set with your own file. Set custom_metrics to add metrics to the set. A custom metric replaces a built-in metric when both use the same context and field names.

Refer to the oracledb_exporter repository for examples of TOML metrics files.

The component sets the instance label on its exported targets to the host and port portion of the connection string. Refer to Multiple databases for the instance label value when you configure more than one database block.

Blocks

You can use the following blocks with prometheus.exporter.oracledb:

Configure one or more database blocks, or the deprecated connection_string argument, but not both.

database

The database block configures an Oracle database for the component to scrape.

You can use the following arguments with the database block:

Each database block must have a name that’s unique within the component. The exporter uses the name argument as the value of the database label on the metrics it collects from this database.

The connection_string argument accepts an oracle:// URL with the username and password embedded:

text Copy

oracle://<USERNAME>:<PASSWORD>@<HOST>:<PORT>/<SERVICE_NAME>[?<OPTION_1>=<VALUE_1>[&<OPTION_N>=<VALUE_N>]]

It also accepts an address without a scheme, where you set the username and password arguments separately:

text Copy

<HOST>:<PORT>/<SERVICE_NAME>[?<OPTION_1>=<VALUE_1>[&<OPTION_N>=<VALUE_N>]]

Set username and password only with the second format. The component returns an error if you set either argument together with an oracle:// connection string.

Multiple databases

Configure a database block for each Oracle database you want to scrape from one component. The component connects to every database you configure and exports a single target for all of them.

When you configure more than one database block, no single host identifies the target, so the component sets the instance label to the component ID, for example, prometheus.exporter.oracledb.example. Use the database label, which the exporter sets to each block’s name, to tell the metrics from each database apart.

Refer to the Example for a configuration that scrapes two databases.

Exported fields

Component health

prometheus.exporter.oracledb is only reported as unhealthy if given an invalid configuration. In those cases, exported fields retain their last healthy values.

Debug information

prometheus.exporter.oracledb doesn’t expose any component-specific debug information.

Debug metrics

prometheus.exporter.oracledb doesn’t expose any component-specific debug metrics.

Example

The following example collects metrics from two Oracle databases:

Alloy Copy

prometheus.exporter.oracledb "example" {
  database {
    name              = "primary"
    connection_string = "db-primary.example.com:1521/ORCL"
    username          = "<DB_USERNAME>"
    password          = "<DB_PASSWORD>"
  }

  database {
    name              = "standby"
    connection_string = "db-standby.example.com:1521/ORCL"
    username          = "<DB_USERNAME>"
    password          = "<DB_PASSWORD>"
  }
}

// Configure a prometheus.scrape component to collect oracledb metrics.
prometheus.scrape "demo" {
  targets    = prometheus.exporter.oracledb.example.targets
  forward_to = [prometheus.remote_write.demo.receiver]
}

prometheus.remote_write "demo" {
  endpoint {
    url = "<PROMETHEUS_REMOTE_WRITE_URL>"

    basic_auth {
      username = "<USERNAME>"
      password = "<PASSWORD>"
    }
  }
}

Replace the following:

• <DB_USERNAME>: The username for the Oracle database.
• <DB_PASSWORD>: The password for the Oracle database.
• <PROMETHEUS_REMOTE_WRITE_URL>: The URL of the Prometheus remote_write compatible server to send metrics to.
• <USERNAME>: The username to use for authentication to the remote_write API.
• <PASSWORD>: The password to use for authentication to the remote_write API.

Compatible components

prometheus.exporter.oracledb has exports that can be consumed by the following components:

• Components that consume Targets