diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index f0a34505cc..372b778803 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,4 +1,4 @@ -name: Build PMM Docs 2.x +name: Build PMM Docs 3.x on: push: @@ -43,6 +43,6 @@ jobs: # Builds Material-themed static web site in 'preview' branch - name: Build a themed site (2.x) run: | - PATH=$PATH:_resources/bin mike deploy 2.x -b preview - mike set-default 2.x -b preview - mike retitle 2.x "PMM 2.x (LATEST)" -b preview + PATH=$PATH:_resources/bin mike deploy 3.x -b preview + mike set-default 3.x -b preview + mike retitle 3.x "PMM 3.x (LATEST)" -b preview diff --git a/README.md b/README.md index 94da48eac5..0415dd116a 100644 --- a/README.md +++ b/README.md @@ -20,9 +20,11 @@ We use [MkDocs] to convert [Markdown] files into a static HTML website (or [PDF] The documentation source files are in the `docs` directory. (Other files in this repo are explained in [Directories and files](#directories-and-files).) -The two major PMM versions are kept in separate branches: +The three major PMM versions are kept in separate branches: -- `main` is for PMM 2.x (latest) +- `PMM3-branch` is for PMM 3.x (latest) + +- `main` is for PMM 2.x - `1.x` is for PMM 1.x @@ -159,7 +161,7 @@ View the site at ## Version switching -We use [mike] to build different versions of the documentation. Currently, only two are built, the latest PMM 1 and PMM 2 versions. +We use [mike] to build different versions of the documentation. Currently, only two are built, the latest PMM 2 and PMM 3 versions. A [GitHub actions] workflow runs `mike` which in turn runs `mkdocs`. The HTML is committed and pushed to the `publish` branch. The whole branch is then copied (by an internal Percona Jenkins job) to our web server. diff --git a/docs/Update_page.png b/docs/Update_page.png new file mode 100644 index 0000000000..9a1b1bbc36 Binary files /dev/null and b/docs/Update_page.png differ diff --git a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg index e749e7bb0e..539cf47e5a 100644 Binary files a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg and b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade.jpg differ diff --git a/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png new file mode 100644 index 0000000000..5017337d14 Binary files /dev/null and b/docs/_images/PMM_Home_Dashboard_Panels_Upgrade2.png differ diff --git a/docs/_images/PMM_Inventory_Item_Selection.png b/docs/_images/PMM_Inventory_Item_Selection.png index d62e516ef2..6c63f67c74 100644 Binary files a/docs/_images/PMM_Inventory_Item_Selection.png and b/docs/_images/PMM_Inventory_Item_Selection.png differ diff --git a/docs/_images/PMM_Inventory_Node_Agent_Properties.png b/docs/_images/PMM_Inventory_Node_Agent_Properties.png index 6384e0d73a..7968b8596f 100644 Binary files a/docs/_images/PMM_Inventory_Node_Agent_Properties.png and b/docs/_images/PMM_Inventory_Node_Agent_Properties.png differ diff --git a/docs/_images/PMM_Inventory_Node_Selection.png b/docs/_images/PMM_Inventory_Node_Selection.png index e442b8ac86..9044bdae26 100644 Binary files a/docs/_images/PMM_Inventory_Node_Selection.png and b/docs/_images/PMM_Inventory_Node_Selection.png differ diff --git a/docs/_images/PMM_Inventory_Service_Selection.jpg b/docs/_images/PMM_Inventory_Service_Selection.jpg new file mode 100644 index 0000000000..6be98841d0 Binary files /dev/null and b/docs/_images/PMM_Inventory_Service_Selection.jpg differ diff --git a/docs/_images/PMM_Inventory_Service_Selection.png b/docs/_images/PMM_Inventory_Service_Selection.png index c6514d3588..b73de5dee3 100644 Binary files a/docs/_images/PMM_Inventory_Service_Selection.png and b/docs/_images/PMM_Inventory_Service_Selection.png differ diff --git a/docs/_images/PMM_Inventory_cluster_view.png b/docs/_images/PMM_Inventory_cluster_view.png index 4bd3b6bdcd..2956e6e592 100644 Binary files a/docs/_images/PMM_Inventory_cluster_view.png and b/docs/_images/PMM_Inventory_cluster_view.png differ diff --git a/docs/_images/PMM_Inventory_cluster_view_details.png b/docs/_images/PMM_Inventory_cluster_view_details.png index 386dcb757c..d2a6b6e91f 100644 Binary files a/docs/_images/PMM_Inventory_cluster_view_details.png and b/docs/_images/PMM_Inventory_cluster_view_details.png differ diff --git a/docs/_images/PMM_Inventory_cluster_view_filter.png b/docs/_images/PMM_Inventory_cluster_view_filter.png index ad21a32d85..fe05796845 100644 Binary files a/docs/_images/PMM_Inventory_cluster_view_filter.png and b/docs/_images/PMM_Inventory_cluster_view_filter.png differ diff --git a/docs/_images/PMM_Settings_Metrics_Resolution.jpg b/docs/_images/PMM_Settings_Metrics_Resolution.jpg index ecc348b6e4..199dcb2197 100644 Binary files a/docs/_images/PMM_Settings_Metrics_Resolution.jpg and b/docs/_images/PMM_Settings_Metrics_Resolution.jpg differ diff --git a/docs/_images/PMM_Settings_SSH_Key.jpg b/docs/_images/PMM_Settings_SSH_Key.jpg index 82ba0fd697..2cda5badae 100644 Binary files a/docs/_images/PMM_Settings_SSH_Key.jpg and b/docs/_images/PMM_Settings_SSH_Key.jpg differ diff --git a/docs/_images/PMM_access_edit_labels.png b/docs/_images/PMM_access_edit_labels.png index 9028c8491d..90b90548e8 100644 Binary files a/docs/_images/PMM_access_edit_labels.png and b/docs/_images/PMM_access_edit_labels.png differ diff --git a/docs/_images/scrape_targets_03.png b/docs/_images/scrape_targets_03.png index 821e3135f9..215afd3abc 100644 Binary files a/docs/_images/scrape_targets_03.png and b/docs/_images/scrape_targets_03.png differ diff --git a/docs/alert/index.md b/docs/alert/index.md index 88a1d7d289..bc795e6920 100644 --- a/docs/alert/index.md +++ b/docs/alert/index.md @@ -1,13 +1,7 @@ # About Percona Alerting - -!!! alert alert-info "Important" - Percona Alerting is the new Alerting feature introduced in PMM 2.31. This replaces the Integrated Alerting feature available in previous versions. Alerting notifies of important or unusual activity in your database environments so that you can identify and resolve problems quickly. When something needs your attention, Percona Alerting can be configured to automatically send you a notification through your specified contact points. - -PMM 2.31 introduced Percona Alerting which replaces 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. - Percona Alerting is enabled by default in the PMM Settings. This feature adds the **Alert rule templates** option on the main menu and alert template options on the **Alerting** page. These options enable you to create alerts based on a set of Percona-supplied templates with common events and expressions for alerting. diff --git a/docs/alert/silence_alerts.md b/docs/alert/silence_alerts.md index c77433c828..e222e22d92 100644 --- a/docs/alert/silence_alerts.md +++ b/docs/alert/silence_alerts.md @@ -1,7 +1,7 @@ # Silence alerts Create a silence when you want to suppress/stop alerts and their associated notifications for a very specific amount of time. -Silences default to today’s current date and have a default duration of two hours. +Silences default to today’s current date and have a default duration of two hours. You can also schedule a silence for a future date and time. This is referred to as a `Pending` silence, which can be observed on the Silences page. @@ -14,6 +14,7 @@ Silenced alerts are still recorded under **Alerting > Fired Alerts** so that you You can silence an alert by creating a silence from the **Silences** page. Here you define labels that match the alert that you want to silence. To create a new silence: +{.power-number} 1. Click the **Create silence** button. 2. Select the start and end date to indicate when the silence should go into effect and expire. @@ -27,15 +28,16 @@ For more information on working with silences, see [About alerting silences](htt ## Alerting compatibility -### Template compatibility with previous PMM versions +### Template compatibility with PMM 2 -If you have used Integrated Alerting in previous PMM versions, your custom alert rule templates will be automatically migrated to the new PMM version. After upgrading to the new version, you will find all your alert templates under **Alerting > Alert rule templates**. +After upgrading from the latest PMM 2 version to PMM 3, you will find all your alert templates under **Alerting > Alert rule 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 have any templates available in the `/srv/ia/templates` folder, make sure to transfer them to `/srv/alerting/templates` as PMM 3 will look for custom templates in this location. ### Template compatibility with other alerting tools If you have existing YAML alert templates that you want to leverage in Percona Alerting: +{.power-number} 1. Go to **Alerting > Alert rule templates** tab and click **Add template** at the top right-hand side of the table. 2. Upload a local .yaml file that contains the definition of one or more alert templates then click **Add**. Alert templates added in bulk will be displayed individually on **Alert rule templates** page. diff --git a/docs/annotate/index.md b/docs/annotate/index.md index d26c4257dd..c82514455a 100644 --- a/docs/annotate/index.md +++ b/docs/annotate/index.md @@ -1,6 +1,3 @@ # PMM annotation - -!!! alert alert-info "" - Percona Alerting is the new Alerting feature introduced in PMM 2.31. This replaces the Integrated Alerting feature available in previous versions. - -Alerting notifies of important or unusual activity in your database environments so that you can identify and resolve problems quickly. When something needs your attention, PMM automatically sends you an alert through your specified contact points. \ No newline at end of file + +Alerting notifies of important or unusual activity in your database environments so that you can identify and resolve problems quickly. When something needs your attention, PMM automatically sends you an alert through your specified contact points. \ No newline at end of file diff --git a/docs/api/authentication.md b/docs/api/authentication.md index 81ed45f244..e8269af6b9 100644 --- a/docs/api/authentication.md +++ b/docs/api/authentication.md @@ -21,6 +21,13 @@ Creating multiple tokens for the same service account is beneficial in the follo - when a token becomes compromised and needs to be replaced. Instead of revoking the entire service account, you can rotate or replace the affected token without disrupting other applications using the same service account. - when you want to implement token lifecycle management. You can set expiration dates for individual tokens, ensuring that they are regularly rotated and reducing the risk of unauthorized access. +## Service Account name management + +To prevent node registration failures, PMM automatically manages service account names that exceed 200 characters using a `{prefix}_{hash}` pattern. For example, a very long service account name will be automatically shortened while maintaining uniqueness: + +- **original**: `very_long_mysql_database_server_in_production_environment_with_specific_location_details...` +- **shortened**: `very_long_mysql_database_server_in_prod_4a7b3f9d` + ## Generate a service account and token PMM uses Grafana service account tokens for authentication. These tokens are randomly generated strings that serve as alternatives to API keys or basic authentication passwords. diff --git a/docs/backup/index.md b/docs/backup/index.md index 3052fd076a..1a29005216 100644 --- a/docs/backup/index.md +++ b/docs/backup/index.md @@ -20,7 +20,7 @@ For MySQL databases, you can create and restore on-demand and scheduled physical ### Sharded MongoDB cluster configurations -PMM 2.38 added support for creating backups of sharded MongoDB clusters. However, the restoring process is not handled end-to-end, and requires you to manually restore the artifacts using the CLI in Percona Backup for MongoDB. +PMM 3 supports creating backups of sharded MongoDB clusters. However, the restoring process is not handled end-to-end, and requires you to manually restore the artifacts using the CLI in Percona Backup for MongoDB. ## Start here diff --git a/docs/backup/mongodb-backup/backup_mongo.md b/docs/backup/mongodb-backup/backup_mongo.md index c5f8ed548b..9065749590 100644 --- a/docs/backup/mongodb-backup/backup_mongo.md +++ b/docs/backup/mongodb-backup/backup_mongo.md @@ -12,7 +12,7 @@ PMM supports the following actions for MongoDB backups: ## Sharded clusters -Backups of sharded clusters is supported starting with PMM 2.38. However, restoring for sharded cluster configurations is only supported from the CLI, and is handled via [Percona Backup for MongoDB](https://docs.percona.com/percona-backup-mongodb/usage/restore.html). +PMM 3 supports backing up sharded clusters. However, restoring for sharded cluster configurations is only supported from the CLI, and is handled via [Percona Backup for MongoDB](https://docs.percona.com/percona-backup-mongodb/usage/restore.html). - Storing backups on Amazon S3-compatible object storage, and on mounted filesystem - Creating Logical snapshot backups diff --git a/docs/backup/mongodb-backup/create_PITR_mongo.md b/docs/backup/mongodb-backup/create_PITR_mongo.md index 144d6261b7..d746c00af8 100644 --- a/docs/backup/mongodb-backup/create_PITR_mongo.md +++ b/docs/backup/mongodb-backup/create_PITR_mongo.md @@ -8,7 +8,7 @@ Point-in-Time Recovery helps you prevent data loss during a disaster such as cra PMM introduced the option to create PITR Backups for MongoDB in version 2.23, as part of the larger Backup Management feature. This implementation in PMM uses Percona Backup for MongoDB (pbm) behind the scenes. Percona Backup for MongoDB is a distributed, low-impact solution for achieving consistent backups of MongoDB sharded clusters and replica sets. -Starting with PMM 2.32, restoring PITR backups is available for backups based on pbm ≤ 2.0.1. To restore PITR backups, make sure you have pbm ≥ 2.0.1 installed. +Restoring PITR backups is available for backups based on pbm ≤ 2.0.1. To restore PITR backups, make sure you have pbm ≥ 2.0.1 installed. Percona Backup for MongoDB supports [Percona Server for MongoDB](https://www.percona.com/software/mongodb/percona-server-for-mongodb) and MongoDB Community ≤ 3.6, with [MongoDB Replication](https://docs.mongodb.com/manual/replication/) enabled. For more information, see the [Percona Backup for MongoDB documentation](https://docs.percona.com/percona-backup-mongodb/installation.html). diff --git a/docs/backup/mongodb-backup/mongo_prerequisites.md b/docs/backup/mongodb-backup/mongo_prerequisites.md index 5146b9fa0d..d48af7e4f5 100644 --- a/docs/backup/mongodb-backup/mongo_prerequisites.md +++ b/docs/backup/mongodb-backup/mongo_prerequisites.md @@ -22,4 +22,4 @@ Services that do not specify a cluster name should be removed and re-added using Use `pbm` in manual mode only for restoring sharded cluster backups or other operations that can only be completed via the PBM CLI! Since PMM takes care of the PBM configuration, any unnecessary manual intervention can break the state. - PMM 2.32 and later require PBM 2.0.1 or newer. \ No newline at end of file + PMM 3 and later require PBM 2.0.1 or newer. \ No newline at end of file diff --git a/docs/backup/mongodb-backup/mongodb_limitations.md b/docs/backup/mongodb-backup/mongodb_limitations.md index 37ce94d100..038115c8e5 100644 --- a/docs/backup/mongodb-backup/mongodb_limitations.md +++ b/docs/backup/mongodb-backup/mongodb_limitations.md @@ -4,7 +4,7 @@ Creating and restoring MongoDB backups in PMM currently has the following limita - Physical backups and restores are supported only for **Percona Server for MongoDB**. - Physical restores are not supported for deployments with arbiter nodes. For more information, see the [Percona Backup for MongoDB documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html#physical-restore-known-limitations). -- Creating backups for sharded clusters was included in PMM 2.38 and is available straight from the UI. However, restoring these backup artifacts is only possible via the CLI, using Percona Backup for MongoDB. For information on restoring sharded backups, check the [PBM documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html). +- Creating backups for sharded clusters is available straight from the UI. However, restoring these backup artifacts is only possible via the CLI, using Percona Backup for MongoDB. For information on restoring sharded backups, check the [PBM documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html). - Retention policy is supported only for snapshot types of scheduled backups and for the S3-compatible storage type. - Before restoring, make sure to prevent clients from accessing the database. diff --git a/docs/backup/mongodb-backup/restore_MongoDB_backups.md b/docs/backup/mongodb-backup/restore_MongoDB_backups.md index f3666ee62b..cd4e0dd7d6 100644 --- a/docs/backup/mongodb-backup/restore_MongoDB_backups.md +++ b/docs/backup/mongodb-backup/restore_MongoDB_backups.md @@ -130,6 +130,6 @@ To restore to a new cluster manually: ### Restoring from a sharded cluster -Sharded cluster backups are supported starting with PMM 2.38 and PMM handles the backup process end-to-end. However, restoring such artifacts is currently possible only via the CLI, using Percona Backup for MongoDB. +Sharded cluster backups are supported and PMM handles the backup process end-to-end. However, restoring such artifacts is currently possible only via the CLI, using Percona Backup for MongoDB. For information on restoring sharded backups, check the [PBM documentation](https://docs.percona.com/percona-backup-mongodb/usage/restore.html) \ No newline at end of file diff --git a/docs/configure-pmm/ssh.md b/docs/configure-pmm/ssh.md index 4773496fe2..23ed580a40 100644 --- a/docs/configure-pmm/ssh.md +++ b/docs/configure-pmm/ssh.md @@ -1,6 +1,6 @@ # SSH Key -This section lets you upload your public SSH key to access the PMM Server via SSH (for example, when accessing PMM Server as a [virtual appliance](../install-pmm/install-pmm-server/baremetal/virtual/index.md). +This section enables you to upload your public SSH key for SSH access to the PMM Server, such as when accessing it as a [virtual appliance](../install-pmm/install-pmm-server/baremetal/virtual/index.md). ![!](../_images/PMM_Settings_SSH_Key.jpg) diff --git a/docs/how-to/extend-metrics.md b/docs/how-to/extend-metrics.md index 85984ddbe4..b8100a4431 100644 --- a/docs/how-to/extend-metrics.md +++ b/docs/how-to/extend-metrics.md @@ -9,9 +9,9 @@ The collector is enabled by default. The following folders are used for differen | Resolution | Folder | |------------|---------------------------------------------------------------------------| -| High | `/usr/local/percona/pmm2/collectors/textfile-collector/high-resolution` | -| Medium | `/usr/local/percona/pmm2/collectors/textfile-collector/medium-resolution` | -| Low | `/usr/local/percona/pmm2/collectors/textfile-collector/low-resolution` | +| High | `/usr/local/percona/pmm/collectors/textfile-collector/high-resolution` | +| Medium | `/usr/local/percona/pmm/collectors/textfile-collector/medium-resolution` | +| Low | `/usr/local/percona/pmm/collectors/textfile-collector/low-resolution` | ![!image](../_images/node-exporter.textfile-collector.1.png) @@ -23,14 +23,14 @@ Metrics are stored on the PMM Server-side with additional labels related to this To statically set roles for a machine using labels: ```sh -echo 'node_role{role="my_monitored_server_1"} 1' > /usr/local/percona/pmm2/collectors/textfile-collector/low-resolution/node_role.prom +echo 'node_role{role="my_monitored_server_1"} 1' > /usr/local/percona/pmm/collectors/textfile-collector/low-resolution/node_role.prom ``` Here's an example of a `cron` job that automatically pushes logged-in users: ```sh $ cat /etc/cron.d/loggedin_users -*/1 * * * * root /usr/bin/who | /usr/bin/wc -l | sed -ne 's/^/node_loggedin_users /p' > /usr/local/percona/pmm2/collectors/textfile-collector/high-resolution/node_users.prom +*/1 * * * * root /usr/bin/who | /usr/bin/wc -l | sed -ne 's/^/node_loggedin_users /p' > /usr/local/percona/pmm/collectors/textfile-collector/high-resolution/node_users.prom ``` ![!image](../_images/node-exporter.textfile-collector.2.png) diff --git a/docs/how-to/integrate-platform.md b/docs/how-to/integrate-platform.md index 601ed582e2..088190a768 100644 --- a/docs/how-to/integrate-platform.md +++ b/docs/how-to/integrate-platform.md @@ -11,16 +11,8 @@ We recommend that you connect with a Percona Account, as this gives you access t #### Prerequisites To ensure that PMM can establish a connection to Percona Platform: -### Upgrade to PMM 2.27.0 or later - Before connecting your PMM Server to Percona Platform, make sure you are using PMM version 2.27 or newer. Otherwise, upgrade your PMM installation beforehand. - - This is required because, starting with PMM 2.27, Percona Platform has replaced username/password authentication with access token authentication. Access-token authentication increases security and enables federated identity. - - This change did not affect existing connections to PMM Platform, which were not automatically terminated. - - For more information, see [Install and set up PMM](../setting-up/index.md). - ### Check that you are a member of an existing Platform organization + 1. Log in to [Percona Platform](https://portal.percona.com) using your Percona Account. If you are connecting via GitHub, make sure you set your email address as **public** in your GitHub account. If your email address is private instead, Percona Platform cannot access it to authenticate you. 2. On the **Getting Started** page, check that the **Create organization** step shows an option to view your organization. @@ -59,20 +51,16 @@ To disconnect a PMM Server, go to > **Configuration In situations where you are not able to disconnect servers yourself, ask your PMM Admin to disconnect the server for you. For example, you may not be able to disconnect servers when PMM is moved to a network segment without outbound connections to public networks. - -!!! note alert alert-primary "Availability" - This feature is available starting with PMM 2.29.0. - If you cannot disconnect servers yourself, ask your PMM Admin to disconnect the server for you. For example, you may not be able to disconnect servers when PMM is moved to a network segment without outbound connections to public networks. If you are a PMM Admin, you can terminate any connections to Percona Platform, even if you are not logged into PMM with a Percona Account. However, we recommend logging in with a Percona Account before disconnecting servers, as this will automatically remove the disconnected servers from Percona Platform as well. -If you do disconnect servers without being connected with a Percona Account, you'll have to manually remove the unavailable servers from Percona Platform. This ensures that your list of connected PMM instances stays up-to-date in Percona Platform. +If you do disconnect servers without being connected with a Percona Account, you'll have to manually remove the unavailable servers from Percona Platform. This ensures that your list of connected PMM instances stays up-to-date in Percona Platform. To do this, go to [PMM instances](https://portal.percona.com/login), and remove any servers that you have already disconnected from PMM. - ## Sign into PMM with your Percona Account + Once you've successfully connected your PMM instance to the Percona Platform, you can also sign into PMM using your Percona Account: 1. Log out of your existing PMM session. diff --git a/docs/how-to/share-dashboard 2.md b/docs/how-to/share-dashboard 2.md index 1dd8344bb1..5c2b03060a 100644 --- a/docs/how-to/share-dashboard 2.md +++ b/docs/how-to/share-dashboard 2.md @@ -18,41 +18,32 @@ When you need to share a dashboard with your team members, you can either send t Rendering images requires the Image Renderer plug-in. If your PMM Admin has not installed this for your PMM instance, you will see the following error message under **Share Panel > Link**. ![!image](../_images/No_Image_Render_Plugin.png) -To install the dependencies: +To enable image rendering: -1. Connect to your PMM Server Docker container. +1. Deploy the Grafana Image Renderer container alongside PMM Server: - ```sh - docker exec -it pmm-server bash - ``` + ```sh + docker run -d --name renderer --network=pmm-network grafana/grafana-image-renderer:latest + ``` -2. Install Grafana plug-ins. +2. Stop your existing PMM Server container: - ```sh - grafana-cli plugins install grafana-image-renderer - ``` + ```sh + docker stop pmm-server + docker rm pmm-server + ``` -3. Restart Grafana. +3. Start a new PMM Server container with the required environment variables: - ```sh - supervisorctl restart grafana - ``` - -4. Install libraries. - - ```sh - yum install -y libXcomposite libXdamage libXtst cups libXScrnSaver pango \ - atk adwaita-cursor-theme adwaita-icon-theme at at-spi2-atk at-spi2-core \ - cairo-gobject colord-libs dconf desktop-file-utils ed emacs-filesystem \ - gdk-pixbuf2 glib-networking gnutls gsettings-desktop-schemas \ - gtk-update-icon-cache gtk3 hicolor-icon-theme jasper-libs json-glib \ - libappindicator-gtk3 libdbusmenu libdbusmenu-gtk3 libepoxy \ - liberation-fonts liberation-narrow-fonts liberation-sans-fonts \ - liberation-serif-fonts libgusb libindicator-gtk3 libmodman libproxy \ - libsoup libwayland-cursor libwayland-egl libxkbcommon m4 mailx nettle \ - patch psmisc redhat-lsb-core redhat-lsb-submod-security rest spax time \ - trousers xdg-utils xkeyboard-config alsa-lib - ``` + ```sh + docker run -d \ + --name pmm-server \ + --network=pmm-network \ + -p 8443:443 \ + -e GF_RENDERING_SERVER_URL=http://renderer:8081/render \ + -e GF_RENDERING_CALLBACK_URL=https://pmm-server:8443/graph/ \ + percona/pmm-server:latest + ``` ## Render Dashboard image diff --git a/docs/how-to/upgrade.md b/docs/how-to/upgrade.md deleted file mode 100644 index 1b767d270c..0000000000 --- a/docs/how-to/upgrade.md +++ /dev/null @@ -1,64 +0,0 @@ -# Upgrade - -## Plan the upgrade order - -### Upgrade PMM Server first - -Make sure to upgrade the PMM Server before you upgrade the PMM Client. - -Ensure that the PMM Server version is higher than or equal to the PMM Client version. Otherwise, there might be configuration issues, thus leading to failure in the client-server communication as PMM Server might not be able to identify all the parameters in the configuration. - -For example, for a PMM Server version 2.25.0, the PMM Client version should be 2.25.0 or 2.24.0. If the PMM Client version is 2.26.0, PMM might not work as expected. - -### Staged upgrade approach - -When upgrading PMM from older versions (2.30.0 and below), we recommend following a staged approach: first, upgrade to version 2.33.0, and then proceed to the latest version. - -This sequential upgrading process ensures that PMM's internal components are migrated and updated correctly. - -## Update the Server - -!!! caution alert alert-warning "Known issues for older versions" - - Upgrading to PMM 2.32.0 from older versions fails. We recommend upgrading directly to2.33 or latest version. For more information, see the [troubleshooting topic](../how-to/troubleshoot.md#pmm-server-fails-while-upgrading). - - - PMM versions prior to 2.33.0 may not show the latest versions available with instances created from the AWS marketplace in specific environments, including AWS. For solution, see the [troubleshooting](../how-to/troubleshoot.md#pmm-server-not-showing-latest-versions-available-with-the-instances-created-from-aws) section. - - -Client and server components are installed and updated separately. - -PMM Server can run natively, as a Docker image, a virtual appliance, or an AWS cloud instance. Each has its own installation and update steps. - -The preferred and simplest way to update PMM Server is with the *PMM Upgrade* panel on the Home page. - -![!image](../_images/PMM_Home_Dashboard_Panels_Upgrade.jpg) - -The panel shows: - -- the current server version and release date; -- whether the server is up to date; -- the last time a check was made for updates. - -Click the refresh button to manually check for updates. - -If one is available, click the update button to update to the version indicated. - -!!! seealso alert alert-info "See also" - [PMM Server Docker upgrade](../setting-up/server/docker.md#upgrade) - -## Updating a PMM-Agent - -PMM-Agent can be updated from tarball: - - 1. Download `tar.gz` with `pmm2-client`. - 2. Extract it. - 3. Run `./install_tarball` script with the `-u` flag. - -**Hint!** The configuration file will be overwritten if you do not provide the `-u` flag while the `pmm-agent` is updated. - -## Upgrade from PMM 1 - -Because of the significant architectural changes between PMM1 and PMM2, there is no direct upgrade path. The approach to making the switch from PMM version 1 to 2 is a gradual transition, outlined [in this blog post](https://www.percona.com/blog/2019/11/27/running-pmm1-and-pmm2-clients-on-the-same-host/). - -In short, it involves first standing up a new PMM2 server on a new host and connecting clients to it. As new data is reported to the PMM2 server, old metrics will age with the retention period (30 days, by default), at which point you'll be able to shut down your existing PMM1 server. - -Any alerts configured through the Grafana UI will have to be recreated due to the target dashboard id's not matching between PMM1 and PMM2. In this instance we recommend moving to Alertmanager recipes in PMM2 for alerting which, for the time being, requires a separate Alertmanager instance. We are working on integrating this natively into PMM2 Server and expect to support your existing Alertmanager rules. diff --git a/docs/index.md b/docs/index.md index 430d3bee0e..da08fb775d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,7 +1,6 @@ # About PMM - -:material-information: Info: This is the documentation for the latest release, **PMM {{release}}** ([Release Notes](release-notes/3.0.0_Alpha.md)). +:material-information: Info: This is the documentation for the latest release, **PMM {{release}}** ([Release Notes](release-notes/3.0.0_Alpha.md). Percona Monitoring and Management (PMM) is an open source database observability, monitoring, and management tool for use with MySQL, PostgreSQL, MongoDB, and the servers on which they run. It enables you to view node- to single-query performance metrics for all of your databases in a single place. diff --git a/docs/install-pmm/HA.md b/docs/install-pmm/HA.md index c730e6b3cb..2aaf256b6c 100644 --- a/docs/install-pmm/HA.md +++ b/docs/install-pmm/HA.md @@ -1,7 +1,7 @@ # Install PMM in HA mode !!! caution alert alert-warning "Important" - This feature has been added in PMM 2.41.0 and is currently in [Technical Preview](https://docs.percona.com/percona-monitoring-and-management/details/glossary.html#technical-preview). Early adopters are advised to use this feature for testing purposes only as it is subject to change. + This feature is currently in [Technical Preview](https://docs.percona.com/percona-monitoring-and-management/details/glossary.html#technical-preview). Early adopters are advised to use this feature for testing purposes only as it is subject to change. Set up PMM using Docker containers in a high-availability (HA) configuration following these instructions. diff --git a/docs/install-pmm/install-pmm-client/binary_package.md b/docs/install-pmm/install-pmm-client/binary_package.md index 949c396efe..b1585ebc14 100644 --- a/docs/install-pmm/install-pmm-client/binary_package.md +++ b/docs/install-pmm/install-pmm-client/binary_package.md @@ -1,84 +1,188 @@ -# Install PMM client manually using binaries +# Install PMM Client manually using binaries -To install PMM client with **binary** package, do the following: -{.power-number} +Choose your installation instructions based on whether you have root permissions: -1. Download the PMM Client package: +=== "With root permissions" + To install PMM Client with **binary** package with root permissions: + {.power-number} - ```sh - wget https://downloads.percona.com/downloads/pmm2/{{release}}/binary/tarball/pmm2-client-{{release}}.tar.gz - ``` + 1. Download the PMM Client package for your architecture: -2. Download the PMM Client package checksum file: + === "For ARM64 (aarch64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-aarch64.tar.gz + ``` - ```sh - wget https://downloads.percona.com/downloads/pmm2/{{release}}/binary/tarball/pmm2-client-{{release}}.tar.gz.sha256sum - ``` + === "For x86_64 (AMD64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-x86_64.tar.gz + ``` -3. Verify the download. + 2. Download the corresponding checksum file: - ```sh - sha256sum -c pmm2-client-{{release}}.tar.gz.sha256sum - ``` + === "For ARM64 (aarch64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-aarch64.tar.gz.sha256sum + ``` -4. Unpack the package and move into the directory. + === "For x86_64 (AMD64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-x86_64.tar.gz.sha256sum + ``` - ```sh - tar xfz pmm2-client-{{release}}.tar.gz && cd pmm2-client-{{release}} - ``` + 3. Verify the download: -5. Choose one of these two commands (depends on your permissions): + === "For ARM64 (aarch64)" + ```sh + sha256sum -c pmm-client-{{release}}-aarch64.tar.gz.sha256sum + ``` + + === "For x86_64 (AMD64)" + ```sh + sha256sum -c pmm-client-{{release}}-x86_64.tar.gz.sha256sum + ``` + + 4. Unpack the package and move into the directory: + + === "For ARM64 (aarch64)" + ```sh + tar xfz pmm-client-{{release}}-aarch64.tar.gz && cd pmm-client-{{release}} + ``` + + === "For x86_64 (AMD64)" + ```sh + tar xfz pmm-client-{{release}}-x86_64.tar.gz && cd pmm-client-{{release}} + ``` + + 5. Set the installation directory: - !!! caution alert alert-warning "Without root permissions" ```sh - export PMM_DIR=YOURPATH + export PMM_DIR=/usr/local/percona/pmm + ``` + + 6. Run the installer: + + ```sh + ./install_tarball ``` - where YOURPATH replace with you real path, where you have required access. - !!! caution alert alert-warning "With root permissions" + 7. Update your PATH: + ```sh - export PMM_DIR=/usr/local/percona/pmm2 + PATH=$PATH:$PMM_DIR/bin ``` -6. Run the installer. + 8. Set up the agent: - !!! hint "Root permissions (if you skipped step 5 for non root users)" ```sh - ./install_tarball + pmm-agent setup --config-file=/usr/local/percona/pmm/config/pmm-agent.yaml --server-address=192.168.1.123 --server-insecure-tls --server-username=admin --server-password=admin ``` -7. Change the path. + 9. Run the agent: + + ```sh + pmm-agent --config-file=${PMM_DIR}/config/pmm-agent.yaml + ``` + + 10. Open a new terminal and verify the installation: + + ```sh + pmm-admin status + ``` + +=== "Without root permissions" + + To install PMM Client with **binary** package without root permissions: + {.power-number} + + 1. Download the PMM Client package for your architecture: + + === "For ARM64 (aarch64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-aarch64.tar.gz + ``` + + === "For x86_64 (AMD64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-x86_64.tar.gz + ``` + + 2. Download the corresponding checksum file: + + === "For ARM64 (aarch64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-aarch64.tar.gz.sha256sum + ``` - ```sh - PATH=$PATH:$PMM_DIR/bin - ``` + === "For x86_64 (AMD64)" + ```sh + wget https://downloads.percona.com/downloads/pmm/{{release}}/binary/tarball/pmm-client-{{release}}-x86_64.tar.gz.sha256sum + ``` -8. Set up the agent (pick the command for you depending on permissions) + 3. Verify the download: - !!! hint "Root permissions" - ```sh - pmm-agent setup --config-file=/usr/local/percona/pmm2/config/pmm-agent.yaml --server-address=192.168.1.123 --server-insecure-tls --server-username=admin --server-password=admin - ``` + === "For ARM64 (aarch64)" + ```sh + sha256sum -c pmm-client-{{release}}-aarch64.tar.gz.sha256sum + ``` - !!! caution alert alert-warning "Non root users" - ```sh - pmm-agent setup --config-file=${PMM_DIR}/config/pmm-agent.yaml --server-address=192.168.1.123 --server-insecure-tls --server-username=admin --server-password=admin --paths-tempdir=${PMM_DIR}/tmp --paths-base=${PMM_DIR} - ``` + === "For x86_64 (AMD64)" + ```sh + sha256sum -c pmm-client-{{release}}-x86_64.tar.gz.sha256sum + ``` -9. Run the agent. + 4. Unpack the package and move into the directory: - ```sh - pmm-agent --config-file=${PMM_DIR}/config/pmm-agent.yaml - ``` + === "For ARM64 (aarch64)" + ```sh + tar xfz pmm-client-{{release}}-aarch64.tar.gz && cd pmm-client-{{release}} + ``` -10. Open a new terminal and check. + === "For x86_64 (AMD64)" + ```sh + tar xfz pmm-client-{{release}}-x86_64.tar.gz && cd pmm-client-{{release}} + ``` - ```sh - pmm-admin status - ``` - + 5. Set the installation directory: + + ```sh + export PMM_DIR=YOURPATH + ``` + + Replace YOURPATH with a path where you have required access. + + 6. Run the installer: + + ```sh + ./install_tarball + ``` + + 7. Update your PATH: + + ```sh + PATH=$PATH:$PMM_DIR/bin + ``` + + 8. Set up the agent: + + ```sh + pmm-agent setup --config-file=${PMM_DIR}/config/pmm-agent.yaml --server-address=192.168.1.123 --server-insecure-tls --server-username=admin --server-password=admin --paths-tempdir=${PMM_DIR}/tmp --paths-base=${PMM_DIR} + ``` + + 9. Run the agent: + + ```sh + pmm-agent --config-file=${PMM_DIR}/config/pmm-agent.yaml + ``` + + 10. Open a new terminal and verify the installation: + + ```sh + pmm-admin status + ``` + !!! hint alert alert-success "Tips" - - Download tar.gz with pmm2-client. + - Download tar.gz with pmm-client. - Extract it. - Run `./install_tarball script `with the `-u` flag. diff --git a/docs/install-pmm/install-pmm-client/connect-database/postgresql.md b/docs/install-pmm/install-pmm-client/connect-database/postgresql.md index 6e1bfca20c..402ff92644 100644 --- a/docs/install-pmm/install-pmm-client/connect-database/postgresql.md +++ b/docs/install-pmm/install-pmm-client/connect-database/postgresql.md @@ -261,7 +261,7 @@ If your PostgreSQL instance is configured to use TLS, click on the *Use TLS for ### Auto-discovery limit -PMM 2.41.0 introduces limit for **Auto-discovery** in PostgreSQL, a feature that dynamically discovers all databases in your PostgreSQL instance. +Limit for **Auto-discovery** in PostgreSQL is a feature that dynamically discovers all databases in your PostgreSQL instance. Limiting **Auto-discovery** reduces connections and prevents high CPU and RAM usage caused by multiple databases. @@ -350,7 +350,7 @@ where: #### Automatic discovery limit via CLI -Starting with PMM 2.41.0, there is a new flag in `pmm-admin` to limit Auto-discovery: +The `pmm-admin` flag limits Auto-discovery: `--auto-discovery-limit=XXX` @@ -400,7 +400,7 @@ To check the data: ### Running custom queries The PostgreSQL exporter can run custom queries to add new metrics not provided by default. -Those custom queries must be defined in the `/usr/local/percona/pmm2/collectors/custom-queries/postgresql` in the same host where the exporter is +Those custom queries must be defined in the `/usr/local/percona/pmm/collectors/custom-queries/postgresql` in the same host where the exporter is running. There are 3 directories inside it: - high-resolution/ - every 5 seconds - medium-resolution/ - every 10 seconds diff --git a/docs/install-pmm/install-pmm-client/connect-database/remote.md b/docs/install-pmm/install-pmm-client/connect-database/remote.md index a993747089..c680ff7b9f 100644 --- a/docs/install-pmm/install-pmm-client/connect-database/remote.md +++ b/docs/install-pmm/install-pmm-client/connect-database/remote.md @@ -6,6 +6,7 @@ When monitoring remote instances including RDS and Google instances, network lat For this reason, it is recommended to [lower the metrics resolution](../../../configure-pmm/metrics_res.md). The scrape timeout in PMM is dynamically set based on the resolution of data collection. The following rules determine the scrape timeout: +Scrape timeouts are managed based on resolution settings: {.power-number} - For resolutions <= 2 seconds, scrape timeout is 1 second. diff --git a/docs/install-pmm/install-pmm-client/package_manager.md b/docs/install-pmm/install-pmm-client/package_manager.md index f9764df290..c8e0cf40b5 100644 --- a/docs/install-pmm/install-pmm-client/package_manager.md +++ b/docs/install-pmm/install-pmm-client/package_manager.md @@ -7,7 +7,7 @@ On Debian or Red Hat Linux, install `percona-release` and use a Linux package ma ```sh percona-release disable all - percona-release percona-release enable pmm-client + percona-release percona-release enable pmm3-client ``` === "Debian-based" diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md b/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md index 4f85bc2c4a..4afd87a201 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/env_var.md @@ -1,36 +1,150 @@ -# Environment variables - -Use the following Docker container environment variables (with `-e var=value`) to set PMM Server parameters. - -| Variable         | Description -| --------------------------------------------------------------- | ----------------------------------------------------------------------- -| `DISABLE_UPDATES` | Disables a periodic check for new PMM versions as well as ability to apply upgrades using the UI -| `DISABLE_TELEMETRY` | Disable built-in telemetry and disable STT if telemetry is disabled. -| `METRICS_RESOLUTION` | High metrics resolution in seconds. -| `METRICS_RESOLUTION_HR` | High metrics resolution (same as above). -| `METRICS_RESOLUTION_MR` | Medium metrics resolution in seconds. -| `METRICS_RESOLUTION_LR` | Low metrics resolution in seconds. -| `DATA_RETENTION` | The number of days to keep time-series data.
**N.B.** This must be set in a format supported by `time.ParseDuration`
and represent the complete number of days.
The supported units are `ns`, `us` (or `µs`), `ms`, `s`, `m`, and `h`.
The value must be a multiple of 24, e.g., for 90 days 2160h (90 * 24). -| `ENABLE_VM_CACHE` | Enable cache in VM. -| `DISABLE_ALERTING` | Disables built-in Percona Alerting, which is enabled by default. -| `ENABLE_AZUREDISCOVER` | Enable support for discovery of Azure databases. -| `DISABLE_BACKUP_MANAGEMENT` | Disables Backup Management, which is enabled by default. -| `PMM_DEBUG` | Enables a more verbose log level. -| `PMM_TRACE` | Enables a more verbose log level including trace-back information. -| `PMM_PUBLIC_ADDRESS` | External IP address or the DNS name on which PMM server is running. -| `PMM_WATCHTOWER_HOST=${PMM_WATCHTOWER_HOST:-http://watchtower:8080}` | Specifies the connection URL for the WatchTower container, including the schema (http), host (watchtower), and port (8080). -| `PMM_WATCHTOWER_TOKEN=${PMM_WATCHTOWER_TOKEN:-123}` | Defines the authentication token used for secure communication between the PMM Server container and the WatchTower container. Make sure this matches the value of the `WATCHTOWER_HTTP_API_TOKEN` environment variable set in the WatchTower container. - -## Other variables - -The following variables are also supported but values passed are not verified by PMM. If any other variable is found, it will be considered invalid and the server won't start. - -| Variable | Description -| --------------------------------------------------------------- | ------------------------------------------------------ -| `_`, `HOME`, `HOSTNAME`, `LANG`, `PATH`, `PWD`, `SHLVL`, `TERM` | Default environment variables. -| `GF_*` | [Grafana](https://grafana.com/docs/grafana/latest/setup-grafana/configure-grafana/) environment variables. -| `VM_*` | [VictoriaMetrics'](https://docs.victoriametrics.com/Single-server-VictoriaMetrics.html#environment-variables) environment variables. -| `SUPERVISOR_` | `supervisord` environment variables. -| `KUBERNETES_` | Kubernetes environment variables. -| `MONITORING_` | Kubernetes monitoring environment variables. -| `PERCONA_TEST_` | Unknown variable but won't prevent the server starting. \ No newline at end of file +# Environment variables in PMM + +Configure PMM Server by setting Docker container environment variables using the `-e var=value` syntax: + +```bash +docker run -e PMM_DATA_RETENTION=720h -e PMM_DEBUG=true percona/pmm-server:3 +``` + +## Core configuration variables + +### Performance & storage + +| Variable | Default | Description | Example | +|----------|---------|-------------|----------| +| `PMM_DATA_RETENTION` | `30d` | Duration to retain metrics data. Must be in multiples of 24h. | `720h` (30 days) | +| `PMM_METRICS_RESOLUTION` | `1s` | Base metrics collection interval | `5s` | +| `PMM_METRICS_RESOLUTION_HR` | `5s` | High-resolution metrics interval | `10s` | +| `PMM_METRICS_RESOLUTION_MR` | `10s` | Medium-resolution metrics interval | `30s` | +| `PMM_METRICS_RESOLUTION_LR` | `60s` | Low-resolution metrics interval | `300s` | + +### Feature flags + +| Variable | Default | Effect when enabled | +|----------|---------|-------------------| +| `PMM_ENABLE_UPDATES` | `true` | Allows version checks and UI updates | +| `PMM_ENABLE_TELEMETRY` | `true` | Enables usage data collection | +| `PMM_ENABLE_ALERTING` | `true` | Enables Percona Alerting system | +| `PMM_ENABLE_BACKUP_MANAGEMENT` | `true` | Enables backup features | +| `PMM_ENABLE_AZURE_DISCOVER` | `false` | Enables Azure database discovery | + +### Debugging + +| Variable | Default | Purpose | +|----------|---------|---------| +| `PMM_DEBUG` | `false` | Enables verbose logging | +| `PMM_TRACE` | `false` | Enables detailed trace logging | + +## Advanced configuration + +### Networking + +| Variable | Description | +|----------|-------------| +| `PMM_PUBLIC_ADDRESS` | External DNS/IP for PMM server | +| `PMM_INTERFACE_TO_BIND` | Network interface binding | + +### Database connections + +| Variable | Purpose | +|----------|----------| +| `PMM_CLICKHOUSE_*` | ClickHouse connection settings | +| `PMM_POSTGRES_*` | PostgreSQL connection settings | + + +### Supported external variables + +- **Grafana**: All `GF_*` variables +- **VictoriaMetrics**: All `VM_*` variables +- **Kubernetes**: All `KUBERNETES_*` variables +- **System**: Standard variables like `HOME`, `PATH`, etc. + +## Variables for migrating from PMM v2 to PMM v3 + +When migrating from PMM v2 to PMM v3, you'll need to update your environment variables to match the new naming convention. This is because PMM v3 introduces several important changes to improve consistency and clarity: + +- environment variables now use `PMM_` prefix +- some boolean flags reversed (e.g., `DISABLE_` → `ENABLE_`) +- removed deprecated variables + +### Examples + +```bash +# PMM v2 +-e DISABLE_UPDATES=true -e DATA_RETENTION=720h + +# PMM v3 equivalent +-e PMM_ENABLE_UPDATES=false -e PMM_DATA_RETENTION=720h +``` + +### Migration reference table + +??? note "Click to expand migration reference table" + + #### Configuration variables + | PMM 2 | PMM 3 | Comments | + |---------------------------------|------------------------------------|------------------------------| + | `DATA_RETENTION` | `PMM_DATA_RETENTION` | | + | `DISABLE_ALERTING` | `PMM_ENABLE_ALERTING` | | + | `DISABLE_UPDATES` | `PMM_ENABLE_UPDATES` | | + | `DISABLE_TELEMETRY` | `PMM_ENABLE_TELEMETRY` | | + | `DISABLE_BACKUP_MANAGEMENT` | `PMM_ENABLE_BACKUP_MANAGEMENT` | Note the reverted boolean | + | `ENABLE_AZUREDISCOVER` | `PMM_ENABLE_AZURE_DISCOVER` | | + | `ENABLE_RBAC` | `PMM_ENABLE_ACCESS_CONTROL` | | + | `LESS_LOG_NOISE` | | Removed in PMM v3 | + + #### Metrics configuration + | PMM 2 | PMM 3 | + |---------------------------------|------------------------------------| + | `METRICS_RESOLUTION` | `PMM_METRICS_RESOLUTION` | + | `METRICS_RESOLUTION_HR` | `PMM_METRICS_RESOLUTION_HR` | + | `METRICS_RESOLUTION_LR` | `PMM_METRICS_RESOLUTION_LR` | + | `METRICS_RESOLUTION_MR` | `PMM_METRICS_RESOLUTION_MR` | + + + #### ClickHouse configuration + | PMM 2 | PMM 3 | Comments | + |-------------------------------------|------------------------------------|--------------------------| + | `PERCONA_TEST_PMM_CLICKHOUSE_ADDR` | `PMM_CLICKHOUSE_ADDR` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_DATABASE` | `PMM_CLICKHOUSE_DATABASE` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_DATASOURCE` | `PMM_CLICKHOUSE_DATASOURCE` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_HOST` | `PMM_CLICKHOUSE_HOST` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_PORT` | `PMM_CLICKHOUSE_PORT` | | + | `PERCONA_TEST_PMM_DISABLE_BUILTIN_CLICKHOUSE` | `PMM_DISABLE_BUILTIN_CLICKHOUSE` | | + | `PERCONA_TEST_PMM_CLICKHOUSE_BLOCK_SIZE` | | Removed in PMM v3, new version| + | `PERCONA_TEST_PMM_CLICKHOUSE_POOL_SIZE` | | Removed in PMM v3, new version| + + #### PostgreSQL configuration + | PMM 2 | PMM 3 | + |-------------------------------------|------------------------------------| + | `PERCONA_TEST_POSTGRES_ADDR` | `PMM_POSTGRES_ADDR` | + | `PERCONA_TEST_POSTGRES_DBNAME` | `PMM_POSTGRES_DBNAME` | + | `PERCONA_TEST_POSTGRES_USERNAME` | `PMM_POSTGRES_USERNAME` | + | `PERCONA_TEST_POSTGRES_DBPASSWORD` | `PMM_POSTGRES_DBPASSWORD` | + | `PERCONA_TEST_POSTGRES_SSL_CA_PATH` | `PMM_POSTGRES_SSL_CA_PATH` | + | `PERCONA_TEST_POSTGRES_SSL_CERT_PATH` | `PMM_POSTGRES_SSL_CERT_PATH` | + | `PERCONA_TEST_POSTGRES_SSL_KEY_PATH` | `PMM_POSTGRES_SSL_KEY_PATH` | + | `PERCONA_TEST_POSTGRES_SSL_MODE` | `PMM_POSTGRES_SSL_MODE` | + | `PERCONA_TEST_PMM_DISABLE_BUILTIN_POSTGRES` | `PMM_DISABLE_BUILTIN_POSTGRES` | + + #### Telemetry & development + | PMM 2 | PMM 3 | + |-------------------------------------|------------------------------------| + | `PMM_TEST_TELEMETRY_DISABLE_SEND` | `PMM_DEV_TELEMETRY_DISABLE_SEND` | + | `PERCONA_TEST_TELEMETRY_DISABLE_START_DELAY` | `PMM_DEV_TELEMETRY_DISABLE_START_DELAY` | + | `PMM_TEST_TELEMETRY_FILE` | `PMM_DEV_TELEMETRY_FILE` | + | `PERCONA_TEST_TELEMETRY_HOST` | `PMM_DEV_TELEMETRY_HOST` | + | `PERCONA_TEST_TELEMETRY_INTERVAL` | `PMM_DEV_TELEMETRY_INTERVAL` | + | `PERCONA_TEST_TELEMETRY_RETRY_BACKOFF` | `PMM_DEV_TELEMETRY_RETRY_BACKOFF` | + | `PERCONA_TEST_VERSION_SERVICE_URL` | `PMM_DEV_VERSION_SERVICE_URL` | + | `PERCONA_TEST_STARLARK_ALLOW_RECURSION` | `PMM_DEV_ADVISOR_STARLARK_ALLOW_RECURSION` | + + #### Removed variables + | PMM 2 | PMM 3 | Comments | + |-------------------------------------|------------------------------------|------------------------------| + | `PERCONA_TEST_AUTH_HOST` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS` | + | `PERCONA_TEST_CHECKS_HOST` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS` | + | `PERCONA_TEST_CHECKS_INTERVAL` | | Removed, not used | + | `PERCONA_TEST_CHECKS_PUBLIC_KEY` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_PUBLIC_KEY` | + | `PERCONA_TEST_NICER_API` | | Removed in PMM v3 | + | `PERCONA_TEST_SAAS_HOST` | | Removed, use `PMM_DEV_PERCONA_PLATFORM_ADDRESS` | \ No newline at end of file diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/index.md b/docs/install-pmm/install-pmm-server/baremetal/docker/index.md index b0241dfe8d..d73990beb9 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/index.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/index.md @@ -1,21 +1,24 @@ # Install PMM Server with Docker container - This section provides instructions for running PMM Server with Docker based on the [PMM Docker image](https://hub.docker.com/r/percona/pmm-server). ## Running PMM Server with Watchtower -To enable PMM Server upgrades via the **Upgrade Now** button on the PMM Home dashboard, you need to set up Watchtower alongside PMM Server during installation. Watchtower is a container monitoring tool that updates Docker containers to the latest version when triggered. +To enable PMM Server upgrades via the **Upgrade page** and the **Upgrade Now** button on the Home dashboard, you must configure Watchtower during the PMM Server installation. Watchtower is a container monitoring tool that helps update Docker containers to their latest version when triggered. + +The [Easy-install script](../easy-install.md) script includes Watchtower commands, allowing for a one-step setup of PMM alongside Watchtower. + +You can also install PMM 3 manually, following the instructions below. -The PMM 3 Beta release will integrate Watchtower commands into the [Easy-install script](../easy-install.md), allowing for a one-step setup of PMM alongside Watchtower. Until then, you can manually test the PMM installation by following the instructions using the instructions provided below. +## Installing PMM Server manually -Before proceeding, review the installation prerequisites and choose a method to run PMM Server with Docker based on your preferred data storage option: +Before starting the installation, review the installation prerequisites below and choose a method to run PMM Server with Docker based on your preferred data storage option: - [Running Docker with Data container](../docker/run_with_data_container.md) - [Running Docker with host directory](../docker/run_with_host_dir.md) - [Running Docker with volume](../docker/run_with_vol.md) -**Prerequisites** +### Manual installation prerequisites - Install [Docker](https://docs.docker.com/get-docker/) version 17.03 or higher. - Ensure your CPU (and any virtualization layer you may be using) supports `x86-64-v2`. diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/isolated_hosts.md b/docs/install-pmm/install-pmm-server/baremetal/docker/isolated_hosts.md index 5de45e94bb..4d81fe4fc9 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/isolated_hosts.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/isolated_hosts.md @@ -7,8 +7,8 @@ If the host where you will run PMM Server has no internet connection, you can do 1. On an internet-connected host, download the Docker image and its checksum file. ```sh - wget https://downloads.percona.com/downloads/pmm2/{{release}}/docker/pmm-server-{{release}}.docker - wget https://downloads.percona.com/downloads/pmm2/{{release}}/docker/pmm-server-{{release}}.sha256sum + wget https://downloads.percona.com/downloads/pmm/{{release}}/docker/pmm-server-{{release}}.docker + wget https://downloads.percona.com/downloads/pmm/{{release}}/docker/pmm-server-{{release}}.sha256sum ``` 2. Copy both files to where you will run PMM Server. diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md b/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md index de80cec896..29b1c3ddc7 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_data_container.md @@ -41,10 +41,10 @@ To run Docker with data container: perconalab/pmm-server:3.0.0-rc ``` -4. Change the password for the default `admin` user: +4. Change the password for the default `admin` user, replacing `your_secure_password123` with a strong, unique password: ```sh - docker exec -t pmm-server change-admin-password + docker exec -t pmm-server change-admin-password your_secure_password123 ``` 5. Check the [WatchTower prerequisites](../docker/index.md|#prerequisites) and pass the following command to Docker Socket to start [Watchtower](https://containrrr.dev/watchtower/): @@ -53,4 +53,4 @@ To run Docker with data container: docker run -v /var/run/docker.sock:/var/run/docker.sock -e WATCHTOWER_HTTP_API_UPDATE=1 -e WATCHTOWER_HTTP_API_TOKEN=your_watchtower_token --hostname=your_watchtower_host --network=pmm_default docker.io/perconalab/watchtower ``` -6. Visit `https://localhost:443` to see the PMM user interface in a web browser. (If you are accessing the docker host remotely, replace `localhost` with the IP or server name of the host.) +6. Visit `https://localhost:443` to see the PMM user interface in a web browser. If you are accessing the docker host remotely, replace `localhost` with the IP or server name of the host. diff --git a/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_vol.md b/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_vol.md index 9271968cdb..1c316cd447 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_vol.md +++ b/docs/install-pmm/install-pmm-server/baremetal/docker/run_with_vol.md @@ -18,7 +18,7 @@ To run Docker with volume: 3. Run the image: - ```sh + ```sh docker run --detach --restart always \ --publish 443:8443 \ --env PMM_WATCHTOWER_HOST=your_watchtower_host \ @@ -28,11 +28,11 @@ To run Docker with volume: --name pmm-server \ perconalab/pmm-server:3.0.0-rc ``` - -4. Change the password for the default `admin` user: + +4. Change the password for the default `admin` user, replacing `your_secure_password123` with a strong, unique password: ```sh - docker exec -t pmm-server change-admin-password + docker exec -t pmm-server change-admin-password your_secure_password123 ``` 5. Check the [WatchTower prerequisites](../docker/index.md|#prerequisites) and pass the following command to Docker Socket to start [Watchtower](https://containrrr.dev/watchtower/): @@ -41,4 +41,4 @@ To run Docker with volume: docker run -v /var/run/docker.sock:/var/run/docker.sock -e WATCHTOWER_HTTP_API_UPDATE=1 -e WATCHTOWER_HTTP_API_TOKEN=your_watchtower_token --hostname=your_watchtower_host --network=pmm_default docker.io/perconalab/watchtower ``` -6. Visit `https://localhost:443` to see the PMM user interface in a web browser. (If you are accessing the docker host remotely, replace `localhost` with the IP or server name of the host.) \ No newline at end of file +6. Visit `https://localhost:443` to see the PMM user interface in a web browser. If you are accessing the Docker host remotely, replace `localhost` with the IP or server name of the host. \ No newline at end of file diff --git a/docs/install-pmm/install-pmm-server/baremetal/helm/index.md b/docs/install-pmm/install-pmm-server/baremetal/helm/index.md index 55f8418713..0c936e711a 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/helm/index.md +++ b/docs/install-pmm/install-pmm-server/baremetal/helm/index.md @@ -33,9 +33,6 @@ Also, ensure that the Kubernetes cluster has [high availability](https://kuberne ## Install PMM Server -!!! note alert alert-primary "Availability" - This feature is available starting with PMM 2.29.0. - ??? info "Summary" !!! summary alert alert-info "" diff --git a/docs/install-pmm/install-pmm-server/baremetal/podman/index.md b/docs/install-pmm/install-pmm-server/baremetal/podman/index.md index a200a17373..4e149b8bad 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/podman/index.md +++ b/docs/install-pmm/install-pmm-server/baremetal/podman/index.md @@ -2,11 +2,10 @@ This section provides instructions for running PMM Server with Podman based on our [Docker image](https://hub.docker.com/r/percona/pmm-server). -!!! note alert alert-primary "" - The tags used here are for the current release (PMM 2.33.0). Other [tags](https://hub.docker.com/r/percona/pmm-server/tags) are available. !!! seealso alert alert-info "See also" - [Docker](../docker/index.md) + - [Docker](../docker/index.md) + - Other [tags](https://hub.docker.com/r/percona/pmm-server/tags) are available. Podman is an open-source project available on most Linux platforms and resides on [GitHub](https://github.com/containers/podman). Podman is a daemonless container engine for developing, managing, and running Open Container Initiative (OCI) containers and container images on your Linux System. @@ -29,9 +28,6 @@ Percona recommends running PMM as a non-privileged user and running it as part o ## Run as non-privileged user to start PMM -!!! note alert alert-primary "Availability" - This feature is available starting with PMM 2.29.0. - ??? info "Summary" !!! summary alert alert-info "" diff --git a/docs/install-pmm/install-pmm-server/baremetal/virtual/download_ova.md b/docs/install-pmm/install-pmm-server/baremetal/virtual/download_ova.md index 97e57a8f3b..8069b70a2d 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/virtual/download_ova.md +++ b/docs/install-pmm/install-pmm-server/baremetal/virtual/download_ova.md @@ -20,8 +20,8 @@ This section contains guidelines on how to download and verify the OVA file. Download the latest PMM Server OVA and checksum files. ```sh - wget https://www.percona.com/downloads/pmm2/{{release}}/ova/pmm-server-{{release}}.ova - wget https://www.percona.com/downloads/pmm2/{{release}}/ova/pmm-server-{{release}}.sha256sum + wget https://www.percona.com/downloads/pmm/{{release}}/ova/pmm-server-{{release}}.ova + wget https://www.percona.com/downloads/pmm/{{release}}/ova/pmm-server-{{release}}.sha256sum ``` ## Verify OVA file from CLI diff --git a/docs/install-pmm/install-pmm-server/baremetal/virtual/index.md b/docs/install-pmm/install-pmm-server/baremetal/virtual/index.md index 48870a35ca..119c0c35c5 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/virtual/index.md +++ b/docs/install-pmm/install-pmm-server/baremetal/virtual/index.md @@ -28,9 +28,9 @@ Most steps can be done with either a user interface or on the command line, but | Item | Value |---------------|----------------------------------------------------------- -| Download page | +| Download page | | File name | `pmm-server-{{release}}.ova` -| VM name | `PMM2-Server-{{release_date}}-N` (`N`=build number) +| VM name | `pmm-Server-{{release_date}}-N` (`N`=build number) ## VM specifications diff --git a/docs/install-pmm/install-pmm-server/baremetal/virtual/login_UI.md b/docs/install-pmm/install-pmm-server/baremetal/virtual/login_UI.md index aeac583e81..cb28a27d4e 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/virtual/login_UI.md +++ b/docs/install-pmm/install-pmm-server/baremetal/virtual/login_UI.md @@ -47,7 +47,7 @@ To log in to the PMM user interface: 2. Log into the PMM user interface. - 3. Select **PMM → PMM Settings → SSH Key**. + 3. Select **PMM Configuration > Settings > SSH Key**. 4. Copy and paste the contents of the `admin.pub` file into the **SSH Key** field. diff --git a/docs/install-pmm/install-pmm-server/baremetal/virtual/vmware.md b/docs/install-pmm/install-pmm-server/baremetal/virtual/vmware.md index e44dd93903..0c4796576a 100644 --- a/docs/install-pmm/install-pmm-server/baremetal/virtual/vmware.md +++ b/docs/install-pmm/install-pmm-server/baremetal/virtual/vmware.md @@ -30,7 +30,7 @@ ```sh ovftool --name="PMM Server" --net:NAT=Wi-Fi \ - https://www.percona.com/downloads/pmm2/{{release}}/ova/pmm-server-{{release}}.ova \ + https://www.percona.com/downloads/pmm/{{release}}/ova/pmm-server-{{release}}.ova \ pmm-server-{{release}}.vmx ``` @@ -92,7 +92,7 @@ To start the guest and get the IP address from the CLI: pmm-server.vmx nogui ``` -[OVA]: https://www.percona.com/downloads/pmm2/{{release}}/ova +[OVA]: https://www.percona.com/downloads/pmm/{{release}}/ova [OVF]: https://wikipedia.org/wiki/Open_Virtualization_Format [VirtualBox]: https://www.virtualbox.org/ [VMware]: https://www.vmware.com/products/workstation-player/ diff --git a/docs/pmm-admin/security/data_encryption.md b/docs/pmm-admin/security/data_encryption.md new file mode 100644 index 0000000000..3b27ef8dcd --- /dev/null +++ b/docs/pmm-admin/security/data_encryption.md @@ -0,0 +1,54 @@ +# PMM data encryption + +Percona Monitoring and Management (PMM) implements robust encryption for sensitive data stored in its internal database's `agent` table. This includes access credentials and configuration details. + +## Default encryption + +PMM automatically manages encryption using a key file located at `/srv/pmm-encryption.key`. PMM generates this file upon the initial launch of PMM 3 or when upgrading from the latest version of PMM 2. + +## Custom encryption key configuration + +For enhanced security control, PMM supports custom encryption keys. + +To set up a custom keys, configure the `PMM_ENCRYPTION_KEY_PATH` environment variable to point to your custom key file. + +!!! hint alert alert-success "Important" + Make sure to set this configuration **before** any data encryption occurs—specifically, either before upgrading to PMM 3 or before the initial startup of a new PMM 3.x container. + +### Key management requirements + +Once configured, PMM will use custom keys to encrypt and decrypt all sensitive data stored within the system. + +If the custom key is unavailable or misplaced, PMM will be unable to access and decrypt the stored data, which will prevent it from running correctly. + +Make sure to store and manage the custom encryption key securely to avoid potential loss of data access. + +## Rotating the encryption key + +You may want to change or update the encryption key when the original key is compromised or as part of routine security maintenance. For this, you can use the **PMM Encryption Rotation Tool**. + +This tool re-encrypts all existing sensitive data with a newly generated encryption key, ensuring continuous security with minimal disruption. + +To rotate or regenerate the encryption key: +{.power-number} + +1. Log in to the container that runs PMM Server. + +2. Run the Encryption Rotation Tool using the following the command: + + ```bash + pmm-encryption-rotation + ``` + + - Ensure `PMM_ENCRYPTION_KEY_PATH` is set to the current custom key if using one, so the tool can decrypt data before re-encryption. + - If using custom credentials/SSL for the PMM internal database, provide them with the appropriate flags. + +3. Verify PMM functionality all components are functioning properly to ensure that the encryption key rotation was successful. + +Once the rotation tool has completed, a new encryption key will be generated and saved either in the default location (`/srv/pmm-encryption.key`) or in the path specified by `PMM_ENCRYPTION_KEY_PATH`. The tool will automatically re-encrypt all sensitive data with the new key. + +## Best pracices for custom key management + +- Always keep a secure backup of your encryption key, especially when using `PMM_ENCRYPTION_KEY_PATH`, as it is critical to PMM’s data decryption process. +- In containerized environments, ensure `PMM_ENCRYPTION_KEY_PATH` is persistently set in the container configuration to avoid issues during restarts. +- Test the encryption key rotation process in a staging environment before applying it in production to minimize potential downtime or configuration issues. diff --git a/docs/pmm-upgrade/index.md b/docs/pmm-upgrade/index.md index 208bb4a398..5fb2185f8c 100644 --- a/docs/pmm-upgrade/index.md +++ b/docs/pmm-upgrade/index.md @@ -1,17 +1,15 @@ # About PMM Server upgrade -!!! caution alert alert-warning "Important" - Upgrade the PMM Server before you upgrade the PMM Client. - Ensure that the PMM Server version is higher than or equal to the PMM Client version. Otherwise, there might be configuration issues, thus leading to failure in the client-server communication as PMM Server might not be able to identify all the parameters in the configuration. - - For example, for a PMM Server version 2.25.0, the PMM Client version should be 2.25.0 or 2.24.0. If the PMM Client version is 2.26.0, PMM might not work as expected. +!!! caution alert alert-warning "Upgrade PMM Server before Clients" + - When upgrading PMM, always upgrade the PMM Server before upgrading any PMM Clients. + - Make sure that the PMM Server version is higher than or equal to the PMM Client version. Mismatched versions can lead to configuration issues and failures in Client-Server communication, as the PMM Server may not recognize all parameters in the client configuration. Find the detailed information on how to upgrade PMM in the following sections: -* [Upgrade PMM Server using the UI](ui_upgrade.md) +* [Upgrade PMM Server from the UI](ui_upgrade.md) -* [Upgrade PMM agent](upgrade_agent.md) +* [Upgrade PMM Client](upgrade_agent.md) * [Upgrade PMM Server using Docker](upgrade_docker.md) -* [Upgrade from PMM 1](upgrade_from_pmm_1.md) \ No newline at end of file +* [Migrate from PMM 2](migrating_from_pmm_2.md) diff --git a/docs/pmm-upgrade/migrating_from_pmm_2.md b/docs/pmm-upgrade/migrating_from_pmm_2.md new file mode 100644 index 0000000000..ee1b174a97 --- /dev/null +++ b/docs/pmm-upgrade/migrating_from_pmm_2.md @@ -0,0 +1,66 @@ +# Migrate from PMM 2 to PMM 3 + +PMM 3 introduces significant architectural changes that require gradual transition from PMM 2: + +## Step 1: Upgrade PMM 2 Server to the latest version + +Before upgrading to PMM 3, ensure your PMM 2 Server is running the latest version: +{.power-number} + +1. From the **Home** page, scroll to the **PMM Upgrade** panel and click the Refresh button to manually check for updates. +2. If an update is available, click the **Update** button to install the latest PMM 2 version. +3. Verify the update was successful by checking the version number after the update completes. + +## Step 2: Migrate PMM 2 Server to PMM 3 + +Follow these manual steps to upgrade your PMM 2 Server to PMM 3: +{.power-number} + +1. Pull the new PMM 3 Server Docker image: + + ```sh + docker pull percona/pmm-server:3 + ``` + +2. Stop all services of the PMM 2 Server container: + + ```sh + docker exec -t pmm-server supervisorctl stop all + ``` + +3. Transfer ownership of all directories and files in the `/srv` directory to the pmm user: + + ```sh + docker exec -t pmm-server chown -R pmm:pmm /srv + ``` + +4. Stop and remove the PMM 2 Server container: + + ```sh + docker stop pmm-server && docker rm pmm-server + ``` + +5. Run a new container based on the PMM 3 image, ensuring you pass the same pmm-data volume: + + ```sh + docker run -d -p 80:8080 -p 443:8443 -v pmm-data:/srv --name pmm-server --restart always percona/pmm-server:3 + ``` + +6. Verify that the new PMM 3 Server container is running and accessible through the UI. + +## Step 3: Migrate PMM 2 Clients to PMM 3 + +!!! caution alert alert-warning "Important" + Support of PMM 2 Clients by PMM 3 Server is limited to metrics and Query Analytics (QAN) only. This limited support will be dropped in PMM 3.3. + +Depending on your initial installation method, update PMM Clients using your operating system's package manager or by updating from a tarball. +For detailed instructions, see the [Upgrade PMM Client topic](../pmm-upgrade/upgrade_client.md). + +### Post-migration steps + +After you finish migrating: +{.power-number} + +1. Verify that all clients are up to date by checking **PMM Configuration > Updates**. +2. Confirm all previously monitored services are reporting correctly to the new PMM 3 Server by reviewing **Configuration > PMM Inventory > Services**. +3. Check the dashboards to make sure you're receiving the metrics information and QAN data. diff --git a/docs/pmm-upgrade/ui_upgrade.md b/docs/pmm-upgrade/ui_upgrade.md index e048bd6b06..99ece0875b 100644 --- a/docs/pmm-upgrade/ui_upgrade.md +++ b/docs/pmm-upgrade/ui_upgrade.md @@ -1,26 +1,22 @@ -# Upgrade PMM Server using the UI +# Upgrade PMM v3 Server from the UI -!!! caution alert alert-warning "Caution" - - While upgrading PMM to version 2.32.0, it fails. This issue has been resolved for PMM version 2.33.0. However, the issue persists on all the versions prior to 2.33.0. For solution, see the [troubleshooting](../troubleshoot/upgrade_issues.md) section. - - PMM versions prior to 2.33.0 may not show the latest versions available with instances created from the AWS marketplace in specific environments, including AWS. For solution, see the [troubleshooting](../troubleshoot/upgrade_issues.md#pmm-server-not-showing-latest-versions-available-with-the-instances-created-from-aws) section. +PMM Server and Client components are installed and updated separately. -Client and server components are installed and updated separately. +PMM v3 Server can run natively, as a Docker image, a virtual appliance, or an AWS cloud instance. While each environment has its own specific installation and update steps, the UI-based upgrade method is universal and recommended for most users. -PMM Server can run natively, as a Docker image, a virtual appliance, or an AWS cloud instance. Each has its own installation and update steps. +## Upgrade process -The preferred and simplest way to update PMM Server is with the *PMM Upgrade* panel on the Home page. +The preferred and simplest way to update PMM v3 Server is via the **Updates** page: +{.power-number} -![!image](../_images/PMM_Home_Dashboard_Panels_Upgrade.jpg) +1. Go to **PMM Configuration > Updates** in your PMM web interface. Here you can check the current PMM Server version, the timestamp of the last update check and whether your instance is up-to-date. -The panel shows: +2. If an update is available, click the **Update now** button to install the latest version. -- the current server version and release date; -- whether the server is up to date; -- the last time a check was made for updates. +![Update page](../Update_page.png) -Click the refresh button to manually check for updates. +## Quick upgrade check -If one is available, click the update button to update to the version indicated. +For a quick overview of your PMM v3 Server's update status, you can also check to the **Upgrade** panel on the **Home** page. -!!! seealso alert alert-info "See also" - [PMM Server Docker upgrade](upgrade_docker.md) and [Upgrade PMM agent](upgrade_agent.md) \ No newline at end of file +![PMM Home Dashboard Upgrade Panel](../_images/PMM_Home_Dashboard_Panels_Upgrade.jpg) diff --git a/docs/pmm-upgrade/upgrade_agent.md b/docs/pmm-upgrade/upgrade_agent.md deleted file mode 100644 index ebd74f1df3..0000000000 --- a/docs/pmm-upgrade/upgrade_agent.md +++ /dev/null @@ -1,11 +0,0 @@ -# Upgrade PMM agent - -PMM-Agent can be updated from tarball: -{.power-number} - - 1. Download `tar.gz` with `pmm2-client`. - 2. Extract it. - 3. Run `./install_tarball` script with the `-u` flag. - -!!! caution alert alert-warning "Important" - The configuration file will be overwritten if you do not provide the `-u` flag while the `pmm-agent` is updated. diff --git a/docs/pmm-upgrade/upgrade_aws.md b/docs/pmm-upgrade/upgrade_aws.md index d5bf047d75..70b9250515 100644 --- a/docs/pmm-upgrade/upgrade_aws.md +++ b/docs/pmm-upgrade/upgrade_aws.md @@ -1,6 +1,6 @@ # Upgrade PMM Server on AWS -## Change Public IP address +## Change public IP address To assign a public IP address for an Amazon EC2 instance, follow these steps: {.power-number} diff --git a/docs/pmm-upgrade/upgrade_client.md b/docs/pmm-upgrade/upgrade_client.md new file mode 100644 index 0000000000..05ff2d8b23 --- /dev/null +++ b/docs/pmm-upgrade/upgrade_client.md @@ -0,0 +1,47 @@ +# Upgrade PMM Client + +There are two primary methods to update PMM Clients, depending on your initial installation method: +{.power-number} + +1. Using your operating system's package manager +2. Updating from a tarball + +### 1. Package Manager method + +The package manager method is generally more convenient and efficient. Percona provides the [percona-release](https://docs.percona.com/percona-software-repositories/installing.html) package, which helps you install Percona software, including PMM Client. PMM Client is available from the `pmm-client` repository. + +To deploy a new version of the Client via package manager, simply replace the currently installed package with the latest version of the PMM Client or with a specific version. + +#### Install the latest PMM Client version + +Run the commands below to install the latest PMM Client version via package manager and keep your existing Client configuration during the update process. + +For example, to install the latest version of the PMM Client on Red Hat or its derivatives: + + ```sh + percona-release enable pmm-client + yum update pmm-client + ``` + +#### Deploy a specific version + +To deploy a specific version of the PMM Client via package manager, check the available versions and then provide the full name of the package. For example: + + ```sh + yum --showduplicates search pmm-client + pmm-client-3.0.0-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent) + pmm-client-3.0.1-6.el9.x86_64 : Percona Monitoring and Management Client (pmm-agent) + yum update pmm-client-3.0.1-6.el9.x86_64 + ``` + +### 2. Tarball method + +If you initially installed the PMM Client from a tarball, you can update it by replacing the currently installed package with the latest version: +{.power-number} + + 1. Download `tar.gz` with `pmm-client`. + 2. Extract the tarball. + 3. Run `./install_tarball` script with the `-u` flag. + +!!! caution alert alert-warning "Important" + The configuration file will be overwritten if you do not provide the `-u` flag while the `pmm-agent` is updated. diff --git a/docs/pmm-upgrade/upgrade_docker.md b/docs/pmm-upgrade/upgrade_docker.md index 7a52ac3ac1..009d55ea72 100644 --- a/docs/pmm-upgrade/upgrade_docker.md +++ b/docs/pmm-upgrade/upgrade_docker.md @@ -1,62 +1,53 @@ # Upgrade PMM Server using Docker -??? info "Summary" +## Before you begin - !!! summary alert alert-info "" - - Stop the running container. - - Backup (rename) the container and copy data. - - Pull the latest Docker image. - - Run it. - - --- +Before starting the upgrade, complete these preparation steps to ensure you can recover your system if needed and confirm compatibility with the new version: +{.power-number} -!!! caution alert alert-warning "Important" - Downgrades are not possible. To go back to using a previous version you must have created a backup of it before upgrading. +1. Create a backup before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires an backup made prior to the upgrade. -!!! hint alert alert-success "Tip" - To see what release you are running, use the *PMM Upgrade* panel on the *Home Dashboard*, or run: +2. Verify your current PMM version: Check your current PMM version by navigating to **PMM Configuration > Updates** or by running the following command: ```sh - docker exec -it pmm-server \ - curl -ku admin:admin https://localhost/v1/version + docker exec -it pmm-server curl -ku admin:admin https://localhost:8443/v1/version ``` - (If you are accessing the docker host remotely, replace `localhost` with the IP or server name of the host.) +## Upgrade steps -To upgrade PMM Server using Docker: +Follow these steps to upgrade your PMM Server while preserving your monitoring data and settings. In case of any issues, you can restore your system using the backup created in the preparation steps. {.power-number} - -1. Stop the container. +1. Stop the current container: ```sh - docker stop pmm-server + docker stop pmm-server ``` -2. Perform a [backup](#backup). +2. [Back up your data](../install-pmm/install-pmm-server/baremetal/docker/backup_container.md). - -3. Pull the latest image. +3. Pull the latest image: ```sh - docker pull percona/pmm-server:2 + docker pull percona/pmm-server:3 ``` -4. Rename the original container +4. Rename the original container: ```sh - docker rename pmm-server pmm-server-old + docker rename pmm-server pmm-server-old ``` - -5. Run it. +5. Run the new container: ```sh - docker run \ - --detach \ - --restart always \ - --publish 443:443 \ - --volumes-from pmm-data \ - --name pmm-server \ - percona/pmm-server:2 - ``` + docker run \ + --detach \ + --restart always \ + --publish 443:8443 \ + --volumes-from pmm-data \ + --name pmm-server \ + percona/pmm-server:3 + ``` + +6. After upgrading, verify that PMM Server is running correctly and all your data is accessible. diff --git a/docs/pmm-upgrade/upgrade_from_pmm_1.md b/docs/pmm-upgrade/upgrade_from_pmm_1.md deleted file mode 100644 index c504d07acf..0000000000 --- a/docs/pmm-upgrade/upgrade_from_pmm_1.md +++ /dev/null @@ -1,7 +0,0 @@ -# Upgrade from PMM 1 - -Because of the significant architectural changes between PMM1 and PMM2, there is no direct upgrade path. The approach to making the switch from PMM version 1 to 2 is a gradual transition, outlined in [this blog post](https://www.percona.com/blog/running-pmm1-and-pmm2-clients-on-the-same-host/). - -In short, it involves first standing up a new PMM2 server on a new host and connecting clients to it. As new data is reported to the PMM2 server, old metrics will age with the retention period (30 days, by default), at which point you’ll be able to shut down your existing PMM1 server. - -Any alerts configured through the Grafana UI will have to be recreated due to the target dashboard id’s not matching between PMM1 and PMM2. In this instance we recommend moving to Alertmanager recipes in PMM2 for alerting which, for the time being, requires a separate Alertmanager instance. We are working on integrating this natively into PMM2 Server and expect to support your existing Alertmanager rules. \ No newline at end of file diff --git a/docs/pmm-upgrade/upgrade_helm.md b/docs/pmm-upgrade/upgrade_helm.md index e9d579a28f..67d65b1006 100644 --- a/docs/pmm-upgrade/upgrade_helm.md +++ b/docs/pmm-upgrade/upgrade_helm.md @@ -1,21 +1,57 @@ # Upgrade PMM Server using Helm -Percona will release a new chart updating its containers if a new version of the main container is available, there are any significant changes, or critical vulnerabilities exist. +Percona releases new chart versions to update containers when: -By default UI update feature is disabled and should not be enabled. Do not modify that parameter or add it while modifying the custom `values.yaml` file: +- A new version of the main container is available +- Significant changes are made +- Critical vulnerabilities are addressed -```yaml -pmmEnv: - DISABLE_UPDATES: "1" -``` +!!! caution alert alert-warning "UI Update feature disabled by default" + The UI update feature is disabled by default and should remain so. Do not modify or add the following parameter in your custom `values.yaml` file: + ```yaml + pmmEnv: + DISABLE_UPDATES: "1" + ``` -Before updating the helm chart, it is recommended to pre-pull the image on the node where PMM is running, as the PMM images could be large and could take time to download. +## Before you begin -Update PMM as follows: +Before starting the upgrade, complete these preparation steps to ensure you can recover your system if needed and confirm compatibility with the new version: +{.power-number} -```sh -helm repo update percona -helm upgrade pmm -f values.yaml percona/pmm -``` +1. Create a backup before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires a backup made prior to the upgrade. -This will check updates in the repo and upgrade deployment if the updates are available. \ No newline at end of file +2. To reduce downtime, pre-pull the new image on the node where PMM is running: + + ```sh + # Replace with the latest PMM version + docker pull percona/pmm-server: + ``` + +## Upgrade steps + +Follow these steps to upgrade your PMM Server while preserving your monitoring data and settings—you can restore from your backup if needed. +{.power-number} + +1. Update Helm repository: + + ```sh + helm repo update percona + ``` + +2. Upgrade PMM: + + ```sh + helm upgrade pmm -f values.yaml percona/pmm + ``` + +3. After the upgrade, verify that PMM Server is running correctly: + + ```sh + kubectl get pods | grep pmm-server + ``` + +4. Check the logs for any errors: + + ```sh + kubectl logs deployment/pmm-server + ``` diff --git a/docs/pmm-upgrade/upgrade_podman.md b/docs/pmm-upgrade/upgrade_podman.md index cfbc9d1145..941b0bb62a 100644 --- a/docs/pmm-upgrade/upgrade_podman.md +++ b/docs/pmm-upgrade/upgrade_podman.md @@ -1,63 +1,52 @@ -# Upgrade PMM Server using podman +# Upgrade PMM Server using Podman -??? info "Summary" +## Before you begin - !!! summary alert alert-info "" - - Perform a backup. - - Update PMM tag. - - Pre-pull image. - - Run it. - - --- +Before starting the upgrade, complete these preparation steps to ensure you can recover your system if needed and confirm compatibility with the new version: +{.power-number} -!!! caution alert alert-warning "Important" - You cannot downgrade. To go to a previous version, you must create a backup before upgrading. +1. Create a backup before upgrading, as downgrades are not possible. Therefore, reverting to a previous version requires an backup made prior to the upgrade. -!!! hint alert alert-success "Tip" - To see the current release running on your system, use the *PMM Upgrade* panel on the *Home Dashboard*, or run: +2. Verify your current PMM version: Check your current PMM version by navigating to **PMM Configuration > Updates** or by running the following command. ```sh podman exec -it pmm-server \ curl -ku admin:admin https://localhost/v1/version ``` -(If you are accessing the podman host remotely, replace `localhost` with the IP or server name of the host.) -{.power-number} +## Upgrade steps -1. Perform a [backup](../install-pmm/install-pmm-server/baremetal/podman/backup_container_podman.md). +Follow these steps to upgrade your PMM Server while preserving your monitoring data and settings—you can restore from your backup if needed. +{.power-number} +1. [Back up your data](../install-pmm/install-pmm-server/baremetal/podman/backup_container_podman.md). -2. Update PMM tag. +2. Update PMM tag by editing `~/.config/pmm-server/env` file and running the following command to set the latest release version: + ```sh + sed -i "s/PMM_TAG=.*/PMM_TAG=3.0.0/g" ~/.config/pmm-server/env + ``` - Edit `~/.config/pmm-server/env` and create/update with a new tag from [latest release](https://per.co.na/pmm/latest): +3. Pre-pull the new image to ensure a faster restart: ```sh - sed -i "s/PMM_TAG=.*/PMM_TAG=2.33.0/g" ~/.config/pmm-server/env + source ~/.config/pmm-server/env + podman pull ${PMM_IMAGE}:${PMM_TAG} ``` -3. Pre-pull image for faster restart. +4. Restart PMM Server: - + +5. After the upgrade, verify that PMM Server is running correctly: ```sh - source ~/.config/pmm-server/env - podman pull ${PMM_IMAGE}:${PMM_TAG} + podman ps | grep pmm-server ``` -4. Run PMM. +3. Check the logs for any errors: ```sh - systemctl --user restart pmm-server + podman logs pmm-server ``` - - diff --git a/docs/quickstart.md b/docs/quickstart.md index b4d7fdfaca..279a7f356b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -101,7 +101,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Install the PMM Client package: ```sh - yum install -y pmm2-client + yum install -y pmm-client ``` 3. Register PMM Client: @@ -180,7 +180,7 @@ Once PMM is set up, choose the database or the application that you want it to m ```sh apt update - apt install -y pmm2-client + apt install -y pmm-client ``` === ":material-redhat: Red Hat-based" @@ -196,7 +196,7 @@ Once PMM is set up, choose the database or the application that you want it to m 4. Install the PMM Client package: ```sh - yum install -y pmm2-client + yum install -y pmm-client ``` 8. Register PMM Client: @@ -284,7 +284,7 @@ Once PMM is set up, choose the database or the application that you want it to m ```sh apt update - apt install -y pmm2-client + apt install -y pmm-client ``` === ":material-redhat: Red Hat-based" @@ -300,7 +300,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Install the PMM Client package: ```sh - yum install -y pmm2-client + yum install -y pmm-client ``` 4. Register PMM Client: @@ -341,7 +341,7 @@ Once PMM is set up, choose the database or the application that you want it to m ```sh apt update - apt install -y pmm2-client + apt install -y pmm-client ``` === ":material-redhat: Red Hat-based" @@ -357,7 +357,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Install the PMM Client package: ```sh - yum install -y pmm2-client + yum install -y pmm-client ``` 3. Register PMM Client: @@ -397,7 +397,7 @@ Once PMM is set up, choose the database or the application that you want it to m ```sh apt update - apt install -y pmm2-client + apt install -y pmm-client ``` === ":material-redhat: Red Hat-based" @@ -413,7 +413,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Install the PMM Client package: ```sh - yum install -y pmm2-client + yum install -y pmm-client ``` 4. Register PMM Client: diff --git a/docs/quickstart/index.md b/docs/quickstart/index.md index 83cca71ecc..bba22dd6da 100644 --- a/docs/quickstart/index.md +++ b/docs/quickstart/index.md @@ -83,13 +83,13 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: ```sh apt update - apt install -y pmm2-client + apt install -y pmm-client ``` === ":material-redhat: Red Hat-based" @@ -106,7 +106,7 @@ Once PMM is set up, choose the database or the application that you want it to m 5. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 6. Install the PMM Client package: @@ -189,7 +189,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: @@ -211,7 +211,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: @@ -303,7 +303,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: @@ -325,7 +325,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: @@ -370,7 +370,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: @@ -392,7 +392,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: @@ -436,7 +436,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: @@ -458,7 +458,7 @@ Once PMM is set up, choose the database or the application that you want it to m 2. Enable the PMM client repository: ```sh - percona-release enable pmm-client release + percona-release enable pmm3-client release ``` 3. Install the PMM Client package: diff --git a/docs/reference/dashboards/dashboard-mongodb-experimental_collection_details.md b/docs/reference/dashboards/dashboard-mongodb-experimental_collection_details.md index 03f3236f2e..10ce205ea9 100644 --- a/docs/reference/dashboards/dashboard-mongodb-experimental_collection_details.md +++ b/docs/reference/dashboards/dashboard-mongodb-experimental_collection_details.md @@ -3,9 +3,6 @@ !!! caution alert alert-warning "Disclaimer" This is an Experimental Dashboard that is not part of the official Percona Monitoring and Management (PMM) deployment and might be updated. We ship this Dashboard to obtain feedback from our users. -!!! note alert alert-primary "Availability" - This experimental dashboard is available starting with PMM 2.30.0. - This realtime experimental dashboard provides detailed information about the top collections by document count, size, and document read for MongoDB databases. ![!image](../../_images/PMM_Mongodb_Collections_Details_Experimental.png) diff --git a/docs/reference/dashboards/dashboard-mongodb-experimental_collection_overview.md b/docs/reference/dashboards/dashboard-mongodb-experimental_collection_overview.md index c13c067306..1b9dec9a39 100644 --- a/docs/reference/dashboards/dashboard-mongodb-experimental_collection_overview.md +++ b/docs/reference/dashboards/dashboard-mongodb-experimental_collection_overview.md @@ -3,9 +3,6 @@ !!! caution alert alert-warning "Disclaimer" This is an Experimental Dashboard that is not part of the official Percona Monitoring and Management (PMM) deployment and might be updated. We ship this Dashboard to obtain feedback from our users. -!!! note alert alert-primary "Availability" - This experimental dashboard is available starting with PMM 2.30.0. - This realtime dashboard contains panels of data about the Hottest Collections in the MongoDB database. The Instance level includes two panels, one for the **Hottest Collections by Read (Total)** and the **Hottest Collections by Write (total)**. diff --git a/docs/reference/dashboards/dashboard-mongodb-experimental_oplog.md b/docs/reference/dashboards/dashboard-mongodb-experimental_oplog.md index 30a862c9b8..8267daa76e 100644 --- a/docs/reference/dashboards/dashboard-mongodb-experimental_oplog.md +++ b/docs/reference/dashboards/dashboard-mongodb-experimental_oplog.md @@ -3,9 +3,6 @@ !!! caution alert alert-warning "Disclaimer" This is an Experimental Dashboard that is not part of the official Percona Monitoring and Management (PMM) deployment and might be updated. We ship this Dashboard to obtain feedback from our users. -!!! note alert alert-primary "Availability" - This experimental dashboard is available starting with PMM 2.30.0. - This realtime dashboard contains Oplog details such as Recovery Window, Processing Time, Buffer Capacity, and Oplog Operations. ![!image](../../_images/PMM_Mongodb_Collections_Oplog_Experimental.png) diff --git a/docs/reference/dashboards/dashboard-pxc-galera-cluster-summary-experimental.md b/docs/reference/dashboards/dashboard-pxc-galera-cluster-summary-experimental.md index 6d14a4bfb3..bf886397a6 100644 --- a/docs/reference/dashboards/dashboard-pxc-galera-cluster-summary-experimental.md +++ b/docs/reference/dashboards/dashboard-pxc-galera-cluster-summary-experimental.md @@ -3,9 +3,6 @@ !!! caution alert alert-warning "Disclaimer" This is an Experimental Dashboard that is not part of the official Percona Monitoring and Management (PMM) deployment and might be updated. We ship this Dashboard to obtain feedback from our users. -!!! note alert alert-primary "Availability" - This experimental dashboard is available starting with PMM 2.29.0. - The experimental PXC/Galera Cluster Summary dashboard provides a high level information about the clusters, resource utilization and its state for MySQL databases. ![!image](../../_images/PMM_PXC_Galera_Cluster_Summary._Experimental.jpg) diff --git a/docs/reference/dashboards/kubernetes_cluster_summary.md b/docs/reference/dashboards/kubernetes_cluster_summary.md index b854858dbf..7dd443ac11 100644 --- a/docs/reference/dashboards/kubernetes_cluster_summary.md +++ b/docs/reference/dashboards/kubernetes_cluster_summary.md @@ -3,9 +3,6 @@ !!! caution alert alert-warning "Disclaimer" This is an Experimental Dashboard that is not part of the official Percona Monitoring and Management (PMM) deployment and might be updated. We ship this Dashboard to obtain feedback from our users. -!!! note alert alert-primary "Availability" - This experimental dashboard is available starting with PMM 2.30.0. - ![!image](../../_images/PMM_K8s_volume.png) diff --git a/docs/reference/develop_advisor_checks.md b/docs/reference/develop_advisor_checks.md index 71519516eb..b82fcde0ba 100644 --- a/docs/reference/develop_advisor_checks.md +++ b/docs/reference/develop_advisor_checks.md @@ -36,20 +36,10 @@ PMM uses Alertmanager API to get information about failed checks and show them o ![!](../_images/FrontEndChecks.png) -## Check format versions -Starting with the 2.28 release, PMM uses Advisor checks format version 2. Format version 1 is deprecated. +## Format for checks +Advisor checks use the following format: -# Version 2 advisor checks for PMM 2.28 and newer -PMM 2.28 upgraded Advisor Checks to version 2, which uses a slightly different structure than version 1 checks, created in 2.7 and earlier. This is because, compared to version 1 checks, checks created in 2.28 and later offer additional support for: - -- Multiple queries -- Victoria Metrics as a data source -- Database **Family** field - -## Format for v.2 checks -Advisor checks for PMM 2.28 and later use the following format: - -??? note alert alert-info "Version 2 Checks Format" +??? note alert alert-info "Checks Format" {% raw %} ```yaml @@ -168,6 +158,7 @@ Advisor checks for PMM 2.28 and later use the following format: The check script assumes that there is a function with `check_context`, that accepts a _list_ where each item represents the result of a single query specified in the check. Each result itself is a _list_ of _docs_ containing returned rows for SQL databases and documents for MongoDB. It returns zero, one, or several check results that are then converted to alerts. ## Check severity levels + You can label your advisor checks with one of the following available severity levels: **Emergency**, **Alert**, **Critical**, **Error**, **Warning**, **Notice**, **Info**, **Debug**. PMM groups failed checks by their severity, and displays them under **Advisors Checks > Failed Checks**. @@ -179,7 +170,7 @@ Checks can include the following fields: - **Name** (string, required): defines machine-readable name (ID). - **Summary** (string, required): defines short human-readable description. - **Description** (string, required): defines long human-readable description. -- **Family** (string, required): specifies one of the supported database families: MYSQL, POSTGRESQL, MONGODB. This field is only available for Advisor checks v.2, created for PMM 2.28 and later. +- **Family** (string, required): specifies one of the supported database families: MYSQL, POSTGRESQL, MONGODB. This field is only available for Advisor checks v.2. - **Advisor** (string, required): specifies the advisor to which this check belongs. For local environments, specify **dev**. - **Interval** (string/enum, optional): defines running interval. Can be one of the predefined intervals in the UI: Standard, Frequent, Rare. - **Queries** (array, required): contains items that specify queries. diff --git a/docs/reference/faq.md b/docs/reference/faq.md index 8d890ba815..9858de0d42 100644 --- a/docs/reference/faq.md +++ b/docs/reference/faq.md @@ -18,21 +18,13 @@ - [Setting up PMM Server](setting-up/server/index.md) - [Setting up PMM Client](setting-up/client/index.md) -## How can I upgrade from version 1? +## How can I upgrade from version 2? -There is no direct software upgrade path. - -You must [set up](setting-up/index.md) PMM 2 and connect your existing clients to it. - -When all data is registered in PMM2 and expired in PMM1, decommission your PMM1 instance. - -!!! seealso alert alert-info "See also" - - [Upgrade from PMM1](how-to/upgrade.md#upgrade-from-pmm-1) - - [Percona blog: Running PMM1 and PMM2 Clients on the Same Host](https://www.percona.com/blog/2019/11/27/running-pmm1-and-pmm2-clients-on-the-same-host/) +PMM 3 introduces significant architectural changes that require gradual transition from PMM 2. For detailed instructions, see [Upgrade from PMM2](../pmm-upgrade/migrating_from_pmm_2.md). ## How to control data retention? {: #retention } -Go to *Configuration* → *Settings* → *Advanced Settings* → *Data retention* to adjust the value in days. +Go to **PMM Configuration > Settings > Advanced Settings > Data retention** to adjust the value in days. !!! seealso alert alert-info "See also" [Configure data retention](how-to/configure.md#data-retention) @@ -78,7 +70,7 @@ When you remove a monitoring service, previously collected data remains availabl By default, the RDS discovery works with the default `aws` partition. But you can switch to special regions, like the [GovCloud](https://aws.amazon.com/govcloud-us/) one, with the alternative [AWS partitions](https://docs.aws.amazon.com/sdk-for-go/api/aws/endpoints/#pkg-constants) (e.g. `aws-us-gov`) adding them to the *Settings* via the PMM Server [API](details/api.md). -![!image](_images/aws-partitions-in-api.png) +![!image](../_images/aws-partitions-in-api.png) To specify other than the default value, or to use several, use the JSON Array syntax: `["aws", "aws-cn"]`. @@ -121,7 +113,7 @@ The `prometheus.yml` file can be regenerated by restarting the PMM Server contai - [API](details/api.md) - [Percona blog: Extending PMM’s Prometheus Configuration](https://www.percona.com/blog/2020/03/23/extending-pmm-prometheus-configuration/) -## How to troubleshoot an Update? +## How to troubleshoot an update? See [Troubleshoot update](how-to/troubleshoot.md#update). @@ -148,22 +140,13 @@ docker exec -t pmm-server bash -c  "grafana-cli --homepath /usr/share/grafana a (This example assumes your Docker container is named `pmm-server`.) - ## How to change the PMM password for a default admin user? -If you're deploying through Docker, you can change the default password for an admin user after starting the Docker container as follows: - -* For PMM versions 2.27.0 and later: +If you're deploying through Docker, you can change the default password for an admin user after starting the Docker container: -```sh -docker exec -t pmm-server change-admin-password -``` - -* For PMM versions prior to 2.27.0: - -```sh -docker exec -t pmm-server bash -c 'grafana-cli --homepath /usr/share/grafana --configOverrides cfg:default.paths.data=/srv/grafana admin reset-admin-password newpass' -``` + ```sh + docker exec -t pmm-server change-admin-password your_secure_password123 + ``` ## How to use a non-default listen-port for pmm-admin? @@ -193,7 +176,7 @@ Read our [Privacy Policy](https://www.percona.com/privacy-policy) to learn how P Following [CVE fix 2023-3128](https://grafana.com/blog/2023/06/22/grafana-security-release-for-cve-2023-3128/) in the 2.38 release, PMM increases security by only allowing authentications based on the unique user ID provided by the identity provider. -If you are trying to log into PMM via a third-party authentication provider which doesn't support a unique ID field, PMM 2.38 and later will show this error on second and subsequent authentications. +If you are trying to log into PMM via a third-party authentication provider which doesn't support a unique ID field, PMM will show this error on second and subsequent authentications. **Solution**: we recommend logging into PMM using a Percona Account, as this is a highly secure authentication method. **Workaround**: if you need to log into PMM via a third-party authentication provider which doesn’t support a unique ID field, you can use the following workaround to log into PMM: diff --git a/docs/reference/index.md b/docs/reference/index.md index b7561a7a48..53fc56c05d 100644 --- a/docs/reference/index.md +++ b/docs/reference/index.md @@ -51,7 +51,7 @@ PMM Server includes the following tools: - Metrics Monitor provides a historical view of metrics that are critical to a MySQL or MongoDB server instance. It includes the following: - - [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics), a scalable time-series database. (Replaced [Prometheus](https://prometheus.io) in [PMM 2.12.0](../release-notes/2.12.0.md).) + - [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics), a scalable time-series database. - [ClickHouse](https://clickhouse.com) is a third-party column-oriented database that facilitates the Query Analytics functionality. - [Grafana](http://docs.grafana.org) is a third-party dashboard and graph builder for visualizing data aggregated (by VictoriaMetrics or Prometheus) in an intuitive web interface. - [Percona Dashboards](https://github.com/percona/grafana-dashboards) is a set of dashboards for Grafana developed by Percona. diff --git a/docs/reference/third-party/victoria.md b/docs/reference/third-party/victoria.md index 2a5547a88f..2d17e1e496 100644 --- a/docs/reference/third-party/victoria.md +++ b/docs/reference/third-party/victoria.md @@ -1,15 +1,11 @@ # VictoriaMetrics -[VictoriaMetrics](https://victoriametrics.github.io/) is a third-party monitoring solution and time-series database that replaced Prometheus in [PMM 2.12.0](../release-notes/2.12.0.md). +[VictoriaMetrics](https://victoriametrics.github.io/) is a third-party monitoring solution and time-series database. ## Push/Pull modes VictoriaMetrics metrics data can be both 'pushed' to the server and 'pulled' by the server. When setting up services, you can decide which mode to use. -!!! note alert alert-primary "" - The 'push' mode is now default for newly-added services. - (In PMM 2.12.0 the default mode was 'pull'.) - The mode (push/pull) is controlled by the `--metrics-mode` flag for the `pmm-admin config` and `pmm-admin add` commands. If you need to change the metrics mode for an existing Service, you must remove it and re-add it with the same name and the required flags. (You cannot update a service.) @@ -57,8 +53,7 @@ This instructs VictoriaMetrics to [deduplicate](https://docs.victoriametrics.com !!! 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. +You can 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: diff --git a/docs/reference/why_pmm.md b/docs/reference/why_pmm.md deleted file mode 100644 index b40656c1dc..0000000000 --- a/docs/reference/why_pmm.md +++ /dev/null @@ -1,187 +0,0 @@ -# FAQ - -## How can I contact the developers? - -- [Community forum](https://www.percona.com/forums/questions-discussions/percona-monitoring-and-management). -- [Discord chat](http://per.co.na/discord). -- [PMM project in JIRA](https://jira.percona.com/projects/PMM). - -## What are the minimum system requirements? - -- Server: - - Disk: 1 GB per monitored database (1 week data retention) - - Memory: 2 GB per monitored database - - CPU: Supports [`SSE4.2`](https://wikipedia.org/wiki/SSE4#SSE4.2) -- Client: - - Disk: 100 MB - -!!! seealso alert alert-info "See also" - - [Setting up PMM Server](setting-up/server/index.md) - - [Setting up PMM Client](setting-up/client/index.md) - -## How can I upgrade from version 1? - -There is no direct software upgrade path. - -You must [set up](setting-up/index.md) PMM 2 and connect your existing clients to it. - -When all data is registered in PMM2 and expired in PMM1, decommission your PMM1 instance. - -!!! seealso alert alert-info "See also" - - [Upgrade from PMM1](how-to/upgrade.md#upgrade-from-pmm-1) - - [Percona blog: Running PMM1 and PMM2 Clients on the Same Host](https://www.percona.com/blog/2019/11/27/running-pmm1-and-pmm2-clients-on-the-same-host/) - -## How to control data retention? {: #retention } - -Go to *Configuration* → *Settings* → *Advanced Settings* → *Data retention* to adjust the value in days. - -!!! seealso alert alert-info "See also" - [Configure data retention](how-to/configure.md#data-retention) - -## How are PMM Server logs rotated? - -PMM Server embeds multiple components, like Victoria Metrics, Query Analytics, Grafana, `managed`, PostgreSQL, ClickHouse, etc. (components). All PMM Server component logs are rotated by `supervisord`. The components' log rotation settings are stored in `*.ini` files within the `/etc/supervisord.d` directory. Those settings define both the maximum size of a log file and the number of log files to keep. The log rotation takes place once the log file reaches its maximum size. - -## What privileges are required to monitor a MySQL instance? - -```sql -SELECT, PROCESS, SUPER, REPLICATION CLIENT, RELOAD -``` - -!!! seealso alert alert-info "See also" - [Setting Up/Client/MySQL](setting-up/client/mysql.md#create-a-database-account-for-pmm). - -## Can I monitor multiple service instances? - -Yes. - -You can add multiple instances of MySQL or any other service to be monitored from the same PMM Client. - -To do this, you provide a unique port and IP address, or a socket for each instance, and specify a unique name for each. (If a name is not provided, PMM uses the name of the PMM Client host.) - -For example, to add MySQL monitoring for two local MySQL servers: - -```sh -pmm-admin add mysql --username root --password root instance-01 127.0.0.1:3001 -pmm-admin add mysql --username root --password root instance-02 127.0.0.1:3002 -``` - -!!! seealso alert alert-info "See also" - [`pmm-admin add mysql`](details/commands/pmm-admin.md#mysql) - -## Can I rename instances? - -Yes, by removing and re-adding with a different name. - -When you remove a monitoring service, previously collected data remains available in Grafana. However, the metrics are tied to the instance name. So if you add the same instance back with a different name, it will be considered a new instance with a new set of metrics. So if you are re-adding an instance and want to keep its previous data, add it with the same name. - -## Can I add an AWS RDS MySQL or Aurora MySQL instance from a non-default AWS partition? - -By default, the RDS discovery works with the default `aws` partition. But you can switch to special regions, like the [GovCloud](https://aws.amazon.com/govcloud-us/) one, with the alternative [AWS partitions](https://docs.aws.amazon.com/sdk-for-go/api/aws/endpoints/#pkg-constants) (e.g. `aws-us-gov`) adding them to the *Settings* via the PMM Server [API](details/api.md). - -![!image](_images/aws-partitions-in-api.png) - -To specify other than the default value, or to use several, use the JSON Array syntax: `["aws", "aws-cn"]`. - -## What resolution is used for metrics? - -The default values (in seconds): - -| Preset | Low | Medium | High | -|-------------------|------|--------|------| -| Rare | 300 | 180 | 60 | -| Standard | 60 | 10 | 5 | -| Frequent | 30 | 5 | 1 | -| Custom (defaults) | 60 | 10 | 5 | - -!!! seealso alert alert-info "See also" - [Metrics resolution](how-to/configure.md#metrics-resolution) - -## How do I set up Alerting? - -When a monitored service metric reaches a defined threshold, PMM Server can trigger alerts for it using embedded Grafana Alerting functionality. - -For this, you must configure alerting rules that define conditions under which an alert should be triggered, and the contact points used to send the alert (e.g. email). - -Percona templated alerts enable you to create alerts based on built-in or custom templates to simplify the alert setup process. Grafana managed alerts allows attaching rules to your dashboard panel and enables you to create more sophisticated alerting rules. In addition, it can be easier to manage installations with a large number of hosts. This additional flexibility comes at the expense of simplicity. - -!!! seealso alert alert-info "See also" - [Grafana Alerting](https://grafana.com/docs/grafana/latest/alerting/) - -## How do I use a custom Prometheus configuration file? - -Normally, PMM Server fully manages the [Prometheus configuration file](https://prometheus.io/docs/prometheus/latest/configuration/configuration/). - -However, some users may want to change the generated configuration to add additional scrape jobs, configure remote storage, etc. - -From version 2.4.0, when `pmm-managed` starts the Prometheus file generation process, it tries to load the `/srv/prometheus/prometheus.base.yml` file first, to use it as a base for the `prometheus.yml` file. - -The `prometheus.yml` file can be regenerated by restarting the PMM Server container, or by using the `SetSettings` API call with an empty body. - -!!! seealso alert alert-info "See also" - - [API](details/api.md) - - [Percona blog: Extending PMM’s Prometheus Configuration](https://www.percona.com/blog/2020/03/23/extending-pmm-prometheus-configuration/) - -## How to troubleshoot an Update? - -See [Troubleshoot update](how-to/troubleshoot.md#update). - -## What are my login credentials when I try to connect to a Prometheus Exporter? - -- User name: `pmm` -- Password: Agent ID - -PMM protects an exporter's output from unauthorized access by adding an authorization layer. To access an exporter, you can use `pmm` as a user name and the Agent ID as a password. You can find the Agent ID corresponding to a given exporter by running `pmm-admin list`. - -!!! seealso alert alert-info "See also" - [`pmm-admin list`](details/commands/pmm-admin.md#information-commands) - -## How to provision PMM Server with non-default admin password? - -Currently, there is no API available to change the `admin` password. If you're deploying through Docker, you can use the following code snippet to change the password after starting the Docker container: - -```sh -PMM_PASSWORD="mypassword" -echo "Waiting for PMM to initialize to set password..." -until [ "`docker inspect -f {% raw %}{{.State.Health.Status}}{% endraw %} pmm-server`" = "healthy" ]; do sleep 1; done -docker exec -t pmm-server bash -c  "grafana-cli --homepath /usr/share/grafana admin reset-admin-password $PMM_PASSWORD" -``` - -(This example assumes your Docker container is named `pmm-server`.) - - -## How to change the PMM password for a default admin user? - -If you're deploying through Docker, you can change the default password for an admin user after starting the Docker container as follows: - -* For PMM versions 2.27.0 and later: - -```sh -docker exec -t pmm-server change-admin-password -``` - -* For PMM versions prior to 2.27.0: - -```sh -docker exec -t pmm-server bash -c 'grafana-cli --homepath /usr/share/grafana --configOverrides cfg:default.paths.data=/srv/grafana admin reset-admin-password newpass' -``` - -## How to use a non-default listen-port for pmm-admin? - -If you configure the PMM agent to use a non-default listen-port, for pmm-admin to communicate with the agent, use the global flag `--pmm-agent-listen-port=LISTEN_PORT`. - -```sh ---pmm-agent-listen-port=LISTEN_PORT -``` - -Example: To use the listen-port 8000 - - -```sh -pmm-admin --pmm-agent-listen-port=8000 add postgresql --username=pmm-agent --password=pmm-agent-password --query-source=pgstatmonitor nameofpostgres -``` -If you are using OVF/AMI, you can change the default password through SSH by using the following command: - -```sh -change-admin-password -``` diff --git a/docs/release-notes/3.0.0_Beta.md b/docs/release-notes/3.0.0_Beta.md index 041eeb9003..9f1bcf3263 100644 --- a/docs/release-notes/3.0.0_Beta.md +++ b/docs/release-notes/3.0.0_Beta.md @@ -10,6 +10,24 @@ It enables you to observe the health of your database systems, explore new patte ## Release highlights +### Streamlined update process + +We've enhanced PMM's update system with a new **Update** page, accessible via **PMM Configuration > Updates**. This new intuitive interface replaces the previous RPM-based update method, allowing you to easily track versions, configurations, and the health status of your PMM Server and Clients. + +This change comes with proactive notifications, alerting you immediately when new versions are released, and providing detailed change summaries so you can make informed decisions before upgrading. + +![Update page](../Update_page.png) + +#### New upgrade environment variables + +When migrating from PMM v2 to PMM v3, you’ll need to update your environment variables to match the new naming convention. This is because PMM v3 introduces several important changes to improve consistency and clarity: + +- environment variables now use PMM_ prefix +- some boolean flags reversed (e.g., `DISABLE_` → `ENABLE_`) +- removed deprecated variables + +To check the Migration reference table, see [Environment variables in PMM](../install-pmm/install-pmm-server/baremetal/docker/env_var.md##variables-for-migrating-from-pmm-v2-to-pmm-v3). + ### Encryption of sensitive data To strengthen the security of your monitoring setup, all sensitive information stored in the PMM Server database, including usernames, passwords, AWS keys, Azure credentials, and TLS/SSL certificates, is now encrypted. @@ -30,19 +48,35 @@ For more details, see [Connect services](../install-pmm/install-pmm-client/index ![Choose node](../_images/choose_node.png) +For more information, see [PMM Data Encryption](../pmm-admin/security/data_encryption.md). + +### [Tech Preview] Support for PSMDB 8.0 + +Added initial support for monitoring Percona Server for MongoDB (PSMDB) 8.0 deployments in PMM. This includes updates to `mongodb_exporter` to accommodate PSMDB 8.0’s revised metrics structure and renamed metrics (e.g., `wiredTiger.concurrentTransactions` is now `queues.execution`). + +This enhances monitoring, particularly for sharded cluster deployments, and requires PMM Agent version 2.43.1 or later. + +Keep in mind that some dashboard metrics may need further updates to fully support MongoDB 8.0's new format. + ### Grafana Angular support discontinuation -Grafana will discontinue support for Angular starting with version 12, expected in 2025. This affects numerous panels and plugins, including but not limited to Graph and Table panels. +Grafana will discontinue support for Angular starting with version 12, expected in 2025. This affects numerous panels and plugins, including but not limited to Graph and Table panels. We have already migrated many plugins to newer technologies and are actively working on the remaining components to ensure continued functionality. We recommend that you review all plugins in your dashboards and begin planning transitions to newer panel types where necessary. -For a comprehensive list of affected plugins and guidance on migration, see [Grafana's official documentation](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/angular-plugins/) on Angular deprecation and plugin migration. +For the full list of affected plugins and guidance on migration, see [Grafana's official documentation](https://grafana.com/docs/grafana/latest/developers/angular_deprecation/angular-plugins/) on Angular deprecation and plugin migration. We will provide regular updates on our migration progress in future releases to help you prepare for this change and modernize your dashboards. -## New default password for AWS Marketplace instances +### Nomad integration for PMM Client + +PMM Client packages (DEB, RPM, and tarball) now include the Nomad binary, laying the foundation for expanded functionality in future PMM releases. + +While the Nomad binary is now included and properly configured within the PMM Client ecosystem, Nomad agent configuration and execution capabilities will be implemented in future releases, which will unlock more capabilities for PMM. -PMM Server instances launched via AWS Marketplace now use the EC2 instance ID as the default password for the '*admin*' user. +### New default password for AWS Marketplace instances + +PMM Server instances launched via AWS Marketplace now use the EC2 instance ID as the default password for the `admin` user. This change stems from our recent transition to Docker-based deployment, ensuring secure and consistent initial access across all new AWS Marketplace instances. @@ -50,165 +84,92 @@ Only new PMM instances launched via AWS Marketplace are affected by this update. IMPORTANT: Make sure to change the default password immediately after first login. -For more information, see [Install PMM Server on AWS Marketplace](../install-pmm/install-pmm-server/aws/aws.md) +For more information, see [Install PMM Server on AWS Marketplace](../install-pmm/install-pmm-server/aws/aws.md). +## Improvements +### Increased query length limit for MongoDB in QAN -### Breaking API changes +For MongoDB queries, the default maximum query length in Query Analytics (QAN) is now 4096 characters (up from 2048). +This better supports long queries and aggregation pipelines while reducing truncation errors. Other databases retain the 2048-character limit. + +### Enhanced MySQL SlowLog query identification -#### Removed database ID prefixes +Improved MySQL Slow Log query identification by extending the query ID length from 16 to 32 characters. This reduces the likelihood of ID collisions and ensures more accurate and reliable QAN results. -We have removed prefixes from database record identifiers (IDs) in PMM to improve API compatibility with REST and to simplify ID handling. -For example, an ID that was previously `/agent_id/7cae8a44-8210-4f00-a679-764fa8303ee8` is now simply `7cae8a44-8210-4f00-a679-764fa8303ee8`. +### Added monitoring support for default PostgreSQL database -This change affects various components, including nodes, agents, services, and backup-related entities. As a result: +PMM now collects metrics from its internal PostgreSQL database, displaying them in all PostgreSQL dashboards and QAN. -- Database identifiers are now represented as plain UUIDs without prefixes: `/node_id/`, `/agent_id/`, `/service_id/`, etc. -- API endpoints using IDs as path parameters now use a new format -- Exporter passwords (previously identical to the prefixed `agent_id` value) have changed -- Metrics labels, that used `agent_id` value, have been updated +While using the default database isn't recommended, this provides better monitoring coverage for users who rely on this setup. -##### Impact +### Service Account Name length management -Make sure to update any custom scripts, integrations, or alerts that rely on the old exporter ID format to ensure compatibility with this new structure. +To prevent node registration failures, PMM now automatically shortens service account names longer than 200 characters. -#### Simplified boolean feature controls +PFor this, PMM creates a truncated name in the format `{prefix}_{hash}`, where: -We have replaced the so-called `dual booleans` with single booleans for feature toggles in our API to improve usability and simplify code implementation. Additionally, we've made primitive values `optional` to enhance type handling. +- **prefix**: a portion of the original name, providing context +- **hash**: a unique identifier to avoid naming conflicts -This change affects various API endpoints that control feature toggles and how we handle primitive types. As a result: +For example, a long node name such as: `Copyvery_long_mysql_database_server_in_production_environment_with_specific_location_details_and_multiple_configuration_settings_for_east_coast_datacenter_primary_backup_replica_instance_2024` -- Feature states are now represented by a single enabled boolean key -- API requests to toggle features now use a new, simplified format -- Responses from the API will consistently use the new format -- The API can now distinguish between unset values and empty/zero values for primitive types -- Slices and maps continue to use their standard representations without wrappers +is now shortened to: `Copyvery_long_mysql_database_server_in_prod_4a7b3f9d`. -##### Example of new format +For more information see the [Authentication topic](../api/authentication.md). -```json -{"enable_feature": true} // To enable a feature -{"enable_feature": false} // To disable a feature -``` +### Disabled PostgreSQL telemetry -##### Impact +PMM no longer collects PostgreSQL Pillars Telemetry. -Ensure you update any custom scripts, integrations, or frontend code that interact with feature toggles in the API. +This improves compatibility with the upcoming No-root feature and streamlines configuration by relying on PMM’s own telemetry capabilities. -Review your codebase for any logic that relies on the previous dual boolean system and update accordingly. +### Components upgrade -#### Consistent field emission in API responses +The following PMM components have been upgraded to their latest stable versions to enhance functionality, security, and performance: -We have updated our API to consistently emit all fields in responses, including those with default or zero values. This change improves API clarity and affects how API responses are structured. As a result: +- **Grafana 11.1.8**: Includes significant improvements over the previous version 9.2.20 integration in PMM2. For the full list of Grafana changes included with this update, see [Grafana’s 11.1.8 changelog](https://community.grafana.com/t/changelog-updates-in-grafana-11-1-8/134843) and [Grafana release highlights](https://grafana.com/docs/grafana/latest/whatsnew/). -- All API responses now include fields with zero or default values -- API documentation accurately reflects actual API responses -- Responses provide a more complete picture of available settings and their current values -- It's now easier to differentiate between unset fields and those with default or empty values +- **ClickHouse Datasource plugin**: Updated to address security vulnerabilities and maintain system integrity. This update ensures continued reliable operation of ClickHouse-related dashboards. -##### Example of new response format +- **Node Exporter 1.8.2**: Latest stable release improves system metrics collection with upstream enhancements and fixes. + +### Internal improvements: System infrastructure and telemetry + +PMM’s internal architecture has been enhanced with key updates to system maintenance and telemetry. The telemetry system now connects to Percona’s unified endpoint, aligning PMM with other Percona products for more streamlined and consistent data collection. + +In addition, deployment scripts have been optimized, improving system maintenance efficiency and reliability. + +### Breaking API changes -```json -{ - "settings": { - "updates_enabled": true, - "telemetry_enabled": true, - "metrics_resolutions": { - "hr": "5s", - "mr": "10s", - "lr": "60s" - }, - "data_retention": "2592000s", - "ssh_key": "", - "aws_partitions": ["aws"], - "advisor_enabled": true, - "platform_email": "", - "alerting_enabled": true, - "pmm_public_address": "", - "advisor_run_intervals": { - "standard_interval": "86400s", - "rare_interval": "280800s", - "frequent_interval": "14400s" - }, - "backup_management_enabled": true, - "azurediscover_enabled": false, - "connected_to_platform": false, - "default_role_id": 1 - } -} -``` +This release introduces major breaking API changes: -##### Impact +- Database record identifiers no longer use prefixes (e.g., `/agent_id/`) and are now represented as plain UUIDs. +- Feature toggles have been simplified from dual booleans to a single boolean control with an `enable_feature` property. +- API responses now consistently emit all fields including those with default or zero values. +- Service, node, and agent management has been streamlined through consolidated endpoints where the resource type is specified as a top-level property in the request payload. +- Low-level Inventory API sections have been removed from documentation in favor of the Management API for inventory-related tasks. -Ensure you review and update any custom scripts, integrations, or code that parse API responses. The new format provides more consistent and complete information, but may require updates to existing parsing logic. +For detailed information about all these API changes and new endpoints, see the [PMM API Documentation](https://percona-pmm.readme.io/v3/reference/release-notes/3.0.0_Beta). -Be aware that API responses will be more verbose, including all defined fields regardless of their values. This change improves clarity but may slightly increase the size of API responses. +## Fixed issues -#### Removed Inventory API section from documentation +- [PMM-13452](https://perconadev.atlassian.net/browse/PMM-13452): [QAN] - Fixed an issue where QAN was not displaying data in the **Details** tab when selecting a query. +- [PMM-13417](https://perconadev.atlassian.net/browse/PMM-13417) - Fixed **Service Summary** panel returning 404 error on the **PostgreSQL Instance Summary** dashboard. +-[PMM-13280](https://perconadev.atlassian.net/browse/PMM-13280) - Fixed SSH connectivity issue that prevented users from connecting to OVF instances using SSH keys. -We have streamlined our API documentation by removing most of the low-level Inventory API sections and focusing instead on the Management API for inventory-related tasks. If you are using the Inventory API in your integrations or scripts, make sure to review the updated API documentation for the correct endpoints. +-[PMM-13265](https://perconadev.atlassian.net/browse/PMM-13265) - Fixed error preventing creation of alert rules from the pmm_postgresql_too_many_connections template. +- [PMM-13280](https://perconadev.atlassian.net/browse/PMM-13280) - Fixed "Permission Denied" errors when trying to SSH into OVF instances using configured SSH keys. -#### Streamlined API endpoints for Services, Nodes, and Agents +- [PMM-13250](https://perconadev.atlassian.net/browse/PMM-13250) - Fixed "method RestoreBackup not implemented" error that occurred when initiating backup restoration through the API. + + - [PMM-13122](https://perconadev.atlassian.net/browse/PMM-13122) - Fixed navigation between pages to properly maintain selected service names and timeframes when switching between different dashboards and metrics views. -We have simplified our API structure by consolidated multiple endpoints into single, versatile endpoints for Services, Nodes, and Agents: -##### Services API update -A new `POST /v1/inventory/services` endpoint replaces individual service-specific endpoints. You can now specify the service type (mysql, mongodb, postgresql, proxysql, haproxy, external) as a top-level property in the request payload. For example: -```json -{ - "mysql": { - "service_name": "mysql-sales-db-prod-1", - "node_id": "pmm-server", - "address": "209.0.25.100", - "port": 3306 - // ... other properties - } -} -``` -##### Nodes API update -Similarly, `POST /v1/inventory/nodes` now handles all node types (generic, container, remote, remote_rds, remote_azure). The node type is specified in the request payload: -```json -{ - "generic": { - "node_name": "mysql-sales-db-prod-1", - "region": "us-east-1", - "az": "us-east-1a", - "address": "209.0.25.100" - // ... other properties - } -} -``` - - -##### Agents API update - -The Agents API follows the same pattern, with a single endpoint for all agent types - `POST /v1/inventory/agents`. The agent type is specified as the top-level property in the request payload: - -```json -{ - "mysqld_exporter": { - "pmm_agent_id": "pmm-server", - "service_id": "13519ec9-eedc-4d21-868c-582e146e1d0e", - "username": "mysql-prod-user", - "password": "mysql-prod-pass", - "listen_port": 33060, - "custom_labels": { - "department": "sales", - "environment": "sales-prod", - "replication_set": "db-sales-prod-1-rs1", - "cluster": "db-sales-prod-1" - } - } -} -``` - -##### Impact - -Update your API calls to use the new consolidated endpoints. Review the updated API documentation in the Swagger UI of your PMM instance for the new request formats. diff --git a/docs/troubleshoot/alerting_issues.md b/docs/troubleshoot/alerting_issues.md index 76260ca8d3..0850691b64 100644 --- a/docs/troubleshoot/alerting_issues.md +++ b/docs/troubleshoot/alerting_issues.md @@ -9,8 +9,10 @@ Percona Alerting option isn't active. 2. Enable **Alerting**. ## Custom alert rule templates not migrated to Percona Alerting -If you have used Integrated Alerting in previous PMM versions, and had custom templates under ``/srv/ia/templates``, make sure to transfer them to ``/srv/alerting/templates``. -PMM is no longer sourcing templates from the ``ia`` folder, since we have deprecated Integrated Alerting with the 2.31 release. + +After upgrading from the latest PMM 2 version to PMM 3, you will find all your alert templates under **Alerting > Alert rule templates**. + +If you have any templates available in the `/srv/ia/templates` folder, make sure to transfer them to `/srv/alerting/templates` as PMM 3 will look for custom templates in this location. ## Unreachable external IP addresses @@ -20,7 +22,6 @@ To configure your PMM Server’s Public Address, select < ## Alert Rule Templates are disabled -Built-In alerts are not editable, but you can copy them and edit the copies. (In [PMM 2.14.0](../release-notes/2.14.0.md) and above). - -If you create a custom alert rule template, you will have access to edit. +Built-in alerts are not editable, but you can copy them and edit the copies. +If you create a custom alert rule template, you will have access to edit. \ No newline at end of file diff --git a/docs/troubleshoot/config_issues.md b/docs/troubleshoot/config_issues.md index 8da8040454..4d6c30954e 100644 --- a/docs/troubleshoot/config_issues.md +++ b/docs/troubleshoot/config_issues.md @@ -1,9 +1,8 @@ - # Configuration issues This section focuses on configuration issues, such as PMM-agent connection, adding and removing services for monitoring, and so on. -## Client-server connections +## Client-Server connections There are many causes of broken network connectivity. @@ -13,7 +12,7 @@ PMM can also generate diagnostics data that can be examined and/or shared with o Logs obtained in this way include PMM Client logs and logs received from the PMM Server, and stored separately in the `client` and `server` folders. The `server` folder also contains its `client` subfolder with the self-monitoring client information collected on the PMM Server. -Beginning with [PMM 2.4.0](../release-notes/2.4.0.md), there is a flag that enables the fetching of [`pprof`](https://github.com/google/pprof) debug profiles and adds them to the diagnostics data. To enable, run `pmm-admin summary --pprof`. +For additional debugging information, use the `--pprof` flag to include [pprof](https://github.com/google/pprof) debug profiles: `pmm-admin summary --pprof`. You can get PMM Server logs with either of these methods: @@ -26,14 +25,13 @@ In a browser, visit `https:///logs.zip`. To obtain the logs from the **Help** menu: {.power-number} - 1. Select **Help** → **PMM Logs**. 2. Click **PMM Logs** to retrieve PMM diagnostics data which can be examined and shared with our support team should you need help. ## Connection difficulties -**Passwords** +### Passwords When adding a service, the host might not be detected if the password contains special symbols (e.g., `@`, `%`, etc.). @@ -51,11 +49,8 @@ will give: "s3cR%23tpa%24%24worD" ``` -**Password change** +### Password change When adding clients to the PMM Server, you use the `admin` user. However, if you change the password for the admin user from the PMM UI, then the clients will not be able to access PMM due to authentication issues. Also, Grafana will lock out the admin user due to multiple unsuccessful login attempts. -In such a scenario, use [Service Accounts](../api/authentication.md#service-accounts-authentication) for authentication. You can use Service Accounts as a replacement for basic authentication and API keys. - - - +In such a scenario, use [Service Accounts](../api/authentication.md#service-accounts-authentication) for authentication. You can use Service Accounts as a replacement for basic authentication and API keys. \ No newline at end of file diff --git a/docs/troubleshoot/upgrade_issues.md b/docs/troubleshoot/upgrade_issues.md index 7c3dc3e12d..58062d0356 100644 --- a/docs/troubleshoot/upgrade_issues.md +++ b/docs/troubleshoot/upgrade_issues.md @@ -1,71 +1,15 @@ -# Upgrade issues +# Troubleshoot upgrade issues ## PMM Server not updating correctly - -If the PMM Server wasn't updated correctly, or if you have concerns about the release, you can force the update process in 2 ways: -{.power-number} - -1. From the UI - Home panel: click the Alt key on the reload icon in the Update panel to make the Update Button visible even if you are on the same version as available for update. Pressing this button will force the system to rerun the update so that any broken or not installed components can be installed. In this case, you'll go through the usual update process with update logs and successful messages at the end. - -2. By API call (if UI not available): You can call the Update API directly with: - - ```sh - curl --user admin:admin --request POST 'http://PMM_SERVER/v1/Updates/Start' - ``` - - Replace `admin:admin` with your username/password, and replace `PMM_SERVER` with your server address. - - !!! note alert alert-primary "Note" - You will not see the logs using this method. - - Refresh The Home page in 2-5 minutes, and you should see that PMM was updated. - -3. Upgrade PMM Server using [Docker](../pmm-upgrade/upgrade_docker.md). - - -## PMM Server not showing latest versions available with the instances created from AWS - -For PMM versions prior to 2.33.0, in specific environments, including AWS, some EPEL repository mirrors did not respond within the time limit defined by `pmm-update` (currently set to 30 seconds). It was causing supervisord to kill pmm-update-checker, which determines if a newer PMM Server is available for upgrade. - -**Solution** - -Log in to the PMM Server and run the following command as a root user: - -```sh - $ yum-config-manager --setopt=epel.timeout=1 --save -``` - -## PMM Server fails while upgrading - -A bug in PMM Server ansible scripts caused PMM to upgrade Nginx's dependencies without updating Nginx itself. Due to this, PMM throws an error while upgrading and cannot upgrade to a newer version. - -!!! caution alert alert-warning "Important" - This issue has been resolved for PMM version 2.33.0. However, the issue persists on all the versions prior to 2.33.0. - - -**Solution** - -While PMM is being upgraded, log in to the PMM Server and run the following command: - -```sh - sed -i 's/- nginx/- nginx*/' /usr/share/pmm-update/ansible/playbook/tasks/update.yml -``` - - -## Admin user cannot access PMM after upgrading - -After upgrading PMM from version 2.39.0 to 2.40.0 (not el7) using Docker, the `admin` user cannot access the PMM UI. - -**Solution**: To fix the problem and gain back admin access to the PMM interface execute the following: - -```sh -# psql -U grafana -grafana=> update "user" set id='1' where login='admin'; -UPDATE 1 -grafana=> \q - -# grafana cli --homepath=/usr/share/grafana --config=/etc/grafana/grafana.ini admin reset-admin-password -``` - - +If the automatic update process isn't working, you can force an update using the API: + +1. Open your terminal. +2. Run the update command, replacing : with your credentials and with your PMM server addressЖ + + ```curl -X POST \ + --user : \ + 'http:///v1/server/updates:start' \ + -H 'Content-Type: application/json' + ``` +3. Wait 2-5 minutes and refresh the PMM Home page to verify the update. \ No newline at end of file diff --git a/docs/uninstall-pmm/uninstall_package_manager.md b/docs/uninstall-pmm/uninstall_package_manager.md index 4af6065fa3..47324afe35 100644 --- a/docs/uninstall-pmm/uninstall_package_manager.md +++ b/docs/uninstall-pmm/uninstall_package_manager.md @@ -10,7 +10,7 @@ To uninstall PMM client with package manager, do the following steps: 1. Uninstall the PMM Client package. ```sh - apt remove -y pmm2-client + apt remove -y pmm-client ``` 2. Remove the Percona repository @@ -27,7 +27,7 @@ To uninstall PMM client with package manager, do the following steps: 1. Uninstall the PMM Client package. ```sh - yum remove -y pmm2-client + yum remove -y pmm-client ``` 2. Remove the Percona repository diff --git a/docs/use/commands/pmm-admin.md b/docs/use/commands/pmm-admin.md index 3c5f0ae8ca..9c89c102a5 100644 --- a/docs/use/commands/pmm-admin.md +++ b/docs/use/commands/pmm-admin.md @@ -59,7 +59,7 @@ PMM communicates with the PMM Server via a PMM agent process. `--trace` : Enable trace logging (implies debug). -`--log-level` (This parameter is available starting with PMM 2.29.0.) +`--log-level` : Set the level for the logs as per your requirement such as INFO, WARNING, ERROR, and FATAL. `--json` @@ -77,7 +77,7 @@ PMM communicates with the PMM Server via a PMM agent process. `--group=` : Group name for external services. Default: `external` -`--expose-exporter` (This flag is availble starting with PMM 2.41.0.) +`--expose-exporter` : If you enable this flag, any IP address on the local network and anywhere on the internet can access exporter endpoints. If the flag is disabled/not present, exporter endpoints can be accessed only locally. The flag is disabled by default ## COMMANDS @@ -116,7 +116,7 @@ PMM communicates with the PMM Server via a PMM agent process. `--skip-server` : Skip fetching `logs.zip` from PMM Server. - `--pprof` (This parameter is available starting with PMM 2.29.0) + `--pprof` : Include performance profiling data in the summary. ### CONFIGURATION COMMANDS @@ -149,7 +149,7 @@ PMM communicates with the PMM Server via a PMM agent process. `--paths-base=dir` : Base path where all binaries, tools and collectors of PMM client are located - `--agent-password=password` (This parameter i available starting with PMM 2.29.0.) + `--agent-password=password` : Custom agent password. #### `pmm-admin register` @@ -184,7 +184,7 @@ PMM communicates with the PMM Server via a PMM agent process. `--custom-labels=labels` : Custom user-assigned labels. - `--agent-password=password` (This parameter is available starting with PMM 2.29.0.) + `--agent-password=password` : Custom agent password. #### `pmm-admin add --pmm-agent-listen-port=LISTEN_PORT` @@ -346,10 +346,10 @@ When you remove a service, collected data remains on PMM Server for the specifie - `push`: agent will push metrics. - `pull`: server scrapes metrics from agent. - `--max-query-length=NUMBER` (This parameter is available starting with PMM 2.32.0.) + `--max-query-length=NUMBER` : Limit query length in QAN. Allowed values: - -1: No limit. - - 0: Default value. The default value is 2048 chars. + - 0: Default value. The default value is 4096 chars. - >0: Query will be truncated after chars. !!! caution "" @@ -570,7 +570,7 @@ In low resolution we collect metrics from collectors which could take some time: - `push`: agent will push metrics. - `pull`: server scrapes metrics from agent. - `--max-query-length=NUMBER` (This parameter is available starting with PMM 2.32.0.) + `--max-query-length=NUMBER` : Limit query length in QAN. Allowed values: - -1: No limit. - 0: Default value. The default value is 2048 chars. @@ -654,7 +654,7 @@ In low resolution we collect metrics from collectors which could take some time: - `push`: agent will push metrics. - `pull`: server scrapes metrics from agent. - `--max-query-length=NUMBER` (This parameter is available starting with PMM 2.32.0.) + `--max-query-length=NUMBER` : Limit query length in QAN. Allowed values: - -1: No limit. - 0: Default value. The default value is 2048 chars. diff --git a/docs/use/commands/pmm-agent.md b/docs/use/commands/pmm-agent.md index 8dcc65920c..6bdbfd8917 100644 --- a/docs/use/commands/pmm-agent.md +++ b/docs/use/commands/pmm-agent.md @@ -46,7 +46,7 @@ Most options can be set via environment variables (shown in parentheses). | `--machine-id=machine-id` | `PMM_AGENT_SETUP_MACHINE_ID` | Node machine ID (default is auto-detected). | `--metrics-mode=auto` | `PMM_AGENT_SETUP_METRICS_MODE` | Metrics flow mode for agents node-exporter. Can be `push` (agent will push metrics), `pull` (server scrapes metrics from agent) or `auto` (chosen by server). | `--node-model=NODE-MODEL` | `PMM_AGENT_SETUP_NODE_MODEL` | Node model. -| `--paths-base=PATH` | `PMM_AGENT_PATHS_BASE` | Base path for PMM client, where all binaries, tools and collectors are located. If not set, default is `/usr/local/percona/pmm2`. +| `--paths-base=PATH` | `PMM_AGENT_PATHS_BASE` | Base path for PMM client, where all binaries, tools and collectors are located. If not set, default is `/usr/local/percona/pmm`. | `--paths-exporters_base=PATH` | `PMM_AGENT_PATHS_EXPORTERS_BASE` | Base path for exporters to use. If not set, or set to a relative path, uses value of `--paths-base` prepended to it. | `--paths-mongodb_exporter=PATH` | `PMM_AGENT_PATHS_MONGODB_EXPORTER` | Path to `mongodb_exporter`. | `--paths-mysqld_exporter=PATH` | `PMM_AGENT_PATHS_MYSQLD_EXPORTER` | Path to `mysqld_exporter`. @@ -64,7 +64,7 @@ Most options can be set via environment variables (shown in parentheses). | `--trace` | `PMM_AGENT_TRACE` | Enable trace output (implies `--debug`). | `-h`, `--help` | | Show help (synonym for `pmm-agent help`). | `--version` | | Show application version, PMM version, time-stamp, git commit hash and branch. -| `--expose-exporter` (This flag is available starting with PMM 2.41.0.)| | If you enable this flag, any IP address on the local network and anywhere on the internet can access node exporter endpoints. If the flag is disabled, node exporter endpoints can be accessed only locally. +| `--expose-exporter` | | If you enable this flag, any IP address on the local network and anywhere on the internet can access node exporter endpoints. If the flag is disabled, node exporter endpoints can be accessed only locally. ## CONFIG FILE @@ -78,10 +78,10 @@ Since 2.23.0 this flag could be used for easier setup of PMM agent. With this fl **Examples:** -- **Case 1:** There are no root permissions for `/usr/local/percona/pmm2` folder or there is a need to change default folder for PMM files. +- **Case 1:** There are no root permissions for `/usr/local/percona/pmm` folder or there is a need to change default folder for PMM files. Command: ```` -pmm-agent setup --paths-base=/home/user/custom/pmm2 --config-file=pmm-agent-dev.yaml --server-insecure-tls --server-address=127.0.0.1:443 --server-username=admin --server-password=admin +pmm-agent setup --paths-base=/home/user/custom/pmm --config-file=pmm-agent-dev.yaml --server-insecure-tls --server-address=127.0.0.1:443 --server-username=admin --server-password=admin ```` Config output: ```` @@ -96,21 +96,21 @@ server: password: admin insecure-tls: true paths: - paths_base: /home/user/custom/pmm2 - exporters_base: /home/user/custom/pmm2/exporters - node_exporter: /home/user/custom/pmm2/exporters/node_exporter - mysqld_exporter: /home/user/custom/pmm2/exporters/mysqld_exporter - mongodb_exporter: /home/user/custom/pmm2/exporters/mongodb_exporter - postgres_exporter: /home/user/custom/pmm2/exporters/postgres_exporter - proxysql_exporter: /home/user/custom/pmm2/exporters/proxysql_exporter - rds_exporter: /home/user/custom/pmm2/exporters/rds_exporter - azure_exporter: /home/user/custom/pmm2/exporters/azure_exporter - vmagent: /home/user/custom/pmm2/exporters/vmagent + paths_base: /home/user/custom/pmm + exporters_base: /home/user/custom/pmm/exporters + node_exporter: /home/user/custom/pmm/exporters/node_exporter + mysqld_exporter: /home/user/custom/pmm/exporters/mysqld_exporter + mongodb_exporter: /home/user/custom/pmm/exporters/mongodb_exporter + postgres_exporter: /home/user/custom/pmm/exporters/postgres_exporter + proxysql_exporter: /home/user/custom/pmm/exporters/proxysql_exporter + rds_exporter: /home/user/custom/pmm/exporters/rds_exporter + azure_exporter: /home/user/custom/pmm/exporters/azure_exporter + vmagent: /home/user/custom/pmm/exporters/vmagent tempdir: /tmp - pt_summary: /home/user/custom/pmm2/tools/pt-summary - pt_pg_summary: /home/user/custom/pmm2/tools/pt-pg-summary - pt_mysql_summary: /home/user/custom/pmm2/tools/pt-mysql-summary - pt_mongodb_summary: /home/user/custom/pmm2/tools/pt-mongodb-summary + pt_summary: /home/user/custom/pmm/tools/pt-summary + pt_pg_summary: /home/user/custom/pmm/tools/pt-pg-summary + pt_mysql_summary: /home/user/custom/pmm/tools/pt-mysql-summary + pt_mongodb_summary: /home/user/custom/pmm/tools/pt-mongodb-summary ports: min: 42000 max: 51999 @@ -123,7 +123,7 @@ As could be seen above, base for all exporters and tools was changed only by set - **Case 2:** The older `--paths-exporters_base` flag could be passed along with the `--paths-base` Command: ```` -pmm-agent setup --paths-base=/home/user/custom/pmm2 --paths-exporters_base=/home/user/exporters --config-file=pmm-agent-dev.yaml --server-insecure-tls --server-address=127.0.0.1:443 --server-username=admin --server-password=admin +pmm-agent setup --paths-base=/home/user/custom/pmm --paths-exporters_base=/home/user/exporters --config-file=pmm-agent-dev.yaml --server-insecure-tls --server-address=127.0.0.1:443 --server-username=admin --server-password=admin ```` Config output: ```` @@ -138,7 +138,7 @@ server: password: admin insecure-tls: true paths: - paths_base: /home/user/custom/pmm2 + paths_base: /home/user/custom/pmm exporters_base: /home/user/exporters node_exporter: /home/user/exporters/node_exporter mysqld_exporter: /home/user/exporters/mysqld_exporter @@ -149,10 +149,10 @@ paths: azure_exporter: /home/user/exporters/azure_exporter vmagent: /home/user/exporters/vmagent tempdir: /tmp - pt_summary: /home/user/custom/pmm2/tools/pt-summary - pt_pg_summary: /home/user/custom/pmm2/tools/pt-pg-summary - pt_mysql_summary: /home/user/custom/pmm2/tools/pt-mysql-summary - pt_mongodb_summary: /home/user/custom/pmm2/tools/pt-mongodb-summary + pt_summary: /home/user/custom/pmm/tools/pt-summary + pt_pg_summary: /home/user/custom/pmm/tools/pt-pg-summary + pt_mysql_summary: /home/user/custom/pmm/tools/pt-mysql-summary + pt_mongodb_summary: /home/user/custom/pmm/tools/pt-mongodb-summary ports: min: 42000 max: 51999 diff --git a/docs/use/dashboard-inventory.md b/docs/use/dashboard-inventory.md index 7d0c215b9d..c3274a4f55 100644 --- a/docs/use/dashboard-inventory.md +++ b/docs/use/dashboard-inventory.md @@ -21,8 +21,6 @@ The **Services** tab displays the individual services, the nodes on which they r | Port | The port number on which the service is running. || | Options |* You can check **QAN** information and the **Dashboard** for each service by clicking on the **** icon

* You can also check additional information about the service, by clicking on the **** icon. This expands the service entry to show reference information like service labels and IDs.| - - ![!image](../_images/PMM_Inventory_Service_Selection.png) #### Attributes @@ -33,10 +31,10 @@ These are some of the atributes for a service: - Every service is related to a certain node via its `node_id` attribute. This feature allows to support monitoring of multiple instances on a single node, with different service names, e.g. `mysql1-3306`, and `mysql1-3307`. -- Starting with PMM 2.41.0, each instance of a service gets a `version` attribute to the response of the endpoint that provides a list of services being monitored by PMM. This makes it easy to visualize the database server version. +- Each instance of a service gets a `version` attribute to the response of the endpoint that provides a list of services being monitored by PMM. This makes it easy to visualize the database server version. However, following are the imitations: - + - The version is not captured for the internal PostgreSQL database. - The version is only captured when a new service is being added to PMM and the agent installed on the client side is equal to or greater than v2.41.0. - When a database is upgraded, you will not see the database version updated automatically. It will be updated if you remove and then re-add the service. @@ -57,7 +55,7 @@ To view the agents running on a service and their health status, click **OK** or #### 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. +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. @@ -73,13 +71,11 @@ Understanding the relationship between nodes and services is key to gaining insi You can edit the labels as follows: -1. From the **Main** menu, navigate to **Configuration → Inventory**. +1. From the **Main** menu, go to **PMM Configuration > PMM Inventory > Services**. 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. +3. Click **Edit** to change the labels, then click **Save Changes**. ![!](../_images/PMM_access_edit_labels.png) @@ -102,63 +98,58 @@ Editing existing labels can impact the following PMM functions: - **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](../reference/glossary.md#technical-preview) and is subject to change. We recommend that early adopters use this feature for testing purposes only. +**Organize by Clusters** toggle shows related services grouped into clusters based on their `cluster` label, giving you a consolidated view of your infrastructure. -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) +![!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) +![!image](../_images/PMM_Inventory_cluster_view_details.png) Furthermore, you can filter the clusters by criteria such as Cluster name, Status, Service name, Node name, Monitoring, Address, and Port. -![!image](../../_images/PMM_Inventory_cluster_view_filter.png) - +![!image](../_images/PMM_Inventory_cluster_view_filter.png) ### **Nodes** tab -Shows where the service and agents run. - -Each `node_id` is associated with a `machine_id` (from `/etc/machine-id`). Nodes also have `node_type` attributes, which give an idea about their nature. Some examples are: generic, container, remote, remote_rds, etc. - -By expanding the entry from the options column, you can check the node labels and attributes. +The **Nodes** tab helps you monitor where services and agents are running across your infrastructure. Each node has: -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. +- A unique `node_id` linked to its `machine_id` (from `/etc/machine-id`) +- A `node_type` attribute (e.g., generic, container, remote, remote_rds) indicating its nature -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 node information: +- Click the expand icon in the **Options** column to see node labels and attributes. +- Click any node to view its connected agents. +- Click links in the **Services** column to see running services. -To see the details of the agents running, do the following: +To see agent details: {.power-number} -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. +1. In the **Nodes** tab, under the **Monitoring** column, click **OK** or **Failed** based on the node’s status to view information about the total number of agents deployed on that node: ![!image](../_images/PMM_Inventory_Node_Selection.png) -2. Click on the icon under the **Options** column to view the properties of a specific agent. +2. Click on the icon under the **Options** column to view the properties of a specific agent. -3. On the **Nodes** tab, under the **Options** column, click on the icon for the selected node to check the properties and the current health status of an agent. +3. On the **Nodes** tab, under the **Options** column, click on the icon for the selected node to check the properties and the current health status of an agent. ![!image](../_images/PMM_Inventory_Node_Agent_Properties.png) -## Removing items from the inventory +## Remove items from the inventory To remove items from the inventory: {.power-number} -1. Go to **Configuration** > {{icon.inventory}} **Inventory**. +1. Go to **PMM Configuration > PMM Inventory**. 2. In the first column, select the items to be removed. ![!image](../_images/PMM_Inventory_Item_Selection.png) -3. Click **Delete** and confirm the removal. - - +3. Click **Delete** and confirm the removal. \ No newline at end of file diff --git a/docs/use/dashboards/dashboard-inventory.md b/docs/use/dashboards/dashboard-inventory.md index 1ded8adfd4..c1fb634c01 100644 --- a/docs/use/dashboards/dashboard-inventory.md +++ b/docs/use/dashboards/dashboard-inventory.md @@ -27,7 +27,6 @@ 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 icon under the **Options** column. -![!image](../../_images/PMM_Inventory_Service_Agent_Properties.png) ### **Nodes** tab @@ -38,7 +37,7 @@ Each `node_id` is associated with a `machine_id` (from `/etc/machine-id`). Nodes By expanding the entry from the options column, you can check the node labels and attributes. -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. +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. To see the details of the agents running, do the following: @@ -46,7 +45,8 @@ To see the details of the agents running, do the following: 2. Click on the icon under the **Options** column to view the properties of a specific agent. -3. On the **Nodes** tab, under the **Options** column, click on the icon for the selected node to check the properties and the current health status of an agent. +3. On the **Nodes** tab, under the **Options** column, click on the icon for the selected node to check the properties and the current health status of an agent. + ![!image](../../_images/PMM_Inventory_Node_Agent_Properties.png) ## Removing items from the inventory diff --git a/docs/use/metrics/extend_metrics.md b/docs/use/metrics/extend_metrics.md index 08bc1b6a84..ef164b228a 100644 --- a/docs/use/metrics/extend_metrics.md +++ b/docs/use/metrics/extend_metrics.md @@ -9,9 +9,9 @@ The collector is enabled by default. The following folders are used for differen | Resolution | Folder | |------------|---------------------------------------------------------------------------| -| High | `/usr/local/percona/pmm2/collectors/textfile-collector/high-resolution` | -| Medium | `/usr/local/percona/pmm2/collectors/textfile-collector/medium-resolution` | -| Low | `/usr/local/percona/pmm2/collectors/textfile-collector/low-resolution` | +| High | `/usr/local/percona/pmm/collectors/textfile-collector/high-resolution` | +| Medium | `/usr/local/percona/pmm/collectors/textfile-collector/medium-resolution` | +| Low | `/usr/local/percona/pmm/collectors/textfile-collector/low-resolution` | ![!image](../../_images/node-exporter.textfile-collector.1.png) @@ -23,14 +23,14 @@ Metrics are stored on the PMM Server-side with additional labels related to this To statically set roles for a machine using labels: ```sh -echo 'node_role{role="my_monitored_server_1"} 1' > /usr/local/percona/pmm2/collectors/textfile-collector/low-resolution/node_role.prom +echo 'node_role{role="my_monitored_server_1"} 1' > /usr/local/percona/pmm/collectors/textfile-collector/low-resolution/node_role.prom ``` Here's an example of a `cron` job that automatically pushes logged-in users: ```sh $ cat /etc/cron.d/loggedin_users -*/1 * * * * root /usr/bin/who | /usr/bin/wc -l | sed -ne 's/^/node_loggedin_users /p' > /usr/local/percona/pmm2/collectors/textfile-collector/high-resolution/node_users.prom +*/1 * * * * root /usr/bin/who | /usr/bin/wc -l | sed -ne 's/^/node_loggedin_users /p' > /usr/local/percona/pmm/collectors/textfile-collector/high-resolution/node_users.prom ``` ![!image](../../_images/node-exporter.textfile-collector.2.png) \ No newline at end of file diff --git a/docs/use/qan/panels/details.md b/docs/use/qan/panels/details.md index b2fcd4223b..2f34b0bcf4 100644 --- a/docs/use/qan/panels/details.md +++ b/docs/use/qan/panels/details.md @@ -1,4 +1,4 @@ -# Details Panel +# Details panel - Selecting an item in the Overview panel opens the **Details panel** with a [Details Tab](#details-tab). - If the dimension is **Query**, the panel also contains the [Examples Tab](#examples-tab), [Explain Tab](#explain-tab), and [Tables Tab](#tables-tab). @@ -36,7 +36,6 @@ For PostgreSQL queries (when using `pg_stat_monitor`) the top query will also be Other useful metrics (when using **pg_stat_monitor**) to monitor PostgreSQL Server performance are [Histograms](https://github.com/percona/pg_stat_monitor/blob/master/docs/USER_GUIDE.md#histogram). **Histograms** provide more explicit information about number of queries for fingerprint (`queryid`). Ranges are from 0 seconds up to 100 seconds. - Here is picture of **histogram** in graph: ![!image](../../../_images/PMM_Query_Analytics_Tabs_Details_Histogram.png) @@ -62,8 +61,7 @@ The **Explain** tab shows the `explain` output for the selected query, in Classi - MongoDB: JSON only. - PostgreSQL: Not supported. -Starting with PMM 2.33.0, for MySQL, the *Explain* tab is supported without the *Examples* enabled. If a query in the *Explain* tab contains sensitive data, placeholders will replace them. -Before you can run Explain, you must specify the values for these placeholders. This image illustrates the query with placeholders. +The **Explain** tab for MySQL queries works without enabling **Examples**. For security, sensitive data appears as placeholders that you must fill in before running Explain: ![!image](../../../_images/PMM_Query_Analytics_Tabs_Explain_With_Placeholders.png) @@ -100,5 +98,4 @@ The **Tables** tab shows information on the tables and indexes involved in the s The **Plan** tab shows the plan for PostgreSQL queries (only available when using *pg_stat_monitor*). -![!image](../../../_images/PMM_Query_Analytics_Tabs_Plan.png) - +![!image](../../../_images/PMM_Query_Analytics_Tabs_Plan.png) \ No newline at end of file diff --git a/docs/use/qan/panels/filters.md b/docs/use/qan/panels/filters.md index 4c352f5201..3bc3c5dc79 100644 --- a/docs/use/qan/panels/filters.md +++ b/docs/use/qan/panels/filters.md @@ -16,7 +16,7 @@ !!! 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 testing purposes only. -Starting with PMM 2.38.0, you can filter queries by custom filter groups based on key=value pairs separated from query comments. By default, this feature is disabled. +Filter queries using custom key=value pairs from query comments. This feature is disabled by default. ### Supported technologies and agents diff --git a/mkdocs-base.yml b/mkdocs-base.yml index ad47fd7574..b61c3d4090 100644 --- a/mkdocs-base.yml +++ b/mkdocs-base.yml @@ -227,11 +227,13 @@ nav: - Manual upgrade: - pmm-upgrade/upgrade_docker.md - pmm-upgrade/upgrade_podman.md - - Upgrade PM server in K8s: + - Upgrade PMM Server in K8s: - pmm-upgrade/upgrade_helm.md - - pmm-upgrade/upgrade_agent.md - - pmm-upgrade/upgrade_from_pmm_1.md + - pmm-upgrade/migrating_from_pmm_2.md - pmm-upgrade/upgrade_aws.md + - Upgrade PMM Client: + - pmm-upgrade/upgrade_client.md + - Uninstall: - Uninstall PMM Client: - Docker: uninstall-pmm/uninstall_docker.md @@ -310,6 +312,7 @@ nav: - pmm-admin/security/index.md - pmm-admin/security/ssl_encryption.md - pmm-admin/security/grafana_cookies.md + - pmm-admin/security/data_encryption.md - Percona Platform: - configure-pmm/percona_platform/integrate_with_percona_platform.md - configure-pmm/percona_platform/check_percona_platform.md