Merge pull request #5253 from EnterpriseDB/docs/pwr/new-documentation

Progress Workload Report documentation

build-sources.json

@@ -11,6 +11,7 @@
   "epas": true,
   "pgd": true,
   "pge": true,
+  "pwr": true,
   "eprs": true,
   "hadoop_data_adapter": true,
   "jdbc_connector": true,

gatsby-config.js

@@ -94,6 +94,7 @@ const sourceToPluginConfig = {
   },
   pgpool: { name: "pgpool", path: "product_docs/docs/pgpool" },
   postgis: { name: "postgis", path: "product_docs/docs/postgis" },
+  pwr: { name: "pwr", path: "product_docs/docs/pwr" },
   repmgr: { name: "repmgr", path: "product_docs/docs/repmgr" },
   slony: { name: "slony", path: "product_docs/docs/slony" },
   tde: { name: "tde", path: "product_docs/docs/tde" },

product_docs/docs/pwr/1/configuring.mdx

@@ -0,0 +1,56 @@
+---
+title: "Configuring Postgres Workload Report"
+navTitle: "Configuring"
+---
+
+## `pwr` configuration file
+
+To reduce the number of command-line arguments needed when executing `pwr`, you can use a configuration file to specify options that always have the same value but that value differs from the default.
+
+During execution, `pwr` looks for an existing configuration file in `~/.pwr.conf` and `/etc/pwr.conf`, in that order using the first one found.
+However, if the `--config` option specifies a configuration file, that overides the default locations.
+
+The installation package creates a template for the configuration file in `/etc/pwr.conf.templ`. We recommend copying this file to one of the
+two places where `pwr` looks for a configuration file and editing the options in the template as necessary.
+
+The following sections describe the options you can configure.
+
+### `input_dir`
+
+Identifies an existing directory where the `edb_wait_states` contents of a Lasso report are located. This option is used mainly for `pwr report` execution (see [Using](using)).
+
+### `output_dir`
+
+Specifies where reports are outputted. During execution, Postgres Workload Report tries to create the directory if it doesn't exist.
+
+### `report_name`
+
+Provides the name of the report files generated. Usually, this option is specified from the command line because different reports typically have different names.
+
+### `log_file`
+
+Provides the full path to the file where `pwr` writes the `stdout` and `stderr` logs.
+
+### `log_level`
+
+Specifies the logging level to use when running Postgres Workload Report. Valid values are, from more verbose to less verbose: 
+
+    `DEBUG`
+    `INFO` (default if not specified)
+    `WARNING`
+    `ERROR`
+    `CRITICAL`
+
+See [the Python logging](https://docs.python.org/3/library/logging.html#logging-levels) documentation for more information about log levels.
+
+### `log_format`
+
+Provides the format of the log messages that are 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`
+
+Identifies the directory where you can find the jinja templates used to format the HTML output and the CSS used for PDF output. Typically, the directory you may want to use by default is `/usr/share/pwr/assets`, which contains the assets provided with the `edb-pwr` package.
+
+
+
+

product_docs/docs/pwr/1/index.mdx

@@ -0,0 +1,20 @@
+---
+title: "Postgres Workload Report"
+navigation:
+  - installing
+  - configuring
+  - using
+---
+
+Postgres Workload Report (PWR) is a Python-based tool used for building PostgreSQL workload reports in HTML, Markdown, DOCX, and PDF mode, mimicking the reports provided by the Automatic Workload Repository (AWR) reporting tool from Oracle.
+
+Using a Postgres connection, you can execute Postgres Workload Report from any machine with access to the server for which you want a report. Postgres Workload Report uses Lasso for collecting data, so Lasso is a prerequisite. The `edb-pwr` package has an explicit dependency on `edb-lasso` being installed.
+
+On the Postgres server, you should have `edb_wait_states` version 1.2 or later installed and loaded. The extension also must be created,
+preferably on the main database, so the `edb_wait_states` functions are available for Postgres Workload Report to collect saved snapshot data.
+
+For more information about PWR, see: 
+
+  - [Installing](installing)
+  - [Configuring](configuring)
+  - [Using](using)

product_docs/docs/pwr/1/installing.mdx

@@ -0,0 +1,25 @@
+---
+title: "Installing Postgres Workload Report"
+navTitle: "Installing"
+---
+
+Postgres Workload Report is provided as a Python source distributed package for all supported operating systems. It can be found in the `enterprise` and `standard` repositories.
+
+The following command installs Postgres Workload Report and, if necessary, also pulls the `edb-lasso` package from the repository and installs it too.
+
+To install Postgres Workload Report, enter the following command:
+
+```shell
+sudo <package-manager> -y install edb-pwr
+```
+
+Where: 
+
+`<package-manager>` is the package manager used with your operating system.
+
+| Package manager | Operating system                 |
+| --------------- | -------------------------------- |
+| dnf             | RHEL 8/9 and derivatives         |
+| yum             | RHEL 7 and derivatives, CentOS 7 |
+| zypper          | SLES                             |
+

product_docs/docs/pwr/1/rel_notes/100_rel_notes.mdx

@@ -0,0 +1,12 @@
+---
+title: "Postgres Workload Report 1.0.0 release notes"
+navTitle: Version 1.0.0
+---
+
+Released: 15 Feb 2024
+
+New features, enhancements, bug fixes, and other changes in Postgres Workload Report 1.0.0 include:
+
+|       Type        |                                                                                                 Description                                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Feature     | This is the initial release.    |

product_docs/docs/pwr/1/rel_notes/index.mdx

@@ -0,0 +1,11 @@
+---
+title: "Release notes"
+navigation:
+ - 100_rel_notes
+---
+
+The Postgres Workoad Report (PWR) documentation describes the latest version of PWR 1 including minor releases and patches. The release notes in this section provide information on what was new in each release. For new functionality introduced in a minor or patch release, there are also indicators within the content about what release introduced the feature.
+
+| Version                   | Release Date | 
+| ------------------------- | ------------ | 
+| [1.0.0](100_rel_notes)    | 15 Feb 2024  | 

product_docs/docs/pwr/1/using.mdx

@@ -0,0 +1,61 @@
+---
+title: "Using Postgres Workload Report"
+navTitle: "Using"
+---
+
+
+## Prerequisites
+
+Postgres Workload Report can only provide reports for Postgres servers where the `edb_wait_states` extension, version 1.2 or later, is loaded. Furthermore, PWR can only provide query wait reports for intervals of time when the `edb_wait_states` extension was loaded on the server.
+
+For more information, see [`edb_wait_states`](https://www.enterprisedb.com/docs/pg_extensions/wait_states/).
+
+## Source information for reports
+
+After 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, you can use Postgres Workload Report to extract reports of wait states for the queries that were running during the interval of time specified.
+
+Alternatively, Postgres Workload Report can generate reports from an existing Lasso report, assuming the report was executed on a server with `edb_wait_states` loaded. For this reason Postgres Workload Report has a mandatory first argument, which can be either of the following
+two:
+
+- `execute`
+- `report`
+
+The `execute` argument performs end-to-end execution, calling `lasso` with appropriate options and using the generated tarball report as the input
+to generate an HTML, Markdown, DOCX, or PDF report.
+
+The `report` argument uses the directory for stored `lasso` report contents as input for processing and generating the wait states report. To use the `report` argument, a decompressed and untarred `lasso` report must already exist. 
+
+## Example for the `execute` option
+
+For this example we want to generate a report on query waits for the Postgres server `myserver` for the interval between January 10th at 9:00 and January 10th at 13:00. An incident happened around that time which must be investigated to provide a root cause. The main database on the server where `edb_wait_states` is installed is `my-oltp`. 
+
+To get such a report in HTML format we would use the following command:
+
+```shell
+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 
+```
+
+We can run `pwr execute -h` to get the full output of options available.
+
+## Example for the `report` option
+
+In some cases you may already have a Lasso report and would like PWR to use the Lasso report as the source and build a report based on it. For these cases, the `pwr report` option is useful.
+
+For this example we can use the same scenario already described but we use a Lasso report that has already been executed using the time boundaries shared above. Let's suppose that the Lasso report's name is `edb-lasso-Jan10-incident.tar.bz2` and it is located in the home directory of the machine where `pwr report` will be executed.
+
+The following command executions generate an HTML report saved in `~/pwr_output/Jan10_incident.html`:
+
+```shell
+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'
+```
+
+We can run `pwr report -h` to get the full output for the options available.
+
+

src/constants/products.js

@@ -74,6 +74,10 @@ export const products = {
     name: "EDB Postgres for Kubernetes",
     iconName: IconNames.KUBERNETES,
   },
+  pwr: {
+    name: "Postgres Workload Report",
+    iconName: IconNames.TOOLS,
+  },
   // note: the key here doesn't have to be anything specific,
   // as long as it matches the value used for the `product:` key in the relevant frontmatter
   // I recommend using the actual product name (same as what's used in the next line), just to

src/pages/index.js

@@ -323,6 +323,9 @@ const Page = () => {
               <IndexCardLink to="/livecompare/latest">
                 LiveCompare
               </IndexCardLink>
+              <IndexCardLink to="/pwr/latest">
+                Postgres Workload Report
+              </IndexCardLink>
             </IndexCard>
 
             <IndexCard iconName={iconNames.INSTANCES} headingText="Automation">