New_TOC_PMM

.github/workflows/helm-tests.yml

@@ -6,7 +6,7 @@ on:
       - main
   pull_request:
     paths:
-      - 'docs/setting-up/server/helm.md'
+      - 'docs/install-pmm/install-pmm-server/baremetal/helm.md'
 
   workflow_dispatch:
 
@@ -29,7 +29,7 @@ jobs:
         run: cp _resources/bin/doc_test_template.sh ./docs_test_helm.sh
 
       - name: Get CodeBlocks and push them to test template
-        run: pandoc -i docs/setting-up/server/helm.md --lua-filter _resources/bin/CodeBlock.lua -t html -o /dev/null >> docs_test_helm.sh
+        run: pandoc -i docs/install-pmm/install-pmm-server/baremetal/helm.md --lua-filter _resources/bin/CodeBlock.lua -t html -o /dev/null >> docs_test_helm.sh
 
       - name: Start k8s cluster
         run: minikube start

.github/workflows/podman-tests.yml

@@ -6,7 +6,7 @@ on:
       - main
   pull_request:
     paths:
-      - 'docs/setting-up/server/podman.md'
+      - 'docs/install-pmm/install-pmm-server/baremetal/podman.md'
 
   workflow_dispatch:
 
@@ -29,7 +29,7 @@ jobs:
         run: cp _resources/bin/doc_test_template.sh ./docs_test_podman.sh
 
       - name: Get CodeBlocks and push them to test template
-        run: pandoc -i docs/setting-up/server/podman.md --lua-filter _resources/bin/CodeBlock.lua -t html -o /dev/null >> docs_test_podman.sh
+        run: pandoc -i docs/install-pmm/install-pmm-server/baremetal/podman.md --lua-filter _resources/bin/CodeBlock.lua -t html -o /dev/null >> docs_test_podman.sh
 
       - name: Run podman tests
         run: ./docs_test_podman.sh

README.md

@@ -181,7 +181,7 @@ Here's how it's done.
 
     4. Navigate to `pmm-doc/docs/_images` and select `PMM_Home_Dashboard_Overlay.drawio`
 
-    5. If the dashboard layout has changed, replace the *Guide* Layer with a new screenshot and adjust the elements on the *Overlay* layer as required (To show layers, click View --> Layers). Untick the *Guide* Layer so it is not exported.
+    5. If the dashboard layout has changed, replace the *Guide* Layer with a new screenshot and adjust the elements on the *Overlay* layer as needed (To show layers, click View --> Layers). Untick the *Guide* Layer so it is not exported.
 
     6. Click File --> Export as --> PNG
 
@@ -264,4 +264,4 @@ To enable it for local builds, uncomment the line with `htmlproofer` in the `plu
 [GitHub actions]: https://github.com/percona/pmm-doc/actions
 [ImageMagick]: https://imagemagick.org/script/download.php
 [composite]: https://imagemagick.org/script/composite.php
-[Node.js]: https://nodejs.org/en/download/
+[Node.js]: https://nodejs.org/en/download/

WRITERS-NOTES.md

@@ -229,4 +229,4 @@ But to make the raw Markdown easier to read, we recommend explicitly numbering i
 Other advantages:
 
 - contents can be reused in source code comments by developers;
-- encourages authors to pay attention to the order and number of steps in a recipe.
+- encourages authors to pay attention to the order and number of steps in a recipe.

docs/get-started/advisors.md → docs/advisors/advisors.md

@@ -1,4 +1,4 @@
-# Working with Advisors
+# Advisors
 
 Percona Advisors provide automated insights and recommendations within Percona Monitoring and Management. These proactive insights help you uncover problems before they become larger issues: security risks, misconfigurations, poor performance, etc.
 
@@ -37,6 +37,7 @@ You can change the standard 24-hour interval to a custom frequency for each Advi
  - *Frequent interval* - 4 hours
 
 To change the frequency of an automatic check:
+{.power-number}
 
 1. Click **{{icon.checks}} Advisors**.
 2. Select the Advisor tab that contains the check for which you want to change the frequency.
@@ -51,6 +52,7 @@ To change the frequency of an automatic check:
 In addition to the automatic checks that run every 24 hours, you can also run checks manually, for ad-hoc assessments of your database health and performance.
 
 To run checks manually:
+{.power-number}
 
 1. Click **{{icon.checks}} Advisors** on the main menu.
 2. Select the Advisor tab that contains the checks which you want to run manually.
@@ -75,3 +77,4 @@ To see more details about the available checks and any checks that failed, click
 PMM Advisors offer a set of checks that can detect common security threats, performance degradation, data loss and data corruption.
 
 Developers can create custom checks to cover additional use cases, relevant to specific database infrastructure. For more information, see [Develop Advisor checks](https://docs.percona.com/percona-monitoring-and-management/details/develop-checks/index.html).
+

docs/alert/alert_expressions.md

@@ -0,0 +1,81 @@
+# Test alert expressions
+
+If you want to create custom templates, you can test the MetricsQL expressions for your custom template in the **Explore** section of PMM. Here you can also query any PMM internal database.
+
+To test expressions for custom templates:
+
+1. On the side menu in PMM, choose **Explore > Metrics**.
+2. Enter your expression in the **Metrics** field and click **Run query**.
+
+For example, to validate that a MongoDB instance is down, shut down a member of a three-node replica set, then check that the expression `{service_type="mongodb"}` returns **0** in **Explore > Metrics**.
+
+## Add an alert rule
+After provisioning the resources required for creating Percona templated alerts, you are now ready to create your alert:
+
+1. Go to **Alerting > Alert Rules**, and click **New alert rule**.
+2. On the **Create alert rule** page, select the **Percona templated alert** option. If you want to learn about creating Grafana alerts instead, check our [Grafana's documentation](https://grafana.com/docs/grafana/latest/alerting/).
+3. In the **Template details** section, choose the template on which you want to base the new alert rule. This automatically populates the **Name**, **Duration**, and **Severity** fields with information from the template. You can change these values if you want to override the default specifications in the template.
+4. In the **Filters** field, specify if you want the alert rule to apply only to specific services or nodes. For example: `service_name'`, Operator:`MATCH`, VALUE: `ps5.7`.
+5. From the **Folder** drop-down menu, select the location where you want to store the rule.
+6. Click **Save and Exit** to close the page and go to the **Alert Rules** tab where you can review, edit and silence your new alert.
+
+## Silence alerts
+Create a silence when you want to stop notifications from one or more alerting rules.
+
+Silences stop notifications from being sent to your specified contact points.
+
+Silenced alerts are still recorded under **Alerting > Fired Alerts** so that you can review them later. Silenced alerts are disabled for as long as it's specified in the Silence Duration or until you remove a silence.
+
+For information on creating silences, see [About alerting silences](https://grafana.com/docs/grafana/latest/alerting/silences/) in the Grafana documentation.
+
+## Deprecated alerting options
+ PMM 2.31 introduced Percona Alerting which replaces the old Integrated Alerting in previous PMM versions. In addition to full feature parity, Percona Alerting includes additional benefits like Grafana-based alert rules and a unified, easy-to-use alerting command center on the **Alerting** page.
+
+### Alerting compatibility 
+
+#### Template compatibility with previous PMM versions
+
+If you have used Integrated Alerting in previous PMM versions, your custom alert rule templates will be automatically migrated to PMM 2.31. After upgrading to this new version, you will find all your alert templates under **Alerting > Alert Templates**. 
+
+If you have any templates available in the  ``/srv/ia/templates`` folder, make sure to transfer them to ``/srv/alerting/templates`` as PMM 2.31 and later will look for custom templates in this location. 
+
+If you are upgrading from PMM 2.25 and earlier, alert templates will not be automatically migrated. This is because PMM 2.26.0 introduced significant changes to the core structure of rule templates.
+
+In this scenario, you will need to manually recreate any custom rule templates that you want to transfer to PMM 2.26.0 or later. 
+
+#### Template compatibility with other alerting tools
+
+If you have existing YAML alert templates that you want to leverage in Percona Alerting:
+
+1. Go to **Alerting > Alert Rule Templates** tab and click **Add** at the top right-hand side of the table.
+2. Click **Add** and upload a local .yaml file from your computer.
+
+#### Migrate alert rules
+Alert rules created with Integrated Alerting in PMM 2.30 and earlier are not automatically migrated to Percona Alerting. 
+
+After upgrading to PMM 2.31, make sure to manually migrate any alert rules that you want to transfer to PMM 2.31 using the [Integrated Alerting Migration Script](https://github.com/percona/pmm/blob/main/ia_migration.py).
+
+##### Script commands
+The default command for migrating rules is:
+```yaml 
+*python ia_migration.py -u admin -p admin*
+```
+To see all the available options, check the scrip help using `ia_migration.py -h`
+
+##### Script prerequisites
+- Python version 3.x, which you can download from [Python Downloads centre](https://www.python.org/downloads/).
+
+-  [Requests  library](https://requests.readthedocs.io/en/latest/user/install/#install), which you can install with the following command: ```pip install requests```. 
+
+!!! caution alert alert-warning "Important"
+    The script sets all migrated alert rules to Active. Make sure to silence any alerts that should not be firing. 
+
+For more information about the script and advanced migration options, check out the help information embedded in the script.
+
+### Disable Percona Alerting
+Percona Alerting is enabled by default in the PMM Settings. This feature adds the **Percona templated alerts** option on the **Alerting** page.
+
+If for some reason you want to disable PMM Alert templates and keep only Grafana-managed alerts:
+
+1. Go to **Configuration > PMM Settings**.
+2. Disable the **Alerting** option. The **Alerting** page will now display only Grafana-managed alert rules.

docs/alert/alert_rules.md

@@ -0,0 +1,135 @@
+
+# Alert rules
+
+Alert rules describe the circumstances under which you want to be alerted. The evaluation criteria that you define determine whether an alert will fire. 
+
+An alert rule consists of one or more queries and expressions, a condition, the frequency of evaluation, and the duration over which the condition is met. For example, you might configure an alert to fire and trigger a notification when MongoDB is down.
+
+![!](../_images/alerting-normal-alert-rule.png)
+
+An alert rule can be in three possible states:
+
+- Normal: Everything is working correctly and the conditions specified in the rule has not been met. This is the default state for newly created rules.
+- Pending: The conditions specified in the alert rule has been met, but for a time that is less than the configured duration.
+- Firing: Both the conditions and the duration specified in the alert rule have both been met.
+
+It takes at least one evaluation cycle for an alert rule to transition from one state to another (e.g., from `Normal` to `Pending`).
+
+## Alert rules templates
+
+PMM provides a set of Alert Rule templates with common events and expressions for alerting. These templates can be used as a basis for creating Alert Rules. You can also create your own templates if you need custom expressions.
+
+You can check the alert templates available for your account under **Alerting > Alert rule templates** tab. PMM lists here the following types of templates:
+
+- Built-in templates, available out-of-the-box with PMM.
+- Templates downloaded from Percona Platform.
+- Custom templates created or uploaded on the **Alerting page > Alert Templates** tab. You can also store your custom template files in your ``/srv/alerting/templates`` directory and PMM will load them during startup.
+
+### Create alert rules from alert rule templates
+
+This section focuses on creating an alert rule based on PMM templates. For information on working with the other alert types, check the Grafana documentation on [Grafana Labs](https://grafana.com/docs/grafana/latest/alerting/).
+
+### Provision alert resources
+
+Before creating PMM alert rules, configure the required alert resources:
+{.power-number}
+
+1. Go to **Configuration > PMM Settings** and ensure that the **Alerting** option is enabled. This is enabled by default starting with PMM 2.31. However, if you have disabled it, the **Alerting** page displays only Grafana-managed alert rules. This means that you will not be able to create alerts based on PMM templates.
+2. Go to **Dashboards > Browse** and check the folders available for storing alert rules. If none of the available folders are relevant for your future alert rules, click **New > New Folder** and create a custom one.
+3. Go to **Alerting > Alert Rule Templates** and check the default PMM templates. If none of the templates include a relevant expression for the type of alerts that you want to create, click **Add** to create a custom template instead.
+
+### Configure alert templates
+
+Alerts templates are YAML files that provide the source framework for alert rules.
+Alert templates contain general template details and an alert expression defined in [MetricsQL](https://docs.victoriametrics.com/MetricsQL.html). This query language is backward compatible with PromQL.
+
+### Create custom templates
+
+If none of the default PMM templates contain a relevant expression for the alert rule that you need, you can create a custom template instead.
+
+You can base multiple alert rules on the same template. For example, you can create a `pmm_node_high_cpu_load` template that can be used as the source for alert rules for production versus staging, warning versus critical, etc.
+
+### Template format
+
+When creating custom templates, make sure to use the required template format below:
+
+- **name** (required): uniquely identifies template. Spaces and special characters are not allowed.
+- **version** (required): defines the template format version.
+- **summary** (required): a template description.
+- **expr** (required): a MetricsQL query string with parameter placeholders.
+- **params**: contains parameter definitions required for the query. Each parameter has a name, type, and summary. It also may have a unit, available range, and default value.
+    - **name** (required): the name of the parameter. Spaces and special characters are not allowed.
+    - **summary** (required): a short description of what this parameter represents.
+    - **unit** (optional): PMM currently supports either s (seconds) or % (percentage).
+    - **type** (required): PMM currently supports the `float` type. `string`, `bool`, and other types will be available in a future release.
+    - **range** (optional): defines the boundaries for the value of a  float parameter
+   - **value** (optional): default parameter value. Value strings must not include any of these special characters: `< > ! @ # $ % ^ & * ( ) _ / \ ' + - = (space)`
+- **for** (required): specifies the duration of time that the expression must be met before the alert will be fired
+- **severity** (required): specifies default alert severity level
+ - **labels** (optional): are additional labels to be added to generated alerts
+
+- **annotations** (optional): are additional annotations to be added to generated alerts.
+
+??? info "Template example"
+
+    ```yaml
+    {% raw %}
+    ---
+    templates:
+      - name: pmm_node_high_cpu_load
+        version: 1
+        summary: Node high CPU load
+        expr: |-
+          (1 - avg by(node_name) (rate(node_cpu_seconds_total{mode="idle"}[5m])))
+          * 100
+          > bool [[ .threshold ]]
+        params:
+          - name: threshold
+            summary: A percentage from configured maximum
+            unit: "%"
+            type: float
+            range: [0, 100]
+            value: 80
+        for: 5m
+        severity: warning
+        annotations:
+          summary: Node high CPU load ({{ $labels.node_name }})
+          description: |-
+            {{ $labels.node_name }} CPU load is more than [[ .threshold ]]%.
+    {% endraw %}
+    ```
+
+### Test alert expressions
+If you want to create custom templates, you can test the MetricsQL expressions for your custom template in the **Explore** section of PMM. Here you can also query any PMM internal database.
+
+To test expressions for custom templates:
+{.power-number}
+
+1. On the side menu in PMM, choose **Explore > Metrics**.
+2. Enter your expression in the **Metrics** field and click **Run query**.
+
+For example, to check the CPU usage, Go to **Explore > Metrics** in your PMM dashboard and run the query expression below:
+```
+(1 - avg by(node_name) (rate(node_cpu_seconds_total{mode="idle"}[5m]))) * 100
+```
+![!](../_images/alerting-sample-query.png)
+
+Note that to paste the query above, **Explore** must be in `Code` mode, and not in `Builder` mode.
+
+### Add an alert rule
+
+After provisioning the resources required for creating Percona templated alerts, you are now ready to create your alert rule:
+{.power-number}
+
+1. Go to **Alerting > Alert Rules**, and click **New alert rule**.
+2. On the **Create alert rule** page, select the **Percona templated alert** option. If you want to learn about creating Grafana alerts instead, check our [Grafana's documentation](https://grafana.com/docs/grafana/latest/alerting/).
+3. In the **Template details** section, choose the template on which you want to base the new alert rule. This automatically populates the **Name**, **Duration**, and **Severity** fields with information from the template. You can change these values if you want to override the default specifications in the template.
+4. In the **Filters** field, specify if you want the alert rule to apply only to specific services or nodes. For example: `service_name=ps5.7`. When creating alert rule filters, consider the following:
+
+    - Filters use conjunction semantics. This means that if you add more than one filter, PMM will combine their conditions to search for matches: filter 1 AND filter 2 AND filter 3.
+    - **Label** must be an exact match. You can find a complete list of labels using the <i class="uil uil-compass"></i> **Explore** menu in PMM.
+
+5. From the **Folder** drop-down menu, select the location where you want to store the rule.
+6. Click **Save and Exit** to close the page and go to the **Alert Rules** tab where you can review, edit and silence your new alert.
+
+

docs/alert/alert_type.md

@@ -0,0 +1,13 @@
+# Alert types
+
+Percona Alerting is powered by Grafana infrastructure. It leverages Grafana's advanced alerting capabilities and provides pre-configured Alert Rule Templates that simplify creating powerful alerting rules.
+
+Depending on the datasources that you want to query, and the complexity of your required evaluation criteria, Percona Alerting enables you to create the following types of alerts:
+
+- **Percona templated alerts**: alerts based on a set of Percona-supplied templates with common events and expressions for alerting.
+If you need custom expressions on which to base your alert rules, you can also create your own templates.
+- **Grafana managed alerts**: alerts that handle complex conditions and can span multiple different data sources like SQL, Prometheus, InfluxDB, etc. These alerts are stored and executed by Grafana.
+
+The Alerting page contains are split into eight tabs: Fired Alerts, Alert Rules, Alert Rule Templates, Contact Points, Notification Policies, Silences, Alert Groups and Admin.
+
+![!](../_images/alerting-page-tabs.png)