Metadata-Version: 2.1
Name: pwr
Version: 1.1.0
Summary: EDB Postgres Workload Report
Home-page: https://www.enterprisedb.com/docs/pwr/latest/
License: Proprietary
Keywords: pwr,edb,postgres,workload,report,awr
Author: EnterpriseDB
Author-email: info@enterprisedb.com
Requires-Python: >=3.9,<4.0
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Requires-Dist: Brotli (==1.1.0)
Requires-Dist: Jinja2 (==3.1.4)
Requires-Dist: MarkupSafe (==2.1.4)
Requires-Dist: PyYAML (==6.0.1)
Requires-Dist: beautifulsoup4 (==4.12.3)
Requires-Dist: bs4 (==0.0.2)
Requires-Dist: cairocffi (>=1.6.1,<2.0.0)
Requires-Dist: cffi (==1.16.0)
Requires-Dist: cssselect2 (==0.7.0)
Requires-Dist: fonttools (==4.47.2)
Requires-Dist: html5lib (==1.1)
Requires-Dist: lxml (==5.1.0)
Requires-Dist: numpy (==1.26.3)
Requires-Dist: pandas (==2.2.0)
Requires-Dist: pillow (==10.3.0)
Requires-Dist: pyarrow (==15.0.0)
Requires-Dist: pycparser (==2.21)
Requires-Dist: pydyf (==0.8.0)
Requires-Dist: pyphen (==0.14.0)
Requires-Dist: python-dateutil (==2.8.2)
Requires-Dist: python-docx (==1.1.0)
Requires-Dist: pytz (==2023.3.post1)
Requires-Dist: six (==1.16.0)
Requires-Dist: soupsieve (==2.5)
Requires-Dist: tinycss2 (==1.2.1)
Requires-Dist: typing_extensions (==4.9.0)
Requires-Dist: tzdata (==2023.4)
Requires-Dist: weasyprint (==52.5)
Requires-Dist: webencodings (==0.5.1)
Requires-Dist: zopfli (==0.2.3)
Project-URL: Documentation, https://www.enterprisedb.com/docs/pwr/latest/
Project-URL: Repository, https://github.com/EnterpriseDB/PWR
Description-Content-Type: text/markdown

# PWR

Postgres Workload Report is a Python-based tool used for building PostgreSQL
workload reports in HTML, Markdown, DOCX, and PDF mode, mimicking the reports
provided by the AWR reporting tool from Oracle.

PWR can be executed from any machine with access, via a Postgres connection,
to the server the user wants a report of. It will leverage the use of
Lasso for collecting the data, so Lasso is a package pre-requisite (there's
an explicit dependency in the `edb-pwr` package for `edb-lasso` to be
installed).

On the Postgres server, the user should have `edb_wait_states` version 1.2 or
newer installed and loaded. The extension also needs to be created,
preferably on the main database, so the `edb_wait_states` functions are
available for PWR to collect the saved snapshot data.

## INSTALL

PWR is provided as a Python source distributed package for all supported
operating systems. It can be found in the `enterprise` and `standard`
repositories.

To install PWR just run the following commands on RHEL, SLES, and Debian based
distributions respectively:

```bash
sudo dnf install edb-pwr
```

```bash
sudo zypper install edb-pwr
```

```bash
sudo apt install edb-pwr
```

Both commands will pull and install the `edb-lasso` package as well from
the repository if it still needs to be installed on the machine.

**IMPORTANT:**
`edb-lasso` requires a configuration file to be present to work properly.
Please refer to the [lasso documentation](https://www.enterprisedb.com/docs/lasso/latest/configuration/)
for more information on how to configure it.

### `pwr` configuration file

In order to lower the number of command-line arguments needed when executing
`pwr`, if there are a subset of options that will always be the same, and
different from the default, these can be configured in a configuration file.

On execution, `pwr` will look for a configuration file in the following places,
using the first one found:

1. File pointed through `--config` command-line option, if given;
2. File pointed by `PWR_CONFIG_FILE` environment variable, if set;
3. `~/.pwr.conf`;
4. `/etc/pwr.conf`.

The user can find a template for the configuration file installed by the
package in `/etc/pwr.conf.templ`. We recommend copying this file to one of the
two places where `pwr` will look for a configuration file by default, i.e.
locations `3.` and `4.` from the above list, and edit the options
appropriately.

**Note:** if no configuration file is found, `pwr` will assume the default value
for all options, which can still be override through the corresponding
command-line options.

**Note:** although the configuration file extension is `.conf`, its content must
be in **valid** YAML format.

#### `input_dir`

The value given in `input_dir` has to be an existing directory where the
`edb_wait_states` contents of a Lasso report are located. This is used mainly
for `pwr report` execution (see below for usage instructions)

#### `output_dir`

The value given in `output_dir` is where the reports are going to be outputted.
PWR will try to create the directory on execution if it doesn't exist.

#### `report_name`

The name of the report files generated. Usually this option is better used
from the command line, given that different reports will very likely have
different names.

#### `log_file`

Full path to the file where `pwr` will write the stdout and stderr logs.

#### `log_level`

Log level to use when running `pwr`. Valid values are, from more verbose to
less verbose: `DEBUG`, `INFO` (default if not specified), `WARNING`, `ERROR`,
and `CRITICAL`.

See [the Python logging](https://docs.python.org/3/library/logging.html#logging-levels) documentation for more information on log levels.

#### `log_format`

Format of the log messages that will be written to the log file. See
[the Python logging](https://docs.python.org/3/library/logging.html#logrecord-attributes) documentation for more information on log formatting.

#### `assets_dir`

Directory where the jinja templates used to format the HTML output and the CSS
used for the PDF output can be found. The value you may want to use by default
is `/usr/share/pwr/assets` which contains the assets provided with the `edb-pwr`
package.

## Usage

As stated before, PWR can only provide reports for Postgres servers which have
version 1.2 or newer of the `edb_wait_states` extension loaded, and can only
provide query wait reports for intervals of time in which it was loaded on
the server.

Check the documentation page for more information on
[`edb_wait_states`](https://www.enterprisedb.com/docs/pg_extensions/wait_states/).

Once the `edb-pwr` and `edb-lasso` packages are installed on the machine, and
the server has been running with the `edb_wait_states` extension loaded for a
long enough period of time, we use the `PWR` tool to extract reports of
wait states for the queries that were running during the interval of time
specified.

Alternatively, PWR can generate reports from an existing Lasso report, given
the report was executed on a server with `edb_wait_states` loaded. For this
reason PWR has a mandatory first argument which can be one of the following
two:

- `execute`
- `report`

The `execute` argument will perform the end-to-end execution, calling `lasso`
with appropriate options, and using the generated tarball report as the input
to generate the HTML, Markdown, DOCX or PDF report.

On the other hand, for the `report` argument there needs to be an existing
`lasso` report, decompressed and untarred. The directory where all the `lasso`
report contents are will be used as input for processing and generating the
wait states report.

### `pwr execute`

Let's consider the following example. We need to have a report on query waits
of the Postgres server `myserver` (main database on the server where
`edb_wait_states` is installed is `my-oltp`) in the interval between
January 10th at 9:00 until January 10th at 13:00 (an incident happened
around that time which needs to be investigated to provide a Root Cause).

To get such a report in HTML format the user would need to use the following
command:

```bash
pwr execute --host-name myserver --sampling-start '2024-01-10 09:00+00' \
    --sampling-end '2024-01-10 13:00+00' --html \
    --report-name 'Jan10_incident' my-oltp postgres 
```

**Note:** `--sampling-start` and `--sampling-end` acept both timestamps with or
without time zone. If you do not explicitly set a time zone in the timestamp
then PWR will use the system time zone.

User can run `pwr execute -h` to get the full output of options available.

**Note:** to avoid overwriting previous reports, the `pwr execute` command will
append to the report name provided through the configuration file or the
`--report-name` option the database name and a timestamp with the format
`%Y%m%d%H%M%S` (e.g. `March_report-mydatabase-20240321-133727.html`).
To avoid this behavior, the user can use the `--use-plain-report-name` option
when executing `pwr execute`.

### `pwr report`

In some cases the user may already have a Lasso report and would like to have
PWR use that as the source and build the report based on it. For these cases,
the `pwr report` option comes in handy.

Let's use the same example as above but with an already executed Lasso report
with the time boundaries shared above. Let's suppose that the Lasso report's
name is `edb-lasso-Jan10-incident.tar.bz2` which is located in the home
directory of the machine where `pwr report` will be executed.

The following command executions would provide an HTML report saved in
`~/pwr_output/Jan10_incident.html`:

```bash
cd ~/
mkdir -p pwr_tmp/
tar jxf ../edb-lasso-Jan10-incident.tar.bz2 -C ~/pwr_tmp/ --strip-components=1
pwr report \
    --input-dir ~/pwr_tmp/postgresql/dbs/my-oltp/edb_wait_states/ \
    --html --output-dir ~/pwr_output/ --report-name 'Jan10_incident'
```

User can run `pwr report -h` to get the full output of options available.

**Note:** to avoid overwriting previously generated reports, the `pwr report`
command will append to the report name provided through the configuration file
or the `--report-name` option a timestamp with the format
`%Y%m%d%H%M%S` (e.g. `March_report-20240321-133727.html`).
To avoid this behavior, the user can use the `--use-plain-report-name` option
when executing `pwr report`.

