Skip to content

update documentation according to internal requirements #33

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 25, 2023
Merged

update documentation according to internal requirements #33

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fc374af
Update README.md
spavlusieva Oct 25, 2023
18a3367
Add files via upload
spavlusieva Oct 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 48 additions & 33 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ Contributions are welcome - please see [contributing](CONTRIBUTING.md).
- [Developer notes](#developer-notes)


# Roadmap
## Roadmap

## Version 1.0
### Version 1.0

The first production release, v1.0, includes the following features:

Expand All @@ -41,7 +41,7 @@ Note that this exporter uses a different Oracle Database driver which in turn us

The interfaces for this version have been kept as close as possible to those of earlier alpha releases in this repository to assist with migration. However, it should be expected that there may be breaking changes in future releases.

## Plans
### Plans

We always welcome input on features you would like to see supported. Please open an issue in this repository with your suggestions.

Expand All @@ -59,7 +59,7 @@ Currently, we plan to address the following key features:
- Provide additional documentation and samples, and
- Integrate with the Oracle Database Operator for Kubernetes.

# Standard metrics
## Standard metrics

The following metrics are exposed currently.

Expand Down Expand Up @@ -89,7 +89,7 @@ The following metrics are exposed currently.
- oracledb_resource_current_utilization
- oracledb_resource_limit_value

# Database permissions required
## Database permissions required

For the built-in default metrics, the database user that the exporter uses to connect to the Oracle Database instance must have the `SELECT_CATALOG_ROLE` privilege and/or `SELECT` permission on the following tables.

Expand All @@ -104,7 +104,7 @@ For the built-in default metrics, the database user that the exporter uses to co
- v$session
- v$resource_limit

# Installation
## Installation

There are a number of ways to run the exporter. In this section you will find information on running the exporter:

Expand All @@ -113,11 +113,11 @@ There are a number of ways to run the exporter. In this section you will find i
- In [Kubernetes](#kubernetes)
- As a [standalone binary](#standalone-binary)

## Docker, Podman, etc.
### Docker, Podman, etc.

You can run the exporter in a local container using a conatiner image from [Oracle Container Registry](https://container-registry.oracle.com). The container image is available in the "observability-exporter" repository in the "Database" category. No authentication or license presentment/acceptance are required to pull this image from the registry.

### Oracle Database
#### Oracle Database

If you need an Oracle Database to test the exporter, you can use this command to start up an instance of [Oracle Database 23c Free](https://www.oracle.com/database/free/) which also requires no authentication or license presentment/acceptance to pull the image.

Expand Down Expand Up @@ -152,11 +152,11 @@ docker inspect free23c | grep IPA
"IPAddress": "172.17.0.2",
```

### Exporter
#### Exporter

You need to give the exporter the connection details for the Oracle Database that you want it to run against. You can use a simple connection, or a wallet.

#### Simple connection
##### Simple connection

For a simple connection, you will provide the details using these variables:

Expand All @@ -175,7 +175,7 @@ docker run -it --rm \
container-registry.oracle.com/database/observability-exporter:1.0.0
```

#### Using a wallet
##### Using a wallet

For a wallet connection, you must first set up the wallet. If you are using Oracle Autonomous Database, for example, you can download the wallet from the Oracle Cloud Infrastructure (OCI) console.

Expand All @@ -202,7 +202,7 @@ docker run -it --rm \
```


## Test/demo environment with Docker Compose
### Test/demo environment with Docker Compose

If you would like to set up a test environment with the exporter, you can use the provided "Docker Compose" file in this repository which will start an Oracle Database instance, the exporter, Prometheus and Grafana.

Expand All @@ -219,11 +219,11 @@ Once the containers are all running, you can access the services using these URL
- [Prometheus](http://localhost:9000) - try a query for "oracle".
- [Grafana](http://localhost:3000) - username is "admin" and password is "grafana". An Oracle Database dashboard is provisioned and configured to use data from the exporter.

## Kubernetes
### Kubernetes

To run the exporter in Kubernetes, you need to complete the following steps. All steps must be completed in the same Kunernetes namespace. The examples below assume you want to use a namespace called `exporter`, you must change the commands if you wish to use a different namespace.

### Create a secret with credentials for connecting to the Oracle Database
#### Create a secret with credentials for connecting to the Oracle Database

Create a secret with the Oracle database user and password that the exporter should use to connect to the database using this command. You must specify the correct user and password for your environment. This example uses `pdbadmin` as the user and `Welcome12345` as the password:

Expand All @@ -234,7 +234,7 @@ kubectl create secret generic db-secret \
-n exporter
```

### Create a config map for the wallet (optional)
#### Create a config map for the wallet (optional)

Create a config map with the wallet (if you are using one) using this command. Run this command in the `wallet` directory you created earlier.

Expand All @@ -251,7 +251,7 @@ kubectl create cm db-metrics-tns-admin \
-n exporter
```

### Create a config map for you metrics definition file (optional)
#### Create a config map for you metrics definition file (optional)

If you have defined any [custom metrics](#custom-metrics), you must create a config map for the metrics definition file. For example, if you created a configuration file called `txeventq-metrics.toml`, then create the config map with this command:

Expand All @@ -261,7 +261,7 @@ kubectl create cm db-metrics-txeventq-exporter-config \
-n exporter
```

### Deploy the Oracle Database Observability exporter
#### Deploy the Oracle Database Observability exporter

A sample Kubernetes manifest is provided [here](/kubernetes/metrics-exporter-deployment.yaml). You must edit this file to set the namespace you wish to use, the database connect string to use, and if you have any custom metrics, you will need to uncomment and customize some sections in this file.

Expand All @@ -283,7 +283,7 @@ You can view the exporter's logs with this command:
kubectl logs -f svc/metrics-exporter -n exporter
```

### Create a Kubernetes service for the exporter
#### Create a Kubernetes service for the exporter

Create a Kubernetes service to allow access to the exporter pod(s). A sample Kubernetes manifest is provided [here](/kubernetes/metrics-exporter-service.yaml). You may need to customize this file to update the namespace.

Expand All @@ -293,7 +293,7 @@ Once you have made any necessary udpates, apply the file to your cluster using t
kubectl aspply -f metrics-exporter-service.yaml
```

### Create a Kubernetes service monitor
#### Create a Kubernetes service monitor

Create a Kubernetes service monitor to tell Prometheus (for example) to collect metrics from the exporter. A sample Kubernetes manifest is provided [here](/kubernetes/metrics-service-monitor.yaml). You may need to customize this file to update the namespace.

Expand All @@ -303,7 +303,7 @@ Once you have made any necessary udpates, apply the file to your cluster using t
kubectl aspply -f metrics-service-monitor.yaml
```

### Configure a Prometheus target (optional)
#### Configure a Prometheus target (optional)

You may need to update your Prometheus configuration to add a target. If so, you can use this example job definition as a guide:

Expand All @@ -317,12 +317,12 @@ You may need to update your Prometheus configuration to add a target. If so, yo
- metrics-exporter.exporter.svc.cluster.local:9161
```

### Import Grafana dashboard definition(s) (optional)
#### Import Grafana dashboard definition(s) (optional)

See [Grafana dashboards](#grafana-dashboards) below.


## Standalone binary
### Standalone binary

Pre-compiled versions for Linux 64 bit can be found under [releases](https://github.com/oracle/oracle-db-appdev-monitoring/releases).

Expand Down Expand Up @@ -355,7 +355,7 @@ Usage of oracledb_exporter:
Path to configuration file that can enable TLS or authentication.
```

# Custom metrics
## Custom metrics

The exporter allows definition of arbitrary custom metrics in a TOML file. To specify this file to the
exporter, you can:
Expand Down Expand Up @@ -448,7 +448,7 @@ oracledb_test_value_2 2
You can find [working examples](./custom-metrics-example/custom-metrics.toml) of custom metrics for slow queries, big queries and top 100 tables.
An exmaple of [custom metrics for Transacational Event Queues](./custom-metrics-example/txeventq-metrics.toml) is also provided.

## Customize metrics in a container image
### Customize metrics in a container image

If you run the exporter as a container image and want to include your custom metrics in the image itself, you can use the following example `Dockerfile` to create a new image:

Expand All @@ -458,7 +458,7 @@ COPY custom-metrics.toml /
ENTRYPOINT ["/oracledb_exporter", "--custom.metrics", "/custom-metrics.toml"]
```

# Grafana dashboards
## Grafana dashboards

A sample Grafana dashboard definition is provided [in this directory](/docker-compose/grafana/dashboards). You can import this into your Grafana instance, and set it to use the Prometheus datasource that you have defined for the Prometheus instance that is collecting metrics from the exporter.

Expand All @@ -467,7 +467,7 @@ The dashboard shows some basic information, as shown below:
![](doc/oracledb-dashboard.png)


# Monitoring Transactional Event Queues
## Monitoring Transactional Event Queues

[Oracle Transactional Event Queues](https://docs.oracle.com/en/database/oracle/oracle-database/21/adque/index.html) ("TxEventQ") is a fault-tolerant, scalable, real-time messaging backbone offered by converged Oracle Database that allows you to build an enterprise-class event-driven architectures.

Expand All @@ -477,7 +477,7 @@ The exporter includes a set of metrics for monitoring TxEventQ and a pre-built G

> Note: The metrics are written for Oracle Database 21c or later.

## How to create a topic
### How to create a topic

If you need to create a topic to monitor, you can use these statements to create and start a topic, and create a subscriber:

Expand Down Expand Up @@ -538,11 +538,11 @@ begin
end;
```

## Metrics definitions
### Metrics definitions

The metrics definitions are provided in [this file](./custom-metrics-example/txeventq-metrics.toml). You need to provide this file to the exporter, e.g., by adding it to your container image, or creating a Kubernetes config map containing the file and mounting that config map as a volume in your deployment. You also need to set the `CUSTOM_METRICS` environment variable to the location of this file.

## Additional database permissions
### Additional database permissions

The database user that the exporter uses to connect to the database will also need additional permissions, which can be granted with these statements. This example assumes the exporter connects with the username "exporter":

Expand All @@ -558,7 +558,7 @@ grant select on sys.aq$_queue_shards to exporter;
grant select on user_queue_partition_assignment_table to exporter;
```

## Grafana dashboard
### Grafana dashboard

A Grafana dashboard for Transactional Event Queues is provided [in this file](./docker-compose/grafana/dashboards/txeventq.json). This can be imported into your Grafana environment. Choose the Prometheus datasource that is collecting metrics from the exporter.

Expand All @@ -568,7 +568,7 @@ The dashboard will look like this:

![](./doc/txeventq-dashboard.png)

# Developer notes
## Developer notes

The exporter itself is fairly simple. The initialization is done as follows:

Expand All @@ -590,7 +590,7 @@ For each element (of `Metric` type), a call to the `ScrapeMetric` function will
The `ScrapeGenericValues` function will read the information from the `Metric` structure and, depending on the parameters, will generate the metrics to return. In particular, it will use the `GeneratePrometheusMetrics` function which will make SQL calls to the database.


## Docker/container build
### Docker/container build

To build a container image, run the following command:

Expand All @@ -599,7 +599,7 @@ make docker
```


## Building Binaries
### Building Binaries

Run build:

Expand All @@ -609,3 +609,18 @@ make go-build

This will create binaries and archives inside the `dist` folder for the building operating system.

## Contributing

This project welcomes contributions from the community. Before submitting a pull request, please [review our contribution guide](./CONTRIBUTING.md)

## Security

Please consult the [security guide](./SECURITY.md) for our responsible security vulnerability disclosure process

## License

Copyright (c) 2016, 2023 Oracle and/or its affiliates.

Released under the Universal Permissive License v1.0 as shown at
<https://oss.oracle.com/licenses/upl/>
and the MIT License (MIT)
34 changes: 19 additions & 15 deletions SECURITY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,32 +1,36 @@
# Reporting Security Vulnerabilities
# Reporting security vulnerabilities

Oracle values the independent security research community, and believes that
responsible disclosure of security vulnerabilities helps us to ensure the security
and privacy of all of our users.
Oracle values the independent security research community and believes that
responsible disclosure of security vulnerabilities helps us ensure the security
and privacy of all our users.

Please do NOT raise a GitHub Issue to report a security vulnerability. If you
believe you have found a security vulnerability, then please submit a report to
believe you have found a security vulnerability, please submit a report to
[[email protected]][1] preferably with a proof of concept. Please review
some additional information on [how to report security vulnerabilities to Oracle][2].
Oracle encourages anyone who contacts Oracle Security to use email encryption, using
We encourage people who contact Oracle Security to use email encryption using
[our encryption key][3].

Please do not use other channels, or contact the project maintainers
We ask that you do not use other channels or contact the project maintainers
directly.

For non-vulnerability related security issues, including ideas for new or improved
security features, you are welcome to post these as GitHub Issues.
Non-vulnerability related security issues including ideas for new or improved
security features are welcome on GitHub Issues.

## Security Updates, Alerts and Bulletins
## Security updates, alerts and bulletins

Oracle issues security updates on a regular cadence. Many of our projects typically include release security fixes in conjunction with the [Oracle Critical Patch Update][3] program. Security updates are released on the
Tuesday closest to the 17th day of January, April, July and October. A pre-release announcement will be published on the Thursday preceding each release. Additional information, including past advisories, is available on our [security alerts][4]
Security updates will be released on a regular cadence. Many of our projects
will typically release security fixes in conjunction with the
Oracle Critical Patch Update program. Additional
information, including past advisories, is available on our [security alerts][4]
page.

## Security-Related Information
## Security-related information

Oracle will provide security-related information in our documentation. The information can be a threat model, best practices for secure use, or any known security issues. Please note
that labs and example code are intended to demonstrate a concept. These examples should not be used for production use without ensuring that the code is hardened, and in compliance with common security practices.
We will provide security related information such as a threat model, considerations
for secure use, or any known security issues in our documentation. Please note
that labs and sample code are intended to demonstrate a concept and may not be
sufficiently hardened for production use.

[1]: mailto:[email protected]
[2]: https://www.oracle.com/corporate/security-practices/assurance/vulnerability/reporting.html
Expand Down