Oracle Database receiver

The Oracle Database receiver collects data from an Oracle Database instance.

The Oracle Database receiver is a component of the OpenTelemetry Collector. It connects to an Oracle Database instance and supports metrics and logs pipelines.

Oracle Database support starts from these minimum collector versions:

  • Splunk Distribution of the OpenTelemetry Collector (splunk-otel-collector) v0.156.0 or later
  • Community (OSS) version of the OpenTelemetry Collector (opentelemetry-collector-contrib) v0.156.0 or later

Supported versions and platforms

Splunk Database Monitoring supports these Oracle Database versions and platforms:

  • Versions: 19c, 26ai
  • Platforms: AWS RDS, Oracle Real Application Clusters (RAC), or self-hosted
Note: For Oracle RAC deployments, you must set up a connection to each node in the cluster separately.

Prerequisites

Prepare your database:

  • Create a dedicated, non-administrative user:

    CODE 
    CREATE USER otel-user IDENTIFIED BY otel-user-password;

  • Grant the user you created these permissions:

    Self-hosted Oracle Database
    CODE 
    GRANT SELECT ON SYS.V_$SESSION TO otel-user;
GRANT SELECT ON SYS.V_$SYSSTAT TO otel-user;
GRANT SELECT ON SYS.V_$RESOURCE_LIMIT TO otel-user;
GRANT SELECT ON SYS.DBA_TABLESPACES TO otel-user;
GRANT SELECT ON SYS.DBA_DATA_FILES TO otel-user;
GRANT SELECT ON SYS.DBA_TABLESPACE_USAGE_METRICS TO otel-user;
GRANT SELECT ON SYS.V_$SQL TO otel-user;
GRANT SELECT ON SYS.V_$SQL_PLAN_STATISTICS_ALL TO otel-user;
GRANT SELECT ON SYS.DBA_PROCEDURES TO otel-user;
    Note:

    In SQL query plan details, the LAST_*, OUTPUT_ROWS, and STARTS columns are populated only when Oracle Database collects execution plan statistics, for example with STATISTICS_LEVEL=ALL or the GATHER_PLAN_STATISTICS hint. Otherwise, these fields are null or empty. Collecting execution plan statistics can add runtime overhead. Enable this Oracle instrumentation only if you need runtime execution statistics for query performance analysis.

    To collect optional runtime execution statistics for SQL query plan details, set statistics_level to ALL:

    SQL 
    ALTER SYSTEM SET statistics_level = ALL;
    AWS RDS Oracle Database
    CODE 
    EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SESSION', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SYSSTAT', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$RESOURCE_LIMIT', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_TABLESPACES', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_DATA_FILES', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_TABLESPACE_USAGE_METRICS', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQL_PLAN_STATISTICS_ALL', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('V_$SQL', 'otel-user', 'SELECT', p_grant_option => FALSE);
EXEC rdsadmin.rdsadmin_util.grant_sys_object('DBA_PROCEDURES', 'otel-user', 'SELECT', p_grant_option => FALSE);
    Note:

    In SQL query plan details, the LAST_*, OUTPUT_ROWS, and STARTS columns are populated only when Oracle Database collects execution plan statistics, for example with STATISTICS_LEVEL=ALL or the GATHER_PLAN_STATISTICS hint. Otherwise, these fields are null or empty. Collecting execution plan statistics can add runtime overhead. Enable this Oracle instrumentation only if you need runtime execution statistics for query performance analysis.

    To collect optional runtime execution statistics for SQL query plan details, configure the Oracle DB parameter group:

    1. In the AWS console, navigate to Aurora and RDS > Parameter groups > Edit parameter group. Create or select a custom Oracle DB parameter group for your Oracle engine family, and change this value:

      • statistics_level: ALL

    2. Save the parameter group.

    3. Attach the parameter group to the database instance if it isn't already attached.

    4. Restart the database instance.

Configure the receiver

Modify your collector configuration file as follows. All examples are for the Splunk Distribution of the OpenTelemetry Collector.

  1. In the receivers: section, add oracledb:

    YAML 
    oracledb:
  endpoint: host
  service: service
  username: otel-user
  password: otel-user-password
  resource_attributes:
    oracledb.instance.name:
      enabled: true
  events:
    db.server.query_sample:
      enabled: true
    db.server.top_query:
      enabled: true
    Important:

    If you're using the Splunk Distribution of OpenTelemetry Collector, leave the following receiver settings at their default values:

    • collection_interval (Default: 10s)

    • query_sample_collection.max_rows_per_query (Default: 100)

    • top_query_collection.collection_interval (Default: 60s)

    • top_query_collection.max_query_sample_count (Default: 1000)

    These values support Database Monitoring without affecting the performance of the database or the collector. If you increase these values you might adversely affect the performance of your database or collector, and this could result in ingest throttling.

  2. In the exporters: section, add otlp_http/dbmon:

    YAML 
    otlp_http/dbmon:
  headers:
    X-SF-Token: your-splunk-access-token
    X-splunk-instrumentation-library: dbmon
  logs_endpoint: https://ingest.your-splunk-realm.observability.splunkcloud.com/v3/event
  sending_queue:
    batch:
      flush_timeout: 15s
      max_size: 10485760
      sizer: bytes

  3. In the service.pipelines: section, create a metrics pipeline named metrics/dbmon and a logs pipeline named logs/dbmon:

    YAML 
    metrics/dbmon:
  receivers:
    - oracledb
  processors:
    - memory_limiter
    - batch
  exporters:
    - signalfx
logs/dbmon:
  receivers:
    - oracledb
  processors:
    - memory_limiter
    - batch
  exporters:
    - otlp_http/dbmon
    Important: Use an identical list of processors for the metrics and logs/dbmon pipelines, and include these processors in the same order.

  4. Restart the collector to apply your configuration changes.

    The restart command varies depending on what platform you deployed the collector on and what tool you used to deploy it. Here are general examples of the restart command:

    Linux

    Linux with installer script:

    BASH 
    sudo systemctl restart splunk-otel-collector
    Windows

    Windows with installer script:

    BASH 
    stop-service splunk-otel-collector
start-service splunk-otel-collector
    Kubernetes

    Kubernetes with Helm:

    BASH 
    helm upgrade your-splunk-otel-collector splunk-otel-collector-chart/splunk-otel-collector -f your-override-values.yaml

    where splunk-otel-collector-chart is the name you gave to the Helm chart in the helm repo add command.

Your database instance should now be visible on APM > Database monitoring as well as on Infrastructure > Infrastructure monitoring if you have a Database Monitoring license. For troubleshooting, see Troubleshoot data collection .

Advanced configurations

Collect data from multiple Oracle Database instances

Add multiple oracledb receivers with unique names. For example:

YAML 
receivers:
  oracledb/instance_a:
    ...

  oracledb/instance_b:
    ...
Use secure credentials

Use the environment variables built into the collector. Syntax: ${env:VAR_NAME}:

YAML 
oracledb:
  endpoint: host:port
  username: ${env:ORACLE_USER}
  password: ${env:ORACLE_PASSWORD}
  service: ${env:ORACLE_SERVICE}
Enable optional metrics

For example, oracledb.physical_writes. Since oracledb.physical_reads is enabled by default, you might want to enable oracledb.physical_writes to create complete visibility. No special permissions needed; it comes from the same V$SYSSTAT query that already runs for the default metrics, so enabling it adds no overhead or additional grants.

YAML 
oracledb:
  
  oracledb.physical_writes: null
  enabled: true
High availability datasource

To configure the Oracle Database receiver for high availability, use:

YAML 
oracledb:
  datasource: oracle://otel-user:password@host:port/service_name?server=host:port

You must encode special characters. See Oracle Go Driver go_ora documentation for full connection string options.

Set up APM correlation

See Correlate database queries with Splunk APM traces.

Settings reference

Configuration options for this receiver:

included

https://raw.githubusercontent.com/splunk/collector-config-tools/main/cfg-metadata/receiver/oracledb.yaml

Metrics reference

Metrics, attributes, and resource attributes reported by this receiver:

included

https://raw.githubusercontent.com/splunk/collector-config-tools/main/metric-metadata/oracledbreceiver.yaml