From 0b50a47c39d4f3adcd6ecf1d6fd78e0d5d1d7d59 Mon Sep 17 00:00:00 2001 From: Catalina A Date: Fri, 7 Mar 2025 15:21:03 +0200 Subject: [PATCH 1/2] Rel Notes for extended metrics and labels for MongoDB QAN --- documentation/docs/release-notes/3.1.0.md | 28 +++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/documentation/docs/release-notes/3.1.0.md b/documentation/docs/release-notes/3.1.0.md index 3e57100279..cb8f015f29 100644 --- a/documentation/docs/release-notes/3.1.0.md +++ b/documentation/docs/release-notes/3.1.0.md @@ -49,6 +49,34 @@ This enhancement provides a more accurate and intuitive visualization of your Mo ![Topology section](Topology.png) +### Extended metrics and labels for MongoDB Query Analytics (QAN) + +We've added new metrics and filters to QAN that expose important query execution details, highlighting inefficient execution paths, providing detailed lock and storage metrics. With the new filters, you can also easily identify these problematic queries by application, client, or user: + + +#### Additional MongoDB QAN metrics +The following metrics are now available in QAN for MongoDB queries: + +- `docs_examined`: number of documents scanned during query execution +- `keys_examined`: number of index entries scanned +- `nreturned`: number of documents returned by the query +- `response_length`: size of the response in bytes +- `millis`: query execution time in milliseconds +- `locks_global_acquire_count_read_shared`: global read lock acquisition count +- `locks_global_acquire_count_write_shared`: global write lock acquisition count +- `locks_database_acquire_count_read_shared`: database read lock acquisition count +- `locks_database_acquire_wait_count_read_shared`: database read lock wait count +- `locks_database_time_acquiring_micros_read_shared`: time spent acquiring database locks in microseconds +- `locks_collection_acquire_count_read_shared`: collection read lock acquisition count +- `storage_bytes_read`: amount of data read from storage in bytes +- `storage_time_reading_micros`: time spent reading from storage in microseconds + +#### New QAN filter categories +QAN now includes additional filter options to help you identify problematic queries by source: + +- **Application Name**: Filter queries by the application that generated them +- **Client Host**: Filter queries by the client IP address +- **User Name**: Filter queries by the database user who executed the query ## Improvements From 2babc37dced598fdaec68d6e720425cdb2322b18 Mon Sep 17 00:00:00 2001 From: Catalina A Date: Mon, 10 Mar 2025 13:11:18 +0200 Subject: [PATCH 2/2] Improved wording --- documentation/docs/release-notes/3.1.0.md | 49 ++++++++++---------- documentation/docs/use/qan/panels/filters.md | 49 ++++++++++++++++++-- 2 files changed, 70 insertions(+), 28 deletions(-) diff --git a/documentation/docs/release-notes/3.1.0.md b/documentation/docs/release-notes/3.1.0.md index cb8f015f29..5075054057 100644 --- a/documentation/docs/release-notes/3.1.0.md +++ b/documentation/docs/release-notes/3.1.0.md @@ -51,32 +51,33 @@ This enhancement provides a more accurate and intuitive visualization of your Mo ### Extended metrics and labels for MongoDB Query Analytics (QAN) -We've added new metrics and filters to QAN that expose important query execution details, highlighting inefficient execution paths, providing detailed lock and storage metrics. With the new filters, you can also easily identify these problematic queries by application, client, or user: - +We've added new metrics and filters to the [QAN dashboard](../use/qan/index.md) that expose important query execution details to highlight inefficient execution paths and provide detailed lock and storage metrics. With the new filters, you can easily identify problematic queries by application, client, or user: #### Additional MongoDB QAN metrics -The following metrics are now available in QAN for MongoDB queries: - -- `docs_examined`: number of documents scanned during query execution -- `keys_examined`: number of index entries scanned -- `nreturned`: number of documents returned by the query -- `response_length`: size of the response in bytes -- `millis`: query execution time in milliseconds -- `locks_global_acquire_count_read_shared`: global read lock acquisition count -- `locks_global_acquire_count_write_shared`: global write lock acquisition count -- `locks_database_acquire_count_read_shared`: database read lock acquisition count -- `locks_database_acquire_wait_count_read_shared`: database read lock wait count -- `locks_database_time_acquiring_micros_read_shared`: time spent acquiring database locks in microseconds -- `locks_collection_acquire_count_read_shared`: collection read lock acquisition count -- `storage_bytes_read`: amount of data read from storage in bytes -- `storage_time_reading_micros`: time spent reading from storage in microseconds - -#### New QAN filter categories -QAN now includes additional filter options to help you identify problematic queries by source: - -- **Application Name**: Filter queries by the application that generated them -- **Client Host**: Filter queries by the client IP address -- **User Name**: Filter queries by the database user who executed the query +The **Query Details** section of the QAN dashboard now includes these additional metrics: + +- **Docs Examined**: number of examined documents during query execution +- **Keys Examined**: number of index keys scanned during query execution +- **Docs Returned**: number of returned documents by the query +- **Response Length**: size of the response in bytes +- **Locks Global Acquire Count Read Shared**: number of times a global read lock was acquired during query execution +- **Locks Global Acquire Count Write Shared**: number of times a global write lock was acquired during query execution +- **Locks Database Acquire Count Read Shared**: number of times a read lock was acquired at the database level during query execution +- **Locks Database Acquire Wait Count Read Shared**: number of times a read lock at the database level was requested but had to wait before being granted +- **Locks Database Time Acquiring Micros Read Shared**: indicates the time spent acquiring a read lock at the database level during an operation +- **Locks Collection Acquire Count Read Shared**: number of times a read lock was acquired on a specific collection during operations +- **Storage Bytes Read**: total number of bytes read from storage during a specific operation +- **Storage Time Reading Micros**: indicates the time spent reading data from storage during an operation + +#### New MongoDB QAN filter categories + +The QAN dashboard now includes several additional MongoDB-specific filter options: + +- **Plan Summary**: filters queries by execution plan type (COLLSCAN, IXSCAN, etc.) to easily identify inefficient full collection scans +- **Application Name**: filters queries by the application name that generated them +- **User**: filters queries by the database user who executed the query +- **Database**: filters queries by specific database + ## Improvements diff --git a/documentation/docs/use/qan/panels/filters.md b/documentation/docs/use/qan/panels/filters.md index 9f2672e54c..d3f2883295 100644 --- a/documentation/docs/use/qan/panels/filters.md +++ b/documentation/docs/use/qan/panels/filters.md @@ -1,8 +1,13 @@ -# Filters Panel +# QAN Filters panel + +The Filters panel on the left hand side of the [QAN dashboard](../../qan/index.md) helps you narrow down query data to focus on specific metrics, database instances, or performance issues. + ![!image](../../../images/PMM_Query_Analytics_Panels_Filters.jpg) -- The **Filter** panel on the left hand side of the dashboard lists the filters grouped by category. It also shows the percentage of the main metrics (explained below). If you select a different metric, the percentages on the left panel will change as per this metric. When you select a metric, it reduces the overview list as per the matching filter. +## Understanding filters + +- The **Filter** panel lists the filters grouped by category. It also shows the percentage of the main metrics (explained below). If you select a different metric, the percentages on the left panel will change as per this metric. When you select a metric, it reduces the overview list as per the matching filter. - The first five of each category are shown. If there are more, the list is expanded by clicking **Show all** beside the category name, and collapsed again with **Show top 5**. - Applying a filter may make other filters inapplicable. These become grayed out and inactive. - Click the chart symbol to navigate directly to an item's associated dashboard. @@ -10,6 +15,42 @@ ![!image](../../../images/PMM_Query_Analytics_Time_Range.jpg) +## Available filter groups +The available filter groups depend on the database type you're monitoring. + +### Common filter groups +These filter groups are available for all database types: + +- **Environment** +- **Cluster** +- **Replication Set** +- **Database** +- **Schema** +- **Node Name** +- **Service Name** +- **Client Host** +- **Username** +- **Service Type** +- **Node Type** +- **City** +- **AZ** + +### MySQL-specific filter groups + + + +- **Command Class**: filters by SQL command class (SELECT, INSERT, UPDATE, etc.) +- **Fingerprint**: Filters by normalized query pattern + +### PostgreSQL-specific filter groups + +- **Application** +- **Command Type** +- **Tables** + +### MongoDB-specific filter groups +- **Plan Summary**: filters queries by execution plan type (COLLSCAN, IXSCAN, etc.) to easily identify inefficient full collection scans +- **Client Application Name**: filters queries by the application name that generated them ## Custom filter groups @@ -51,7 +92,7 @@ In the output, you can see another custom group in the `OperationSystem` filter. ### Enabling custom filter groups -- **CLI**: While adding a service through CLI use the flag `comments-parsing`. Possible values are `on/off`. +- **via CLI**: While adding a service through CLI use the flag `comments-parsing`. Possible values are `on/off`. Example for adding MySQL with comments parsing on: @@ -59,7 +100,7 @@ In the output, you can see another custom group in the `OperationSystem` filter. pmm-admin add mysql --username=root --password=root-password --comments-parsing="on" ``` -- **UI**: While adding a service through the UI you will see new checkbox to `enable/disable` comments parsing for current service. +- **via UI**: While adding a service through the UI you will see new checkbox to `enable/disable` comments parsing for current service. ![!image](../../../images/PMM_QAN_Parsing.png)