diff --git a/docs/release-notes/2.43.0.md b/docs/release-notes/2.43.0.md deleted file mode 100644 index e9df9d8bd7..0000000000 --- a/docs/release-notes/2.43.0.md +++ /dev/null @@ -1,218 +0,0 @@ -# Percona Monitoring and Management 2.43.0 - -| **Release date** | August , 2024 | -| -----------------| ----------------------------------------------------------------------------------------------- | -| **Installation** | [Installing Percona Monitoring and Management](../quickstart/index.md) | - -Percona Monitoring and Management (PMM) is an open source database monitoring, management, and observability solution for MySQL, PostgreSQL, and MongoDB. - -It enables you to observe the health of your database systems, explore new patterns in their behavior, troubleshoot them and execute database management operations regardless of whether your databases are located on-premises or in the cloud. - -## What's new in this release - -PMM 2.43 brings a host of updates, including redesigned dashboards, new collectors and metrics, enhanced troubleshooting capabilities, strengthened security, and expanded platform support with official ARM compatibility for PMM Client. - -Additionally, it features many bug fixes and performance enhancements to improve your user experience. - -### MongoDB dashboard improvements and GA of recent experimental dashboard - -This update introduces significant enhancements to MongoDB monitoring, focusing on redesigned dashboards, streamlined navigation, and general availability of previously experimental dashboards. - -#### Redesigned dashboards - -We've overhauled two critical MongoDB dashboards to provide more value, especially for complex, multi-environment setups: - -- **Replica Set Summary** -- **Sharded Cluster Summary** (formerly Cluster Summary) - -These dashboards now offer enhanced usability, improved insights, and optimized visualizations for complex environments. They focus on highlighting potential database issues for faster resolution and provide centralized, actionable insights without clutter. - -#### General availability of Experimental dashboards - -The redesigned dashboards, along with the following previously experimental dashboards, are now generally available: - -- **MongoDB Oplog Details** -- **MongoDB Collection Overview** -- **Replica Set Summary** -- **Sharded Cluster Summary** (formerly Cluster Summary) - -#### Accessing the new dashboards - -The updated dashboards are in the **MongoDB** and **Dashboards** sections of the main menu. They replace the previous versions as the default dashboards for MongoDB monitoring. - -The old dashboards have been moved to the **Experimental** folder and renamed with **(Old)** appended to their names. Future releases will remove these older versions. - -#### Updated MongoDB menu structure - -To complement the dashboard improvements, we've also restructured the MongoDB section on the main menu for better navigation and accessibility: - -- Reorganized menu for a more intuitive navigation, prioritizing the three updated GA dashboards above. -- Decluttered view by moving older dashboards to the **Experimental** folder or removing them from the menu. -- Added **MongoDB Oplog Details**, **MongoDB Collection Overview**, and **MongoDB Instance Summary** to the main menu - -![New MongoDB menu structure](../images/new_Mongo_menu.png) - -We encourage you to start using the new dashboards to benefit from their enhanced monitoring capabilities. We also invite you to share your feedback in the [PMM forum](https://forums.percona.com/c/percona-monitoring-and-management-pmm/percona-monitoring-and-management-pmm-v2/31). - -### Repository changes for PMM: Transition to dedicated `pmm2-client` repository - - -Effective July 1, 2024, Percona has discontinued updates for the original Percona (https://repo.percona.com/percona/) and tools (https://repo.percona.com/tools/) repositories in favor of dedicated product repositories. This change streamlines our repository management and improves efficiency across our product ecosystem. - -For PMM users, this means you can now access the most up-to-date and secure versions of PMM exclusively from the dedicated [repo.percona.com/pmm2-client](`pmm2-client`) repository. To facilitate a smooth transition to this repo, we have developed an automated script that: - -1. Checks installed packages and their repositories -2. Identifies PMM-related packages that should be installed from the `pmm2-client` repository -3. Provides instructions for enabling the correct repository - -To ensure your PMM installation remains secure and up-to-date, [download this script from GitHub](https://raw.githubusercontent.com/Percona-Lab/release-aux/main/scripts/check_percona_packages.py) and run it on your system. - -For detailed instructions and more information about this change, check out [our recent blog post](https://www.percona.com/blog/ensure-the-correct-repositories-are-enabled-for-percona-packages/) and [updated documentation](). - -### Improved troubleshooting - -We've enhanced our troubleshooting capabilities to provide you with better insights and more efficient problem-solving tools: - -#### Enhanced PMM Server logs - -The default number of log lines for each log file returned by `httsp:///logs.zip` endpoint has been increased from 1,000 to 50,000. - -Additionally, the endpoint now includes a customizable line-count parameter in the download URL, allowing you to specify a custom number of log lines or opt for unlimited log size. For more information, see the [API documentation](https://percona-pmm.readme.io/reference/logs). - -#### Streamlined Kubernetes diagnostics - -New PMM client docker images now include essential troubleshooting tools: - -- `tar` enables easier file transfer in and out of containers using the `kubectl cp` command. -- `curl` allows direct checking of exporters to verify their proper functioning. - -### Improved security - -This update addresses several security issues related to the GNU C Library (Glibc), specifically affecting the Name Service Cache Daemon (nscd). Additionally, it resolves multiple security vulnerabilities by upgrading various third-party packages. - -These enhancements strengthen the overall security of the PMM Server environment, although they do not directly impact PMM's core functionality. - -### Official ARM support for PMM Client -With the growing adoption of ARM in data centers and cloud environments, we are excited to announce official support for ARM architecture in PMM Clients. This enables you to seamlessly monitor ARM-based infrastructure, including popular cloud instances and emerging ARM-powered servers. - -Starting with version 2.43, PMM now includes pre-built binaries for ARM architecture. With this update, PMM Client features, such as `node_exporter` and `mysqld_exporter`, are fully supported and optimized for ARM platforms. Additionally, ARM-based PMM Clients seamlessly integrate with existing PMM Server installations, enabling unified monitoring across both x86 and ARM architectures. - -#### Upgrading and getting started -If you have been compiling PMM on ARM manually, you can now upgrade to the 2.43 release for official support. The [Set up PMM Client topic](../setting-up/client/index.md) now also includes ARM-specific instructions for new installations. - -### New MongoDB collector: CurrentOp - -The MongoDB exporter now includes the **CurrentOp** collector, offering visibility into active operations, including the new `mongodb_currentop_query_uptime` metric. - -To start the MongoDB exporter with the CurrentOp collector enabled, use the `--enable-all-collectors` flag when adding MongoDB services to your PMM instance: - -```sh -pmm-admin add mongodb --enable-all-collectors ... -``` - -Specifying a limit with `--max-collections` for this collector is not necessary. - -!!! note "Operation collection limitation" -To minimize impact on disk usage, the CurrentOp collector is designed to collect only operations that have been running for longer than 1 minute. This limitation helps focus on potentially problematic long-running operations while keeping data volume manageable. - -For more information on MongoDB collectors and metrics, see the [pmm-admin commands documentation](../use/commamds/pmm-admin.md). - -### Monitoring for Percona Backup for MongoDB -PMM now supports monitoring your Percona Backup for MongoDB (PBM) setup and provides PBM-related metrics such as `pbm-agent` statuses, PITR configuration, and backup statuses. -This is made possible via a new PBM collector in MongoDB exporter that gives you visibility to your PBM setup via these metrics: -- `mongodb_pbm_cluster_backup_configured` -- `mongodb_pbm_agent_status` -- `mongodb_pbm_cluster_pitr_backup_enabled` -- `mongodb_pbm_backup_size` -- `mongodb_pbm_backup_duration_seconds` - -These metrics are enabled by default. If you're already running Percona Backup for MongoDB, you'll automatically receive these metrics without any additional configuration. -## Improvements - -- [PMM-13133](https://perconadev.atlassian.net/browse/PMM-13133) - - -- [PMM-13054](https://perconadev.atlassian.net/browse/PMM-13054) - The default number of log lines for each log file returned by `httsp:///logs.zip` endpoint has been increased from 1,000 to 50,000. - -Additionally, the endpoint now includes a customizable line-count parameter in the download URL, allowing you to specify a custom number of log lines or opt for unlimited log size. For more information, see the [API documentation](https://percona-pmm.readme.io/reference/logs). - -- [PMM-13159](https://perconadev.atlassian.net/browse/PMM-13159) - We have removed the experimental MongoDB **Collection Details** dashboard from PMM. You can now find up-to-date collection information on the new Mongo **Cluster Summary** dashboard, which provides a more comprehensive and accurate view of MongoDB collection metrics. - -If you have been using the **Collection Details** dashboard, make sure to now check the new **MongoDB Cluster Summary** dashboard for similar information. - - -## Maintenance - -### QAN update: Upgrade to `pg_query_go` v5 and impact on PostgreSQL 9.x - -As part of our ongoing maintenance efforts, we have upgraded the `pg_query_go` package to version 5. This latest version helps parse PostgreSQL queries in QAN, provides improved functionality, and enables subsequent upgrades of important dependencies. - -However, with this change, QAN will no longer be able to list PostgreSQL database tables for versions 9.4, 9.5, and 9.6. Since all PostgreSQL 9.x versions have already reached their end-of-life status, we recommend upgrading to a supported version of PostgreSQL. - -If you're looking to upgrade, you can easily [install the latest version of Percona Distribution for PostgreSQL](https://docs.percona.com/postgresql/16/installing.html). - - -## Improvements - -- [PMM-13257](https://perconadev.atlassian.net/browse/PMM-13257): [Dashboards] - PMM 2.43 delivers refined MongoDB dashboards with standardized layouts, improved visual consistency, and enhanced usability across Replica Set, Cluster, Collections, and Oplog views, ensuring a more intuitive and efficient monitoring experience. - -- [PMM-13003](https://perconadev.atlassian.net/browse/PMM-13003): [Dashboards] - The **MongoDB ReplSet Summary** dashboard now features a clearer, more organized layout with separate rows for CPU usage, CPU saturation, disk I/O, and network traffic for each node in replica sets with more than three nodes, improving visibility and analysis of multi-node deployments. - -- [PMM-12982](https://perconadev.atlassian.net/browse/PMM-12982): [Dashboards] - The **MongoDB ReplSet Summary** dashboard now displays replica set roles (Primary, Secondary, Arbiter) for each node, enhancing visibility and simplifying identification of node functions within the replica set topology. - -- [PMM-13258](https://perconadev.atlassian.net/browse/PMM-13258): [Dashboards] - Revamped **MongoDB** dashboard structure, featuring new and updated dashboards for improved monitoring of various MongoDB aspects including replicas, sharded clusters, collections, and oplogs, while moving older dashboards to the **Experimental** folder. - -- [PMM-13227](https://perconadev.atlassian.net/browse/PMM-13227): [Dashboards] - Renamed the **MongoDB Cluster Summary** dashboard to **MongoDB Sharded Cluster Summary** to more accurately reflect its focus on sharded cluster environments, reducing potential confusion for users monitoring different MongoDB topologies. - -- [PMM-13217](https://perconadev.atlassian.net/browse/PMM-13217): [Dashboards] - The **MongoDB Sharded Cluster Summary** dashboard now displays the versions of mongoS routers alongside shard and config server versions, providing a more comprehensive view of the entire sharded cluster infrastructure. - -- [PMM-13183](https://perconadev.atlassian.net/browse/PMM-13183): [Dashboards] - The **Node States** chart in the **MongoDB ReplSet Summary** dashboard now auto-adjusts its size to display all nodes without scrolling, enhancing visibility and ease of monitoring for larger replica sets. - -- [PMM-13029](https://perconadev.atlassian.net/browse/PMM-13029): [Dashboards] - Improved filtering consistency across all charts on the **MongoDB Oplog Details** dashboard, including the **Oplog GB/Hour** view, ensuring accurate data representation for selected MongoDB nodes. - -- [PMM-13159](https://perconadev.atlassian.net/browse/PMM-13159) [Dashboards] - We have removed the experimental MongoDB **Collection Details** dashboard from PMM. You can now find up-to-date collection information on the new Mongo **Cluster Summary** dashboard, which provides a more comprehensive and accurate view of MongoDB collection metrics. If you have been using the **Collection Details** dashboard, make sure to now check the new **MongoDB Cluster Summary** dashboard for similar information. - -- [PMM-13030](https://perconadev.atlassian.net/browse/PMM-13030): [Dashboards] - The **MongoDB Collections Overview** dashboard has been refined to ensure consistent data filtering across all charts, including **Top 5 Hottest Collections** views, aligning with user-selected database contexts for improved clarity and more accurate per-database analysis. - -- [PMM-13243](https://perconadev.atlassian.net/browse/PMM-13258) - Improved identification and monitoring of MongoDB cluster member roles, particularly for mongos instances, enabling clearer topology visualization and laying the groundwork for more precise alerting in sharded cluster environments. - -- [PMM-12333](https://perconadev.atlassian.net/browse/PMM-12333): [Installation] - The PMM client tarball installation process has been improved with more user-friendly features, including clearer error messages for permission issues, a helpful usage guide, and better overall guidance, making the setup process more intuitive and less error-prone for users. - -- [PMM-12957](https://perconadev.atlassian.net/browse/PMM-12957) - Introduced alerting capabilities for Percona Backup for MongoDB (PBM), leveraging newly added PBM-specific metrics to enable proactive monitoring of backup statuses, configurations, and performance across MongoDB deployments. - -- [PMM-13054](https://perconadev.atlassian.net/browse/PMM-13054) - The default number of log lines returned by the `/logs.zip` endpoint has been increased from 1,000 to 50,000, with an added option to customize the line count or allow unlimited log size via a parameter in the download URL. - -- [PMM-13292](https://perconadev.atlassian.net/browse/PMM-13292) - Introduced an improved mechanism to resolve port conflicts when starting multiple PMM agents on the same machine, enhancing reliability and reducing manual intervention in complex monitoring setups. - -- [PMM-13141](https://perconadev.atlassian.net/browse/PMM-13141) - Introduced new MongoDB metrics for Feature Compatibility Version (FCV), enhancing monitoring capabilities for multi-version deployments. -This metric, collected automatically via the MongoDB exporter, provides insights into individual node compatibility and supports upcoming PMM advisors. - - -### Fixed issues - -- [PMM-13111](https://perconadev.atlassian.net/browse/PMM-13111) - Fixed an issue with `--disable-collectors` flag not supporting new collectors introduced in the recent `postgres_exporter` upgrade. - -- [PMM-13277](https://perconadev.atlassian.net/browse/PMM-13277) - PMM 2.43 is now available on the AWS Marketplace, resolving the previous temporary unavailability issue of PMM 2.42.0. Users can directly install or upgrade to PMM 2.43.0 through AWS Marketplace or the PMM UI for access to the latest features and improvements. - -- [PMM-13246](https://perconadev.atlassian.net/browse/PMM-13246) - Addressed four security vulnerabilities (CVEs) related to the GNU C Library (Glibc), specifically affecting the Name Service Cache Daemon (nscd): - - - [CVE-2024-33599](https://nvd.nist.gov/vuln/detail/CVE-2024-33599) - - [CVE-2024-33600](https://nvd.nist.gov/vuln/detail/CVE-2024-33600) - - [CVE-2024-33601](https://nvd.nist.gov/vuln/detail/CVE-2024-33601) - - [CVE-2024-33602](https://nvd.nist.gov/vuln/detail/CVE-2024-33602) - -- [PMM-13002](https://perconadev.atlassian.net/browse/PMM-13246): [Dashboards] - Fixed a bug in the **MongoDB ReplSet Summary** dashboard where the **Node Summary** section only displayed information for one node. It now correctly shows data for all nodes in a replica set when **All** is selected, providing a comprehensive view of multi-node deployments. - -- [PMM-13255](https://perconadev.atlassian.net/browse/PMM-13255) - Resolved two issues with the MongoDB Replication Lag Alert: one where an error occurred during the import of the alert rule template, and another where the alert description displayed an incorrect current value for the replication lag. - -- [PMM-13288](https://perconadev.atlassian.net/browse/PMM-13288) - Fixed an issue where queries longer than 2048 characters in PostgreSQL were not properly parsed for table extraction, now allowing accurate monitoring and analysis of long queries without generating error messages in logs. - -- [PMM-12965](https://perconadev.atlassian.net/browse/PMM-12965) - We've improved the **MongoDB replication lag is high** alert template to make sure it: - -- now triggers only for `SECONDARY` nodes that are up and exceed the lag threshold, eliminating false alarms during maintenance. -- excludes `PRIMARY` nodes from alerts, as they cannot lag behind themselves. - -To ensure you're using the updated alert logic, make sure to recreate any alerts based on this alert rule template. - -- [PMM-12451](https://perconadev.atlassian.net/browse/PMM-12451) and [PMM-13017](https://perconadev.atlassian.net/browse/PMM-13017) - Resolved an issue with parsing JSON objects into the correct data types and aligned the explain functionality with the official MongoDB client. These updates enhance consistency with MongoDB's native tools and provide improved performance insights. - -- [PMM-13071](https://perconadev.atlassian.net/browse/PMM-13071) - The **Explain** tab on the Query Analytics (QAN) page now properly handles unsupported MongoDB query types. For operations like `INSERT`, which don’t support explain functionality, you will now see a clear message saying that the operation is not explainable. This replaces the previous, confusing error message about duplicate BSON fields, offering more accurate feedback in QAN. diff --git a/docs/release-notes/3.0.0.Beta.md b/docs/release-notes/3.0.0.Beta.md new file mode 100644 index 0000000000..87a713fe5b --- /dev/null +++ b/docs/release-notes/3.0.0.Beta.md @@ -0,0 +1,161 @@ +--- +title: Percona Monitoring and Management v3 API release notes +slug: release-notes-3.0.0.Beta +categorySlug: release-notes +hidden: 0 +--- +## Breaking API changes + +### Removed database ID prefixes + +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`. + +This change affects various components, including nodes, agents, services, and backup-related entities. As a result: + +- 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 + +#### Impact + +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. + +### Simplified boolean feature controls + +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. + +This change affects various API endpoints that control feature toggles and how we handle primitive types. As a result: + +- 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 + +#### Example of new format + +```json +{"enable_feature": true} // To enable a feature +{"enable_feature": false} // To disable a feature +``` + +#### Impact + +Ensure you update any custom scripts, integrations, or frontend code that interact with feature toggles in the API. + +Review your codebase for any logic that relies on the previous dual boolean system and update accordingly. + +### Consistent field emission in API responses + +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: + +- 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 + +#### Example of new response format + +```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 + } +} +``` + +#### Impact + +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. + +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. + +### Removed Inventory API topics from documentation + +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. + +### Streamlined API endpoints for Services, Nodes, and Agents + +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. \ No newline at end of file diff --git a/docs/release-notes/new_Mongo_menu.png b/docs/release-notes/new_Mongo_menu.png deleted file mode 100644 index 17b190ef51..0000000000 Binary files a/docs/release-notes/new_Mongo_menu.png and /dev/null differ