Merge branch 'main' into nethalo-patch-1

percona · Nov 22, 2023 · 6e03482 · 6e03482
2 parents 400eb00 + d46ab27
commit 6e03482
Show file tree

Hide file tree

Showing 36 changed files with 387 additions and 38 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,4 +1,4 @@
-name: Build PMM Docs (2.x)
+name: Build PMM Docs 2.x
 
 on:
   push:
@@ -14,14 +14,15 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: percona-platform/checkout@v2
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Setup Python
-        uses: percona-platform/setup-python@v2
+        uses: actions/setup-python@v4
         with:
-          python-version: "3.x"
+          python-version: '3.x'
+          cache: 'pip'
 
       - name: Setup MkDocs
         run: |

diff --git a/.github/workflows/helm-tests.yml b/.github/workflows/helm-tests.yml
@@ -6,7 +6,7 @@ on:
       - main
   pull_request:
     paths:
-      - "docs/setting-up/server/helm.md"
+      - 'docs/setting-up/server/helm.md'
 
   workflow_dispatch:
 
@@ -16,12 +16,12 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: percona-platform/checkout@v2
+        uses: actions/checkout@v4
         with:
           fetch-depth: 1
 
       - name: Install pandoc
-        run: | 
+        run: |
           wget https://github.com/jgm/pandoc/releases/download/2.18/pandoc-2.18-1-amd64.deb
           sudo apt-get install -y ./pandoc-2.18-1-amd64.deb
 
@@ -35,7 +35,7 @@ jobs:
         run: minikube start
 
       - name: Setup storage driver for snapshots
-        run: | 
+        run: |
           minikube addons disable storage-provisioner
           kubectl delete storageclass standard
           minikube addons enable csi-hostpath-driver
@@ -47,7 +47,7 @@ jobs:
 
       - name: Get debug
         if: ${{ failure() }}
-        run: | 
+        run: |
           cat ./docs_test_helm.sh
           pandoc --version
           helm version

diff --git a/.github/workflows/podman-tests.yml b/.github/workflows/podman-tests.yml
@@ -6,7 +6,7 @@ on:
       - main
   pull_request:
     paths:
-      - "docs/setting-up/server/podman.md"
+      - 'docs/setting-up/server/podman.md'
 
   workflow_dispatch:
 
@@ -16,12 +16,12 @@ jobs:
 
     steps:
       - name: Check out code
-        uses: percona-platform/checkout@v2
+        uses: actions/checkout@v4
         with:
           fetch-depth: 1
 
       - name: Install pandoc
-        run: | 
+        run: |
           wget https://github.com/jgm/pandoc/releases/download/2.18/pandoc-2.18-1-amd64.deb
           sudo apt-get install -y ./pandoc-2.18-1-amd64.deb
 
@@ -36,7 +36,7 @@ jobs:
 
       - name: Get debug
         if: ${{ failure() }}
-        run: | 
+        run: |
           cat ./docs_test_podman.sh
           pandoc --version
           podman version

diff --git a/docs/_images/Backup_Failed_Template.png b/docs/_images/Backup_Failed_Template.png
diff --git a/docs/_images/Inventory.png b/docs/_images/Inventory.png
diff --git a/docs/_images/K8s_overview_dashboard_for_operators.png b/docs/_images/K8s_overview_dashboard_for_operators.png
diff --git a/docs/_images/K8s_summary_dashboard_for_operators.png b/docs/_images/K8s_summary_dashboard_for_operators.png
diff --git a/docs/_images/PMM_DB_clusters_managed_percona_kubernetes_operators.png b/docs/_images/PMM_DB_clusters_managed_percona_kubernetes_operators.png
diff --git a/docs/_images/PMM_Inventory_Item_Selection.png b/docs/_images/PMM_Inventory_Item_Selection.png
diff --git a/docs/_images/PMM_Inventory_Node_Agent_Properties..png b/docs/_images/PMM_Inventory_Node_Agent_Properties..png
diff --git a/docs/_images/PMM_Inventory_Node_Selection.png b/docs/_images/PMM_Inventory_Node_Selection.png
diff --git a/docs/_images/PMM_Inventory_cluster_view.png b/docs/_images/PMM_Inventory_cluster_view.png
diff --git a/docs/_images/PMM_Inventory_cluster_view_details.png b/docs/_images/PMM_Inventory_cluster_view_details.png
diff --git a/docs/_images/PMM_Inventory_node_service_relation.png b/docs/_images/PMM_Inventory_node_service_relation.png
diff --git a/docs/_images/PMM_Inventory_service_node_relation.png b/docs/_images/PMM_Inventory_service_node_relation.png
diff --git a/docs/_images/PMM_access_control_add_labels_services.png b/docs/_images/PMM_access_control_add_labels_services.png
diff --git a/docs/_images/PMM_access_control_add_labels_to_add.png b/docs/_images/PMM_access_control_add_labels_to_add.png
diff --git a/docs/_images/PMM_access_control_add_main_details.png b/docs/_images/PMM_access_control_add_main_details.png
diff --git a/docs/_images/PMM_access_control_add_services.png b/docs/_images/PMM_access_control_add_services.png
diff --git a/docs/_images/PMM_access_control_labels_types.png b/docs/_images/PMM_access_control_labels_types.png
diff --git a/docs/_images/PMM_access_edit_labels.png b/docs/_images/PMM_access_edit_labels.png
diff --git a/docs/details/dashboards/dashboard-inventory.md b/docs/details/dashboards/dashboard-inventory.md
@@ -8,11 +8,20 @@ To check your inventory list, go to <i class="uil uil-cog"></i> **Configuration*
 
 Inventory objects form a hierarchy with Node at the top, then Service and Agents assigned to a Node. This information is detailed in the two tabs available on this page.
 
-### **Services** tab
+### Services tab
 
-Shows individual services, the nodes on which they run, and the Agents that help collect the service metrics.
-The **Status** column shows the status of your databases based on metrics coming directly from the database.
-The **Monitoring** column summarizes the status of all the Agents assigned to the service.
+The **Services** tab displays the individual services, the nodes on which they run, and the Agents that help collect the service metrics along with the following information:
+
+
+**Service name** - The name or identifier associated with the service being monitored.
+
+**Node Name** - Name or identifier associated with a specific node. 
+
+**Monitoring status** - The **Monitoring** column summarizes the status of all the Agents assigned to the service.
+
+**Address** - The IP address or DNS where the service is currently running.
+
+**Port** - The port number on which the service is running.
 
 You can check Query Analytics information and the Service Overview Dashboard for each service by clicking on the <image src="../../_images/dots-three-vertical.ico" width="15px" aria-label="triple dots"/> icon in the **Options** column.
 
@@ -29,10 +38,73 @@ Each binary (exporter, agent) running on a client will get an `agent_type` value
 - `mysqld_exporter` and `qan-mysql-perfschema-agent` are assigned to agents that extract metrics from mysql and its performance schema respectively.
 
 To view the agents running on a service and their health status, click **OK** or **Failed** under the **Monitoring** column. Furthermore, you can also check the properties of a particular agent by clicking the <image src="../../_images/arrow-downward.ico" width="15px" aria-label="downward arrow"/> icon under the **Options** column.
+
 ![!image](../../_images/PMM_Inventory_Service_Agent_Properties.png)
 
+#### Node-service relationship
+
+Starting with PMM 2.40.0, you can click on the link in the **Node Name** column to view the node on which a specific service is running and analyze how node-level resource utilization impacts the performance of those services.
+
+Understanding the relationship between nodes and services is key to gaining insights into the distribution and performance of individual services across nodes.
+
+- **Deployment**: Services within PMM are deployed on nodes and rely on them for resources, such as CPU, memory, and storage, to execute tasks.
+
+- **Resource allocation**: It is essential to know which nodes host which services to allocate resources appropriately to avoid underuse or overload.
+
+- **Performance optimization**: By analyzing node and service-level metrics, you can pinpoint and resolve issues that impede service performance, such as resource limitations and performance bottlenecks.
+
+- **Incident response**: When an issue or incident occurs, understanding the node-service relationship helps in troubleshooting. You can quickly identify which nodes and services are affected and focus your efforts on resolving the problem.
+
+### Editing labels for a service
+
+You can edit the labels as follows:
+
+1. From the **Main** menu, navigate to <i class="uil uil-cog"></i> **Configuration → Inventory**.
+
+2. Click on the three dots next to the service you want to edit labels for.
+
+3. Click **Edit**. The **Edit Service** page opens.
+
+4. Edit the labels as per your requirement and click **Save Changes**. The editing service dialogue box opens.
+
+    ![!](../../_images/PMM_access_edit_labels.png)
 
-### **Nodes** tab
+
+5. Click **Confirm and save changes**. You will be taken back to the **Inventory/Services** page.
+
+#### Effect of editing labels for a service
+
+Editing existing labels can impact the following PMM functions:
+
+- **Alerting** 
+
+    Editing labels without updating alerting rules can lead to missed alerts. If an alert rule is based on specific labels that are changed or no longer apply, the alert may not trigger when it should.
+
+    Update the alert rules promptly after editing the labels for a smooth alerting experience.
+
+- **Scheduled backup**s: Editing the cluster label will remove all scheduled backups for the imapcted service or cluster.
+
+    To prevent any issues, make sure to recreate your backups once you've configured the cluster.
+
+- **Dashboard data**: Edited labels do not affect the existing time-series(metrics). It will only affect the new time-series(metrics).
+
+
+#### Cluster view
+
+!!! caution alert alert-warning "Disclaimer"
+     This feature is still [technical preview](../details/glossary.md#technical-preview) and is subject to change. We recommend that early adopters use this feature for testing purposes only.
+
+
+Starting with PMM 2.40.0, you can choose to view a group of services as a single cluster  with the **Organize by Clusters** toggle. PMM uses the `cluster` label to display services under the same cluster.
+
+![!image](../../_images/PMM_Inventory_cluster_view.png)
+
+Click the downward arrow to view cluster details, including the services running on that cluster, agents, and labels.
+
+![!image](../../_images/PMM_Inventory_cluster_view_details.png)
+
+
+### Nodes tab
 
 Shows where the service and agents run.
 
@@ -42,6 +114,8 @@ By expanding the entry from the options column, you can check the node labels an
 
 Starting with PMM 2.38.0, you can see the number of agents running on any particular node. When you click on any node, the UI navigates to the view of agents, which is filtered to display only agents related to that specific node. 
 
+Furthermore, starting with PMM 2.40.0, you can see the service running on that specific node when you click on the link in the **Services** column.
+
 To see the details of the agents running, do the following:
 
 1. On the **Nodes** tab, under the **Monitoring** column, click **OK** or **Failed** depending on the status of the node that you have selected. A page that provides the user with crucial information regarding the total number of agents deployed on that node is displayed.

diff --git a/docs/details/dashboards/kubernetes_monitor_db_clusters_managed.md b/docs/details/dashboards/kubernetes_monitor_db_clusters_managed.md
@@ -0,0 +1,12 @@
+# DB clusters managed with Percona Kubernetes Operators
+
+
+!!! caution alert alert-warning "Important"
+    This feature is still in [Technical Preview](https://docs.percona.com/percona-monitoring-and-management/details/glossary.html#technical-preview) and is subject to change. We recommend that early adopters use this feature for testing purposes only.
+
+
+This dashboard displays the primary parameters of database clusters created by Percona Operators for various databases and helps identify the performance issues.
+
+![!image](../../_images/PMM_DB_clusters_managed_percona_kubernetes_operators.png)
+
+
diff --git a/docs/details/dashboards/kubernetes_monitor_operators.md b/docs/details/dashboards/kubernetes_monitor_operators.md
@@ -0,0 +1,21 @@
+# Kubernetes monitoring for Percona Operators 
+
+!!! caution alert alert-warning "Important"
+    This feature is still in [Technical Preview](https://docs.percona.com/percona-monitoring-and-management/details/glossary.html#technical-preview) and is subject to change. We recommend that early adopters use this feature for testing purposes only.
+
+Monitoring the state of the database is crucial to timely identify and react to performance issues. Percona Monitoring and Management (PMM) solution enables you to do just that.
+
+However, the database state also depends on the state of the Kubernetes cluster itself. Hence it’s important to have metrics that can depict the state of the Kubernetes cluster.
+
+For inforamtion on setting up monitoring for the Kubernetes cluster health, see [documentation](https://docs.percona.com/percona-operator-for-mysql/pxc/monitor-kubernetes.html). 
+
+This setup has been tested with the PMM server as the centralized data storage and the Victoria Metrics Kubernetes monitoring stack as the metrics collector. These steps may also apply if you use another Prometheus-compatible storage.
+
+
+## Kubernetes overview
+
+The Kubernetes Cluster overview dashboard gives you an overview of Kubernetes health and its objects, including Percona custom resources.
+
+![!image](../../_images/K8s_overview_dashboard_for_operators.png)
+
+
diff --git a/docs/details/pmm_components_and_versions.md b/docs/details/pmm_components_and_versions.md
@@ -2,11 +2,10 @@
 
 The following table lists all the PMM client/server components and their versions:
 
-
-| Component| Version| Documentation                                 | Repository                                                                                                  |
-|----------|--------|---------------------------------------------- |-------------------------------------------------------------------------------------------------------------|
+| PMM client/server component |Version | Documentation |Location on GitHub|
+|-----------------------------|--------|---------------|------------------|
 | Grafana  | 9.2.20*    | [Grafana Documentation](https://grafana.com/docs/grafana/latest/)|[Github Grafana](https://github.com/percona-platform/grafana)|
-| VictoriaMetrics| 1.82.1    | [VictoriaMetrics Documentation](https://docs.victoriametrics.com/)|[Github VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics)    |
+| VictoriaMetrics| 1.93.4    | [VictoriaMetrics Documentation](https://docs.victoriametrics.com/)|[Github VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics)    |
 | Nginx    | 1.20.1 | [Nginx Documentation](http://nginx.org/en/docs/)|[Github Nginx](https://github.com/nginx/nginx-releases)                                                    |
 | Percona Distribution for PostgreSQL  | 14.5    | [Percona Distribution for PostgreSQL 14 Documentation](https://www.percona.com/doc/postgresql/LATEST/index.html)|              |
 | Clickhouse| 21.3.20.1 |[ClickHouse Documentation Documentation](https://clickhouse.com/docs/en/)|[Github ClickHouse](https://github.com/ClickHouse/ClickHouse)|

diff --git a/docs/details/victoria-metrics.md b/docs/details/victoria-metrics.md
@@ -52,7 +52,34 @@ To set downsampling, use the `downsampling.period` parameter as follows:
 
 This instructs VictoriaMetrics to [deduplicate](https://docs.victoriametrics.com/#deduplication) samples older than 20 days with 10 minute intervals and samples older than 120 days with two hour intervals.
 
+## Using VictoriaMetrics external database instance
 
+!!! caution alert alert-warning "Important/Caution"
+    This feature is still in [Technical Preview](https://docs.percona.com/percona-monitoring-and-management/details/glossary.html#technical-preview) and is subject to change. We recommend that early adopters use this feature for evaluation purposes only.
+
+
+Starting with PMM 2.40.0, you can now use an external VictoriaMetrics database for monitoring in PMM.
+
+The environment variable `PMM_VM_URL` has been added, which should point to the external VictoriaMetrics database and should have the following format:
+
+```sh
+http(s)://hostname:port/path.
+```
+
+If the external VictoriaMetrics database requires basic authentication, the following environment variables should be used:
+
+```sh
+VMAGENT_remoteWrite_basicAuth_username={username}
+VMAGENT_remoteWrite_basicAuth_password={password}
+```
+If other authentication methods are used on the VictoriaMetrics side, users can use any of the `vmagent` environment variables by prepending `VMAGENT_ prefix`.
+
+When external VictoriaMetrics is configured, internal VictoriaMetrics stops. In this case, VM Agent on PMM Server pulls metrics from agents configured in the `pull metrics mode` and from remote nodes. Data is then pushed to external VictoriaMetrics.
+
+!!! note alert alert-primary "Note"
+    VM Agents run by PMM Clients push data directly to external VictoriaMetrics. 
+
+    Ensure that they can connect to external VictoriaMetrics.
 
 ## Troubleshooting
 

diff --git a/docs/get-started/backup/create_PITR_mongo.md b/docs/get-started/backup/create_PITR_mongo.md
@@ -46,11 +46,16 @@ Before creating a backup, make sure to check the [MongoDB backup prerequisites](
    query-source=profiler <mark>--cluster=mycluster</mark></code></pre>
     !!! caution alert alert-warning "Important"
         Unless you are using verified custom workflows, make sure to keep the default **Folder** value coming from the cluster name. Editing this field will impact PMM-PBM integration workflows.
+
 11. Click **Schedule** to start creating the backup artifact.
 12. Go to the **All Backups** tab, and check the **Status** column. An animated ellipsis indicator {{icon.bouncingellipsis}} shows that a backup is currently being created.
 
 ![!](../../_images/PMM_Backup_Management-MongoDB-PITR-Enable.jpg)
 
+## Failed backup alerts
+
+If you want to be notified of any MongoDB backups that fail, you can create an alert based on the Backup Failed alert template. For information on working with alert templates, see the [Percona Alerting](../get-started/alerting.md) topic.
+
 ## PITR artifacts
 
 The PITR oplog is available a few minutes (10 by default) after your PITR job has run for the first time. To see the corresponding PITR artifact, check out the list under **Backup > All Backups**.

diff --git a/docs/get-started/roles-and-permissions/lbac.md b/docs/get-started/roles-and-permissions/lbac.md
@@ -22,20 +22,51 @@ PMM supports standard as well as custom labels. PMM automatically assigns standa
 
 ## Adding labels
 
-You can add custom or standard labels in PMM while adding a service for monitoring in PMM. 
+In PMM, labels enable you to identify, categorize, and organize your monitored services and resources. Labels also simplify filtering, grouping, and analyzing data. 
+
+While adding a service for monitoring in PMM, you can add custom or standard labels.
 
 **Using PMM UI**
 
-You can set the labels using User interface as follows:
+You can set the labels using the User interface as follows:
 
-1. From the *Main* menu, navigate to <i class="uil uil-cog"></i> *Configuration → Add Service*.
+1. From the **Main** menu, navigate to <i class="uil uil-cog"></i> **Configuration → Add Service**.
 
 2. Select the service you want to add to PMM for monitoring. The page to add the service opens.
 
-3. Enter the details such as *Hostname, Service name, Port, Username, Password,* etc., along with Label or Custom labels.
+    ![!](../../_images/PMM_access_control_add_services.png)
+
+3. Enter the details such as **Hostname, Service name, Port, Username, Password, Max query length**.
+
+    ![!](../../_images/PMM_access_control_add_main_details.png)
+
+4. (Optional) Enter the **Labels** for the service being monitored.
+
+    ![!](../../_images/PMM_access_control_add_labels_to_add.png)
+
+
+
+5. (Optional) Check the **Additional Options** that you want to include, such as:
+
+    - **Skip connection check**: Do not check the connection to the database.
+
+    - **Use TLS for database connections**: Enabling TLS (Transport Layer Security) for database connections is an important security measure to protect the confidentiality and integrity of data transmitted between the PMM Server and the monitored database instances.
+
+    - **Skip TLS certificate and hostname validation**: For certain purposes, like debugging and testing, it may be necessary to bypass TLS certificate and hostname validation.
+
+    - **Table statistics limit**: Do not collect table statistics if the number of tables in a database exceeds this limit (defaults to 1000).
+
+    - **Disable comments parsing**: Filter out comments in log files or data streams to isolate valid data.
+
+    - **Use performance schema**: Use Performance Schema instead of Slow Query Log (default) for monitoring and diagnosing performance issues in your database.
+
+You can also edit the labels for a service with the PMM user interface. For details on editing labels for a service, see [Editing labels for a service](../../details/dashboards/dashboard-inventory.md)
+
+**Using pmm-admin**
+
+ You can also assign labels using [pmm-admin](../../details/commands/pmm-admin.md).
+
+
 
- ![!](../../_images/PMM_access_control_add_labels_services.png)
 
- **Using pmm-admin**
 
- You can also assign labels using [pmm-admin](../../details/commands/pmm-admin.md).