From 01d3752becd195baea0d344bd6829ecd5fc17038 Mon Sep 17 00:00:00 2001 From: Israel Barth Rubio Date: Tue, 12 Mar 2024 14:41:07 -0300 Subject: [PATCH 1/6] Add `PWR_CONFIG_FILE` env variable to PWR documentation This commit modifies the PWR docs so it contains information about the environment variable `PWR_CONFIG_FILE`, which can be used to specify a config file for PWR. References: PGCP-58. Signed-off-by: Israel Barth Rubio --- product_docs/docs/pwr/1/configuring.mdx | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/product_docs/docs/pwr/1/configuring.mdx b/product_docs/docs/pwr/1/configuring.mdx index 2b5cecf2755..d9a8e0ab71d 100644 --- a/product_docs/docs/pwr/1/configuring.mdx +++ b/product_docs/docs/pwr/1/configuring.mdx @@ -8,11 +8,17 @@ description: "How to configure Postgres Workload Report after installation" 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 and whose values differ from the default. -During execution, `pwr` looks for an existing configuration file in `~/.pwr.conf` and `/etc/pwr.conf`, in that order, and uses the first one found. -However, if the `--config` option specifies a configuration file, that value overrides the default locations. +During execution, `pwr` looks for a configuration file in the following places, and uses 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 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. +two places where `pwr` looks for a configuration file by default, i.e. locations `3.` and `4.` from the above list, and editing the options in the template as necessary. + +**Note:** if no configuration file is found, `pwr` assumes the default value for all options, which can still be override through the corresponding command-line options. You can configure the following options. From 70909f10ae78de3f0929a6f565ba967a7b131097 Mon Sep 17 00:00:00 2001 From: Israel Barth Rubio Date: Tue, 12 Mar 2024 15:07:46 -0300 Subject: [PATCH 2/6] Adjust writing style as instructed in the contributing guidelines Signed-off-by: Israel Barth Rubio --- product_docs/docs/pwr/1/configuring.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/product_docs/docs/pwr/1/configuring.mdx b/product_docs/docs/pwr/1/configuring.mdx index d9a8e0ab71d..bd91f431c70 100644 --- a/product_docs/docs/pwr/1/configuring.mdx +++ b/product_docs/docs/pwr/1/configuring.mdx @@ -10,13 +10,13 @@ To reduce the number of command-line arguments needed when executing `pwr`, you During execution, `pwr` looks for a configuration file in the following places, and uses 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`; +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 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 by default, i.e. locations `3.` and `4.` from the above list, and editing the options in the template as necessary. +two places where `pwr` looks for a configuration file by default, that is locations `3.` and `4.` from the previous list, and editing the options in the template as necessary. **Note:** if no configuration file is found, `pwr` assumes the default value for all options, which can still be override through the corresponding command-line options. From 718964eb2d712ac286ef532b0a505f809fa54e12 Mon Sep 17 00:00:00 2001 From: Israel Barth Rubio Date: Tue, 12 Mar 2024 15:11:57 -0300 Subject: [PATCH 3/6] Adjust writing style as instructed in the contributing guidelines Signed-off-by: Israel Barth Rubio --- product_docs/docs/pwr/1/configuring.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/product_docs/docs/pwr/1/configuring.mdx b/product_docs/docs/pwr/1/configuring.mdx index bd91f431c70..42ef836cb08 100644 --- a/product_docs/docs/pwr/1/configuring.mdx +++ b/product_docs/docs/pwr/1/configuring.mdx @@ -18,7 +18,9 @@ During execution, `pwr` looks for a configuration file in the following places, 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 by default, that is locations `3.` and `4.` from the previous list, and editing the options in the template as necessary. -**Note:** if no configuration file is found, `pwr` assumes the default value for all options, which can still be override through the corresponding command-line options. +!!! Note + If no configuration file is found, `pwr` assumes the default value for all options, which can still be override through the corresponding command-line options. +!!! You can configure the following options. From e218c8dfd3e1fd16362bcb8b5a1333ce7a58b3e1 Mon Sep 17 00:00:00 2001 From: Israel Barth Rubio Date: Tue, 12 Mar 2024 15:18:19 -0300 Subject: [PATCH 4/6] Fix typo in note syntax Signed-off-by: Israel Barth Rubio --- product_docs/docs/pwr/1/configuring.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pwr/1/configuring.mdx b/product_docs/docs/pwr/1/configuring.mdx index 42ef836cb08..6dc53edc3ce 100644 --- a/product_docs/docs/pwr/1/configuring.mdx +++ b/product_docs/docs/pwr/1/configuring.mdx @@ -19,7 +19,7 @@ The installation package creates a template for the configuration file in `/etc/ two places where `pwr` looks for a configuration file by default, that is locations `3.` and `4.` from the previous list, and editing the options in the template as necessary. !!! Note - If no configuration file is found, `pwr` assumes the default value for all options, which can still be override through the corresponding command-line options. +If no configuration file is found, `pwr` assumes the default value for all options, which can still be override through the corresponding command-line options. !!! You can configure the following options. From 6a7306a3245dd931c1b6ae8d4a7e158298078001 Mon Sep 17 00:00:00 2001 From: Josh Heyer Date: Tue, 12 Mar 2024 12:19:10 -0700 Subject: [PATCH 5/6] Style guide compliance --- product_docs/docs/pwr/1/configuring.mdx | 28 ++++++++++++------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/product_docs/docs/pwr/1/configuring.mdx b/product_docs/docs/pwr/1/configuring.mdx index 6dc53edc3ce..2f6f18c4613 100644 --- a/product_docs/docs/pwr/1/configuring.mdx +++ b/product_docs/docs/pwr/1/configuring.mdx @@ -4,45 +4,45 @@ navTitle: "Configuring" description: "How to configure Postgres Workload Report after installation" --- -## `pwr` configuration file +## The Postgres Workload Report 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 and whose values differ from the default. -During execution, `pwr` looks for a configuration file in the following places, and uses the first one found: +During execution, Postgres Workload Report looks for a configuration file in the following places, and uses 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. +1. The file named in the `--config` command-line option, if given. +2. The file named in the `PWR_CONFIG_FILE` environment variable, if set. 3. `~/.pwr.conf`. 4. `/etc/pwr.conf`. 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 by default, that is locations `3.` and `4.` from the previous list, and editing the options in the template as necessary. +two places where Postgres Workload Report looks for a configuration file by default (locations #3 or #4 in the previous list), and editing the options in the template as necessary. !!! Note -If no configuration file is found, `pwr` assumes the default value for all options, which can still be override through the corresponding command-line options. +If no configuration file is found, Postgres Workload Report assumes the default value for all options, which can still be overriden via the corresponding command-line options. See [Using Postgres Workload Report](using/) for more on using command-line options. !!! -You can configure the following options. +## Configuration file options ### `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 Postgres Workload Report](using)). +An existing directory where the `edb_wait_states` portion of a Lasso report are located. This option is used mainly for `pwr report` execution (see [Using Postgres Workload Report](using)). ### `output_dir` -Specifies where to output reports. During execution, Postgres Workload Report tries to create the directory if it doesn't exist. +Location of the directory where Postgres Workload Report writes report files. Executing `pwr` will create this directory if it doesn't exist. ### `report_name` -Provides the name of the report files generated. Usually, you specify this option from the command line because different reports typically have different names. +The name of the report files generated (without a file type extension - that will be added based on the output format(s) specified on the command line). Usually, you would specify this option on 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. +The full path to the file where Postgres Workload Report writes the `stdout` and `stderr` logs. ### `log_level` -Specifies the logging level to use when running Postgres Workload Report. The following are valid values, listed from more verbose to less verbose: +The logging level to use when running Postgres Workload Report. The following are valid values, listed from more verbose to less verbose: `DEBUG` `INFO` (default if not specified) @@ -54,8 +54,8 @@ See [the Python logging](https://docs.python.org/3/library/logging.html#logging- ### `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. +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 to use by default is `/usr/share/pwr/assets`, which contains the assets provided with the `edb-pwr` package. +The directory containing the Jinja templates used to format the HTML output and the CSS used for PDF output. The default value is `/usr/share/pwr/assets`, which contains the assets provided with the `edb-pwr` package. From 5baa5d2825be731fb562b31b18a3a31ee9d73766 Mon Sep 17 00:00:00 2001 From: Josh Heyer Date: Tue, 12 Mar 2024 12:39:08 -0700 Subject: [PATCH 6/6] Correctly format list of log options. Simplify introduction. Eliminate long parenthetical --- product_docs/docs/pwr/1/configuring.mdx | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/product_docs/docs/pwr/1/configuring.mdx b/product_docs/docs/pwr/1/configuring.mdx index 2f6f18c4613..7c9b8e6bd18 100644 --- a/product_docs/docs/pwr/1/configuring.mdx +++ b/product_docs/docs/pwr/1/configuring.mdx @@ -4,11 +4,11 @@ navTitle: "Configuring" description: "How to configure Postgres Workload Report after installation" --- -## The Postgres Workload Report 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 and whose values differ from the default. -During execution, Postgres Workload Report looks for a configuration file in the following places, and uses the first one found: +## Configuration file locations + +Postgres Workload Report looks for a configuration file in the following places, and uses the first one found: 1. The file named in the `--config` command-line option, if given. 2. The file named in the `PWR_CONFIG_FILE` environment variable, if set. @@ -34,7 +34,9 @@ Location of the directory where Postgres Workload Report writes report files. Ex ### `report_name` -The name of the report files generated (without a file type extension - that will be added based on the output format(s) specified on the command line). Usually, you would specify this option on the command line because different reports typically have different names. +The name of the report files generated. Usually, you would specify this option on the command line because different reports typically have different names. + +Don't include a file extension; an appropriate extension will be added will be added based on the output format(s) specified on the command line (`--pdf` adds `.pdf`, `--html` adds `.html`, and so on). ### `log_file` @@ -44,11 +46,11 @@ The full path to the file where Postgres Workload Report writes the `stdout` and The logging level to use when running Postgres Workload Report. The following are valid values, listed from more verbose to less verbose: - `DEBUG` - `INFO` (default if not specified) - `WARNING` - `ERROR` - `CRITICAL` +- `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.