# Oracle DB receiver

<!-- status autogenerated section -->
| Status        |           |
| ------------- |-----------|
| Stability     | [alpha]: metrics   |
| Distributions | [contrib], [splunk] |
| Issues        | [![Open issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aopen%20label%3Areceiver%2Foracledb%20&label=open&color=orange&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aopen+is%3Aissue+label%3Areceiver%2Foracledb) [![Closed issues](https://img.shields.io/github/issues-search/open-telemetry/opentelemetry-collector-contrib?query=is%3Aissue%20is%3Aclosed%20label%3Areceiver%2Foracledb%20&label=closed&color=blue&logo=opentelemetry)](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues?q=is%3Aclosed+is%3Aissue+label%3Areceiver%2Foracledb) |
| [Code Owners](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/CONTRIBUTING.md#becoming-a-code-owner)    | [@dmitryax](https://www.github.com/dmitryax), [@crobert-1](https://www.github.com/crobert-1), [@atoulme](https://www.github.com/atoulme) |

[alpha]: https://github.com/open-telemetry/opentelemetry-collector#alpha
[contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib
[splunk]: https://github.com/signalfx/splunk-otel-collector
<!-- end autogenerated section -->

This receiver collects metrics from an Oracle Database.

The receiver connects to a database host and performs periodically queries.

## Getting Started

To use the OracleDB receiver you must define how to connect to your DB. This can be done in two ways,
defined in the [Primary](#primary-configuration-option) and [Secondary](#secondary-configuration-option) configuration
option sections. Defining one of the two configurations is required. If both are defined, the primary
option will be used.

### Primary Configuration Option

Required options:
- `datasource`: Oracle database connection string. Special characters must be encoded. Refer to Oracle Go Driver go_ora documentation for full connection string options.

Example:

```yaml
receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"
```

### Secondary Configuration Option

Required options:
- `endpoint`: Endpoint used to connect to the OracleDB server. Must be in the format of `host:port`
- `password`: Password for the OracleDB connection. Special characters are allowed.
- `service`: OracleDB Service that the receiver should connect to.
- `username`: Username for the OracleDB connection.

Example:
```yaml
receivers:
  oracledb:
    endpoint: localhost:51521
    password: p@sswo%d
    service: XE
    username: otel
```

## Permissions

Depending on which metrics you collect, you will need to assign those permissions to the database user:
```
GRANT SELECT ON V_$SESSION TO <username>;
GRANT SELECT ON V_$SYSSTAT TO <username>;
GRANT SELECT ON V_$RESOURCE_LIMIT TO <username>;
GRANT SELECT ON DBA_TABLESPACES TO <username>;
GRANT SELECT ON DBA_DATA_FILES TO <username>;
```

## Enabling metrics.

See [documentation](./documentation.md).

You can enable or disable selective metrics.

Example:

```yaml
receivers:
  oracledb:
    datasource: "oracle://otel:password@localhost:51521/XE"
    metrics:
      oracledb.query.cpu_time:
        enabled: false
      oracledb.query.physical_read_requests:
        enabled: true
```