Oracle

Linux

1. Follow the Oracle Instant Client installation for Linux.

2. Verify the following:

   • Both the Instant Client Basic and SDK packages are installed. Find them on Oracle’s download page.

     After the Instant Client libraries are installed, ensure the runtime linker can find the libraries. For example, using ldconfig:

     # Put the library location in an ld configuration file.
     
     sudo sh -c "echo /usr/lib/oracle/12.2/client64/lib > \
         /etc/ld.so.conf.d/oracle-instantclient.conf"
     
     # Update the bindings.
     
     sudo ldconfig
     

   • Both packages are decompressed into a single directory that is available to all users on the given machine (for example, /opt/oracle):

     mkdir -p /opt/oracle/ && cd /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
     

Windows

1. Follow the Oracle Windows installation guide to configure your Oracle Instant Client.

2. Verify the following:

   • The Microsoft Visual Studio 2017 Redistributable or the appropriate version is installed for the Oracle Instant Client.

   • Both the Instant Client Basic and SDK packages from Oracle’s download page are installed.

   • Both packages are extracted into a single directory that is available to all users on the given machine (for example, C:\oracle).

Create a read-only datadog user with proper access to your Oracle Database Server. Connect to your Oracle database with an administrative user, such as SYSDBA or SYSOPER, and run:

-- Enable Oracle Script.
ALTER SESSION SET "_ORACLE_SCRIPT"=true;

-- Create the datadog user. Replace the password placeholder with a secure password.
CREATE USER datadog IDENTIFIED BY <PASSWORD>;

-- Grant access to the datadog user.
GRANT CONNECT TO datadog;
GRANT SELECT ON GV_$PROCESS TO datadog;
GRANT SELECT ON gv_$sysmetric TO datadog;
GRANT SELECT ON sys.dba_data_files TO datadog;
GRANT SELECT ON sys.dba_tablespaces TO datadog;
GRANT SELECT ON sys.dba_tablespace_usage_metrics TO datadog;

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

ALTER SESSION SET "_ORACLE_SCRIPT"=true;

Oracle 12c or 19c

Log in to the root database as an Administrator to create a datadog user and grant permissions:

alter session set container = cdb$root;
CREATE USER c##datadog IDENTIFIED BY password CONTAINER=ALL;
GRANT CREATE SESSION TO c##datadog CONTAINER=ALL;
Grant select any dictionary to c##datadog container=all;
GRANT SELECT ON GV_$PROCESS TO c##datadog CONTAINER=ALL;
GRANT SELECT ON gv_$sysmetric TO c##datadog CONTAINER=ALL;

Host

To configure this check for an Agent running on a host:

1. Edit the oracle.d/conf.yaml file, in the conf.d/ folder at the root of your Agent’s configuration directory. Update the server and port to set the masters to monitor. See the sample oracle.d/conf.yaml for all available configuration options.

   init_config:
   
   instances:
      ## @param server - string - required
      ## The IP address or hostname of the Oracle Database Server.
      #
      - server: localhost:1521
   
        ## @param service_name - string - 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'`
        #
        service_name: <SERVICE_NAME>
   
        ## @param username - string - required
        ## The username for the Datadog user account.
        #
        username: <USERNAME>
   
        ## @param password - string - required
        ## The password for the Datadog user account.
        #
        password: <PASSWORD>
   

2. Restart the Agent.

Only custom queries

To skip default metric checks for an instance and only run custom queries with an existing metrics gathering user, insert the tag only_custom_queries with a value of true. This allows a configured instance of the Oracle integration to skip the system, process, and tablespace metrics from running, and allows custom queries to be run without having the permissions described in the Datadog user creation section. If this configuration entry is omitted, the user you specify is required to have those table permissions to run a custom query.

init_config:

instances:
  ## @param server - string - required
  ## The IP address or hostname of the Oracle Database Server.
  #
  - server: localhost:1521

    ## @param service_name - string - 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'`
    #
    service_name: "<SERVICE_NAME>"

    ## @param user - string - required
    ## The username for the user account.
    #
    user: <USER>

    ## @param password - string - required
    ## The password for the user account.
    #
    password: "<PASSWORD>"

    ## @param only_custom_queries - string - optional
    ## Set this parameter to any value if you want to only run custom
    ## queries for this instance.
    #
    only_custom_queries: true

Connect to Oracle through TCPS

1. To connect to Oracle through TCPS (TCP with SSL), uncomment the protocol configuration option and select TCPS. Update the server option to set the TCPS server to monitor.

   init_config:
   
   instances:
     ## @param server - string - required
     ## The IP address or hostname of the Oracle Database Server.
     #
     - server: localhost:1522
   
       ## @param service_name - string - 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'`
       #
       service_name: "<SERVICE_NAME>"
   
       ## @param user - string - required
       ## The username for the user account.
       #
       user: <USER>
   
       ## @param password - string - required
       ## The password for the user account.
       #
       password: "<PASSWORD>"
   
       ## @param protocol - string - optional - default: TCP
       ## The protocol to connect to the Oracle Database Server. Valid protocols include TCP and TCPS.
       ##
       ## When connecting to Oracle Database via JDBC, `jdbc_truststore` and `jdbc_truststore_type` are required.
       ## More information can be found from Oracle Database's whitepaper:
       ##
       ## https://www.oracle.com/technetwork/topics/wp-oracle-jdbc-thin-ssl-130128.pdf
       #
       protocol: TCPS
   

2. Update the sqlnet.ora, listener.ora, and tnsnames.ora to allow TCPS connections on your Oracle Database.

TCPS through Oracle without JDBC

If you are not using JDBC, verify that the Datadog Agent is able to connect to your database. Use the sqlplus command line tool with the information inputted in your configuration options:

sqlplus <USER>/<PASSWORD>@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<HOST>)(PORT=<PORT>))(SERVICE_NAME=<SERVICE_NAME>)))

When using the Oracle Instant Client connection, move three files to the network/admin directory of the client libraries used by your application:

• tnsnames.ora: Maps net service names used for application connection strings to your database services.
• sqlnet.ora: Configures Oracle Network settings.
• cwallet.sso: Enables SSL or TLS connections. Keep this file secure.

TCPS through JDBC

If you are connecting to Oracle Database using JDBC, you also need to specify jdbc_truststore_path, jdbc_truststore_type, and jdbc_truststore_password (optional) if there is a password on the truststore.

Note: SSO truststores don’t require passwords.

    # In the `instances:` section
    ...

    ## @param jdbc_truststore_path - string - optional
    ## The JDBC truststore file path.
    #
    jdbc_truststore_path: /path/to/truststore

    ## @param jdbc_truststore_type - string - optional
    ## The JDBC truststore file type. Supported truststore types include JKS, SSO, and PKCS12.
    #
    jdbc_truststore_type: SSO

    ## @param jdbc_truststore_password - string - optional
    ## The password for the truststore when connecting via JDBC.
    #
    # jdbc_truststore_password: <JDBC_TRUSTSTORE_PASSWORD>

For more information about connecting to the Oracle Database through TCPS on JDBC, see the official Oracle whitepaper.

Containerized

For containerized environments, see the Autodiscovery Integration Templates for guidance on applying the parameters below.