Skip to content

Oracle

Infrastructure Integration

Instructions

Follow the installation guide below for your given collector environment.

During installation, use the configuration section below as reference.

After installation, the infrastructure datasources in the table below will be available in the AOC.

Installation Guide

Installing this integration consists of creating a yaml file in the filesystem of your collectors. Click below for instructions on how to do so for your given collectors environment.

Docker

Kubernetes

Mesos-Marathon

Debian

Ubuntu

RHEL/CentOS

Configuration

  1. In order to use the Oracle integration install the Oracle Instant Client libraries. Due to licensing restrictions we are unable to include these libraries in our agent, but you can download them directly from Oracle.

Go to the download page

You will need to download the Instant Client Basic and SDK packages.

After you have installed the Instant Client libraries, on linux you may have to ensure that the runtime linker can find the libraries. For example, using ldconfig:

    mkdir -p /opt/oracle/ && cd /opt/oracle/

    # Download Oracle Instant Client (example dir: /opt/oracle).

    unzip /opt/oracle/instantclient-basic-linux.x64-12.1.0.2.0.zip
    unzip /opt/oracle/instantclient-sdk-linux.x64-12.1.0.2.0.zip
    # Put the library location in an ld configuration file.
    sudo sh -c "echo /opt/oracle/instantclient_12_2 > /etc/ld.so.conf.d/oracle-instantclient.conf"

    # Update the bindings.

    sudo ldconfig

Alternately, update your LD_LIBRARY_PATH to include the location of the Instant Client libraries. For example:

    export LD_LIBRARY_PATH=/opt/oracle/instantclient_12_2:$LD_LIBRARY_PATH
  1. Finally, create a read-only epoch user with proper access to your Oracle Database Server. Connect to your Oracle database with an administrative user (e.g. SYSDBA or SYSOPER) and run:
    -- Enable Oracle Script.
    ALTER SESSION SET "_ORACLE_SCRIPT"=true;
    
    -- Create the epoch user. Replace the password placeholder with a secure password.
    CREATE USER epoch IDENTIFIED BY <password>;
    
    -- Grant access to the epoch user.
    GRANT CONNECT TO epoch;
    GRANT SELECT ON GV_$PROCESS TO epoch;
    GRANT SELECT ON gv_$sysmetric TO epoch;
    GRANT SELECT ON sys.dba_data_files TO epoch;
    

Note: If you’re using Oracle 11g, there’s no need to run the following line:

    ALTER SESSION SET "_ORACLE_SCRIPT"=true;
  1. Configure the agent by editing /etc/nutanix/epoch-dd-agent/conf.d/oracle.yaml in the collectors.

Configuration Options:

- `server` (Required) - The IP address or hostname of the Oracle Database server.
- `service_name` (Required) - The Oracle Database service name. To view the services available on your server, run the following  query: - ```SELECT value FROM v$parameter WHERE name='service_names'```.
- `user` (Required) - If you followed the instructions above, set this to the read-only user epoch. Otherwise set it to a user with sufficient privileges to connect to the database and read system metrics.
- `password` (Required) - The password for the user account.
- `tags` (Optional) - A list of tags applied to all metrics collected. Tags may be simple strings or key-value pairs.

Example:

    init_config:

    instances:
    # The Oracle check requires access to the `cx_Oracle` Python
    # module. Due to restrictions on installation, this requires
    # the following steps in order to be included with the agent
    #
    # 1. Download the relevant Oracle Instant Client:
    #    http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html
    #    Both the basic client and the client sdk will be required
    #    Example dir: ~/oracle
    # 2. Decompress this library in a given directory available to
    #    all users on the given machine (i.e. /opt/oracle)
    #       mkdir -p /opt/oracle/ && cd /opt/oracle/
    #       unzip ~/oracle/instantclient-basic-linux.x64-12.1.0.2.0.zip
    #       unzip ~/oracle/instantclient-sdk-linux.x64-12.1.0.2.0.zip
    # 3. Set required env variables for cx_Oracle installation
    #       export LD_RUN_PATH=/opt/oracle/instantclient_12_1
    #       export ORACLE_HOME=/opt/oracle/instantclient_12_1
    # 4. Install instant client in agent's virtual environment
    #       /opt/datadog-agent/embedded/bin/pip install cx_Oracle
    # 5. Following cx_Oracle installation, ensure LD_LIBRARY_PATH points
    #    to this directory when starting/restarting the agent
    #       export LD_LIBRARY_PATH=/opt/oracle/instantclient_12_1
    #
    # NOTE: connection string used will have the format:
    #        user/password@//server/service_name
    #
    # - server: 127.0.0.1
    #   service_name: my_sid
    #   user: my_username
    #   password: my_password
    #
    - server: localhost:1521
      service_name: my_sid
      user: my_username
      password: my_password
      tags:
        - my_tag
  1. Check and make sure that all yaml files are valid with following command:

    /etc/init.d/epoch-collectors configcheck

  2. Restart the Agent using the following command:

    /etc/init.d/epoch-collectors restart

  3. Execute the info command to verify that the integration check has passed:

    /etc/init.d/epoch-collectors info

The output of the command should contain a section similar to the following:

   Checks
   ======
    [...]

     oracle
     ---------
        - instance #0 [OK]
        - - Collected 23 metrics, 0 events & 1 service check

Infrastructure Datasources

Datasource Available Aggregations Unit Description
oracle.buffer_cachehit_ratio avg max min sum Ratio of buffer cache hits
oracle.cursor_cachehit_ratio avg max min sum Ratio of cursor cache hits
oracle.library_cachehit_ratio avg max min sum Ratio of library cache hits
oracle.shared_pool_free avg max min sum percent shared pool free memory %
oracle.physical_reads avg max min sum physical reads per sec
oracle.physical_writes avg max min sum physical writes per sec
oracle.enqueue_timeouts avg max min sum enqueue timeouts per sec
oracle.gc_cr_block_received avg max min sum GC CR block received
oracle.cache_blocks_corrupt avg max min sum corrupt cache blocks
oracle.cache_blocks_lost avg max min sum lost cache blocks
oracle.logons avg max min sum number of logon attempts
oracle.active_sessions avg max min sum number of active sessions
oracle.long_table_scans avg max min sum number of long table scans per sec
oracle.service_response_time avg max min sum second service response time
oracle.user_rollbacks avg max min sum number of user rollbacks
oracle.sorts_per_user_call avg max min sum sorts per user call
oracle.rows_per_sort avg max min sum rows per sort
oracle.disk_sorts avg max min sum disk sorts per second
oracle.memory_sorts_ratio avg max min sum memory sorts ratio
oracle.database_wait_time_ratio avg max min sum memory sorts per second
oracle.session_limit_usage avg max min sum percent session limit usage
oracle.session_count avg max min sum session count
oracle.process.pga_used_memory avg max min sum byte PGA memory used by process
oracle.process.pga_allocated_memory avg max min sum byte PGA memory allocated by process
oracle.process.pga_freeable_memory avg max min sum byte PGA memory freeable by process
oracle.process.pga_maximum_memory avg max min sum byte PGA maximum memory ever allocated by process
oracle.temp_space_used avg max min sum byte temp space used
oracle.tablespace.used avg max min sum byte tablespace used
oracle.tablespace.size avg max min sum byte tablespace size
oracle.tablespace.in_use avg max min sum tablespace in-use
oracle.tablespace.offline avg max min sum tablespace offline