Skip to content

Commit

Permalink
Add Oracle LD_LIBRARY_PATH example (#2653)
Browse files Browse the repository at this point in the history 
* Add LD_LIBRARY_PATH example

* update wording / formatting
  • Loading branch information
@ruthnaebeck
ruthnaebeck authored and Gus committed Nov 28, 2018
1 parent 8e3a8aa commit d7708fb
Showing 1 changed file with 49 additions and 18 deletions.
67 changes: 49 additions & 18 deletions oracle/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,20 +10,18 @@ Get metrics from Oracle Database servers in real time to visualize and monitor a

### Installation

In order to use the Oracle integration, either install the Oracle Instant Client libraries, or download the Oracle JDBC Driver. Due to licensing restrictions we are unable to include these libraries in our agent, but you can download them directly from Oracle.
To use the Oracle integration, either install the Oracle Instant Client libraries, or download the Oracle JDBC Driver. Due to licensing restrictions, these libraries are not included in the Datadog Agent, but can be downloaded directly from Oracle.

#### Steps for the JDBC Driver

- [Download][1] the jar file
- Add the path to the downloaded file in your $CLASSPATH, or add it to the check configuration file under `jdbc_driver_path`, as in the [sample oracle.yaml][2].
- [Download][1] the jar file.
- Add the path to the downloaded file in your `$CLASSPATH` or the check configuration file under `jdbc_driver_path` (see the [sample oracle.yaml][2]).

#### Steps for the Instant Client

Go to the [download page][3]
Go to the [download page][3] and install the Instant Client Basic and SDK packages.

You will need to install 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`:
If you are using Linux, 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.
Expand All @@ -49,18 +47,48 @@ unzip /opt/oracle/instantclient-sdk-linux.x64-12.1.0.2.0.zip
export LD_LIBRARY_PATH=/opt/oracle/instantclient/lib:$LD_LIBRARY_PATH
```

**Note:** Agent 6 uses upstart or systemd to orchestrate the datadog-agent service. Environment variables may need to be added to the service configuration files at the default locations of `/etc/init/datadog-agent.conf` (Upstart) or `/lib/systemd/system/datadog-agent.service` (systemd). See documentation on [Upstart][4] or [systemd][5] for more information on how to configure these settings.
**Note:** Agent 6 uses Upstart or systemd to orchestrate the `datadog-agent` service. Environment variables may need to be added to the service configuration files at the default locations of `/etc/init/datadog-agent.conf` (Upstart) or `/lib/systemd/system/datadog-agent.service` (systemd). See documentation on [Upstart][4] or [systemd][5] for more information on how to configure these settings.

The following is an example of adding `LD_LIBRARY_PATH` to the Datadog Agent service configuration files (`/int/init/datadog-agent.conf`) on a system using Upstart.

```
description "Datadog Agent"
start on started networking
stop on runlevel [!2345]
respawn
respawn limit 10 5
normal exit 0
# Logging to console from the Agent is disabled since the Agent already logs using file or
# syslog depending on its configuration. We make Upstart log what the process still outputs in order
# to log panics/crashes to /var/log/upstart/datadog-agent.log
console log
env DD_LOG_TO_CONSOLE=false
env LD_LIBRARY_PATH=/usr/lib/oracle/11.2/client64/lib/
setuid dd-agent
script
exec /opt/datadog-agent/bin/agent/agent start -p /opt/datadog-agent/run/agent.pid
end script
post-stop script
rm -f /opt/datadog-agent/run/agent.pid
end script
```

#### After installing either the JDBC Driver or the Instant Client

Finally, create a read-only datadog 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:
Create a read-only `datadog` 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 datadog user. Replace the password placeholder with a secure password.
CREATE USER datadog IDENTIFIED BY <password>;
CREATE USER datadog IDENTIFIED BY <PASSWORD>;
-- Grant access to the datadog user.
GRANT CONNECT TO datadog;
Expand All @@ -81,15 +109,17 @@ Edit the `oracle.d/conf.yaml` file, in the `conf.d/` folder at the root of your

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](#installation), set this to the read-only user `datadog`. 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.
| Option | Required | Description |
|----------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `server` | Yes | The IP address or hostname of the Oracle Database Server. |
| `service_name` | Yes | 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` | Yes | If you followed [the instructions above](#after-installing-either-the-jdbc-driver-or-the-instant-client), set this to the read-only user `datadog`. Otherwise set it to a user with sufficient privileges to connect to the database and read system metrics. |
| `password` | Yes | The password for the user account. |
| `tags` | No | A list of tags applied to all metrics collected. Tags may be simple strings or key-value pairs. |

### Validation

[Run the Agent's `status` subcommand][6] and look for `oracle` under the Checks section.
[Run the Agent's status subcommand][6] and look for `oracle` under the Checks section.

## Data Collected

Expand All @@ -100,10 +130,11 @@ See [metadata.csv][7] for a list of metrics provided by this integration.
The Oracle Database check does not include any events at this time.

### Service Checks
The Oracle Database integration includes the service check `oracle.can_connect` which will verify the database is available and accepting connections.
**oracle.can_connect**
Verifies the database is available and accepting connections.

## Troubleshooting
Need help? Contact [Datadog Support][8].
Need help? Contact [Datadog support][8].

[1]: https://www.oracle.com/technetwork/database/application-development/jdbc/downloads/index.html
[2]: https://github.com/DataDog/integrations-core/blob/master/oracle/datadog_checks/oracle/data/conf.yaml.example
Expand Down

0 comments on commit d7708fb

Please sign in to comment.