Documentation Grafana Alloy Reference Components prometheus prometheus.exporter.oracledb

prometheus.exporter.oracledb

The prometheus.exporter.oracledb component embeds oracledb_exporter for collecting statistics from one or more OracleDB servers.

Ensure you have the following:

• Oracle Instant Client Basic installed on the system running Alloy
• Appropriate environment variables configured for Oracle Client libraries

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 for Oracle Client library access:

• Linux: Set LD_LIBRARY_PATH to the Oracle Instant Client library directory
• macOS (ARM): Set DYLD_LIBRARY_PATH to the Oracle Instant Client library directory
• ORACLE_BASE (optional): Base directory for Oracle installations
• ORACLE_HOME (optional): Location of the Oracle Instant Client installation
• TNS_ADMIN (optional): Location of your Oracle wallet directory when using wallet authentication

Database user permissions

The database user specified 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>" {
    connection_string = "<CONNECTION_STRING>"
}

Arguments

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

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

For backward compatibility, you can still provide the username and password arguments in the connection_string argument:

conn Copy

oracle://user:pass@host:port/service_name[?OPTION1=VALUE1[&OPTIONn=VALUEn]...]

If the connection_string argument doesn’t contain the username and password, you must provide the username and password arguments. In this case, the URL must have the format:

conn Copy

host:port/service_name[?OPTION1=VALUE1[&OPTIONn=VALUEn]...]

Multiple databases

To scrape several databases from one component, define one or more database blocks instead of using connection_string at the top level. You must not set both connection_string and database blocks.

The name argument is the database name used by the exporter (for example as the database label on metrics). Each block supports the same connection string rules as the top-level connection_string, including optional per-block username and password.

Blocks

database

The database block configures a single Oracle target when using multi-database mode.

The name argument identifies this database in the exporter configuration and must be unique within the component.

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 uses a prometheus.scrape component to collect metrics from prometheus.exporter.oracledb:

Alloy Copy

prometheus.exporter.oracledb "example" {
  connection_string = "localhost:1521/orcl.localnet"
  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>"
    }
  }
}

Multi-database example:

Alloy Copy

prometheus.exporter.oracledb "multi" {
  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>"
  }
}

Replace the following:

• <DB_USERNAME>: The database username
• <DB_PASSWORD>: The password for the database user
• <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