diff --git a/documentation/docs/admin/_images/PMM-manage-users.png b/documentation/docs/admin/_images/PMM-manage-users.png deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/documentation/docs/admin/roles/access-control/assign_roles.md b/documentation/docs/admin/roles/access-control/assign_roles.md index 07ea37bd501..bae490387d4 100644 --- a/documentation/docs/admin/roles/access-control/assign_roles.md +++ b/documentation/docs/admin/roles/access-control/assign_roles.md @@ -1,11 +1,12 @@ -# Assign roles to users +# Assign access roles to users To assign access roles to users: {.power-number} -1. From [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option. +1. From the [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option. 2. Go to **Administration > Users and access > Users**. +3. Click on the user you want to assign roles to. +4. From the **Roles** drop-down select the appropriate roles. +5. Verify the assigned roles appear in the **Access Role** column. -3. Select the **User** you want to assign to a role from the dropdown. You can assign several roles to a user. - - ![!](../../../images/PMM_access_control_select_role.png) \ No newline at end of file +![PMM Access Control - Assign role](../../../images/lbac/PMM_access_control_select_role.png) diff --git a/documentation/docs/admin/roles/access-control/config_access_cntrl.md b/documentation/docs/admin/roles/access-control/config_access_cntrl.md deleted file mode 100644 index 63ffeb66595..00000000000 --- a/documentation/docs/admin/roles/access-control/config_access_cntrl.md +++ /dev/null @@ -1,31 +0,0 @@ -# Configure access control - -You can configure access control in PMM as follows: - -- Docker -- User Interface - -## Configure access control using Docker - -To configure access roles in a ``pmm-server`` docker container, pass an additional environment variable ``ENABLE_RBAC=1`` when starting the container. - -```sh -docker run … -e ENABLE_RBAC=1 -``` - -For compose add an additional variable: - -``` -services: - pmm-server: - … - environment: - … - ENABLE_RBAC=1 -``` - -## Configure access control from the UI - -To configure access control from the UI: - -From the main menu, go to **PMM Configuration > Settings > Advanced Settings > Access Control** and click toggle. \ No newline at end of file diff --git a/documentation/docs/admin/roles/access-control/create_roles.md b/documentation/docs/admin/roles/access-control/create_roles.md index 4b14d074df6..928a2934cf4 100644 --- a/documentation/docs/admin/roles/access-control/create_roles.md +++ b/documentation/docs/admin/roles/access-control/create_roles.md @@ -1,28 +1,34 @@ # Create access roles -Roles are a vital part of Access control. Roles provide users with access to specific, role-based metrics. +Roles are essential components of PMM's access control system. They allow you to limit users' access to specific metrics based on their responsibilities and permissions. -To create access roles in PMM, do the following: +## Before you begin + +- You must have administrator privileges to create roles. For more information, see [Manage users](../../manage-users/index.md). +- Access control must be enabled in PMM settings + +## Create a new role + +To create access roles in PMM: {.power-number} -1. From the [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option. +1. From the [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access control** option. 2. Go to **Administration > Users and access > Access Roles**. - ![!](../../../images/PMM_access_control_create_role.png) + ![PMM Access Control - Create role](../../../images/lbac/PMM_access_control_create_role.png) 3. Click **Create**. 4. On the **Create role** page, enter the Role name and Role description. -5. Select the following from the drop-downs for metrics access: - - Label - - Operator - - Value of the label +5. Configure metrics access by setting label selectors: + - select a Label (e.g., "service_name", "environment") + - choose an Operator (e.g., "=", "!=", "=~") + - enter the Value for the selected label If you want to add more than one label for a role, click *+* and select the values from the drop-down. For information on how the Prometheus selectors work, see [Prometheus selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-series-selectors). -6. Click **Create** role. +6. Review your selections, then click **Create** to finalize the role. + -!!! note alert alert-primary "Note" - To create roles, you must have admin privileges. For more information, see [Manage users](../../manage-users/index.md). \ No newline at end of file diff --git a/documentation/docs/admin/roles/access-control/enable_access_control.md b/documentation/docs/admin/roles/access-control/enable_access_control.md new file mode 100644 index 00000000000..408295e4f2e --- /dev/null +++ b/documentation/docs/admin/roles/access-control/enable_access_control.md @@ -0,0 +1,51 @@ +# Enable access control + +Access control in PMM lets you restrict user access to specific metrics and Query Analytics data based on their roles. +Choose your preferred method to enable this feature: + +=== "Via Docker" + + When deploying PMM Server with Docker, enable access control by passing an environment variable: + + ```sh + docker run -d \ + --name pmm-server \ + -p 443:8443 \ + -e PMM_ENABLE_ACCESS_CONTROL=1 \ + percona/pmm-server:latest + ``` + +=== "Via Docker Compose" + + For Docker Compose deployments, add the environment variable to your `docker-compose.yml` file: + + ```yaml + services: + pmm-server: + image: percona/pmm-server:latest + ports: + - "443:8443" + environment: + - PMM_ENABLE_ACCESS_CONTROL=1 + volumes: + - pmm-data:/srv + ``` + +=== "Via user interface" + + To enable access control from the PMM web interface: + {.power-number} + + 1. Log in to PMM with an administrator account. + 2. From the main menu, go to **PMM Configuration > Settings > Advanced Settings > Access Control**. + 3. Toggle the toggle. + 4. Click **Apply changes** to save your settings. + +## After enabling access control + +Once access control is enabled: + +- All existing users will have full access until you assign specific roles. +- [Create access roles](../access-control/create_roles.md) for different user types. +- [Assign the new roles](../index.md) to your PMM users. +- Test that restrictions work as expected. \ No newline at end of file diff --git a/documentation/docs/admin/roles/access-control/intro.md b/documentation/docs/admin/roles/access-control/intro.md index 9995bada638..47c51bfd6f7 100644 --- a/documentation/docs/admin/roles/access-control/intro.md +++ b/documentation/docs/admin/roles/access-control/intro.md @@ -1,13 +1,49 @@ -# About access control in PMM +# About label based access control (LBAC) in PMM -!!! caution alert alert-warning "Caution" - PMM Access Control is currently in [technical preview](../../../reference/glossary.md#technical-preview) and is subject to change. We recommend that early adopters use this feature for testing purposes only. +Access control in PMM allows you to manage access to data. By using access control you can restrict access to monitoring metrics and Query Analytics data. -Access control in PMM allows you to manage who has access to individual Prometheus (Victoria Metrics) metrics based on **labels**. Thus, access management provides a standardized way of granting, changing, and revoking access to metrics based on the role assigned to the users. +This is particularly important in environments where sensitive data is involved, and it helps ensure that only authorized users can access specific information, which is crucial for maintaining security and compliance. -The following topics are covered as part of access control: +## How LBAC works +PMM uses Prometheus label selectors to control access to metrics and Query Analytics data. -- [Configure access control](config_access_cntrl.md) -- [Labels for access control](labels.md) -- [Create access roles](create_roles.md) -- [Use case](usecase.md) \ No newline at end of file +Here's how LBAC works: +{.power-number} + +1. Create roles with label selectors. For example `environment=prod` for a specific environment or `service_type=mysql` for specific databases. +2. Assign roles to users based on their responsibilities. +3. Users see only the metrics and (Query Analytics) QAN data that match their role's label selectors. + +## Key benefits + +- Granular permissions: Restrict access to specific services, environments, or regions. +- Enhanced security: Prevent unauthorized access to sensitive database metrics and query data. +- Compliance support: Meet regulatory requirements for data access control. +- Team-specific views: Allow teams to focus only on their relevant systems and queries. +- Simplified management: Manage access through roles instead of individual user permissions. + +## Example scenarios + +| User type | Possible role configuration | What they can see | +|-----------|---------------------------|------------------| +| DBA team lead | All services across environments | Complete monitoring data for all databases and queries | +| MySQL administrators | `service_type=mysql` | Only MySQL-related metrics and queries | +| Production support | `environment=production` | Only production environment metrics and queries | +| Regional team | `region=us-east` | Only metrics and queries from a specific region | + +## Getting started with LBAC + +To implement label-based access control in PMM: +{.power-number} + +1. [Enable access control](enable_access_control.md) in your PMM settings +2. Learn about the [labels available for filtering](labels.md) +3. [Create access roles](create_roles.md) based on your organizational needs +4. Review common [use cases and examples](use_cases.md) for inspiration + +!!! tip "Best practice" + Start with broader access controls and refine them over time as you understand your organization's specific needs. Test LBAC behavior in both dashboards and QAN to ensure proper access control. + +## Related topics + +- [Manage PMM users](../../manage-users/index.md) diff --git a/documentation/docs/admin/roles/access-control/labels.md b/documentation/docs/admin/roles/access-control/labels.md index a6c2214f6e6..f49b46692de 100644 --- a/documentation/docs/admin/roles/access-control/labels.md +++ b/documentation/docs/admin/roles/access-control/labels.md @@ -1,41 +1,68 @@ # Labels for access control +Label-based access control in PMM allows you to precisely manage which monitoring data users can access based on their roles and responsibilities. +This feature is essential for organizations with multiple teams, compliance requirements, or where different users need different levels of visibility. -Label-based access control in PMM allows you to manage who has access to metrics based on labels. By creating roles, you can specify which data can be queried based on specific label criteria, for instance, allowing the QA team to view data related to test environments. - -With Label-based access control, you can associate multiple labels with a role, ensuring only data from series that match your defined labels is returned. +## How LBAC works +Access control in PMM uses Prometheus label selectors to filter metrics and Query Analytics data. +Here's how it works: +{.power-number} + +1. Create roles with specific label selectors. For example, you might allow the QA team to access only metrics related to test environments by assigning them a role with the `environment=test` label or limit visibility to metrics related only to MySQL services with the `service_type=mysql` label. +2. Assign roles to users based on their responsibilities. Each role can include multiple labels, and only data series matching all associated labels will be visible to users with that role. This ensures precise, fine-grained access control to your data. +3. Users see only the metrics and data that match their role's label selectors ## Standard vs custom labels -PMM supports standard as well as custom labels. PMM automatically assigns standard labels. You can also set standard labels when an object (Node, Service, or Agent) is created. Custom labels are assigned and updated only by a user. +PMM supports two types of labels for access control. When a user adds a service to monitoring, PMM automatically assigns standard labels based on the service type, such as `service_type`, `agent_type`, and `node_name`. Additional labels like `service_id` and `node_id` are also auto-generated by PMM. + +You can override some standard labels when creating objects such as Nodes, Services, or Agents. You can also define and assign custom labels. Unlike standard labels, custom labels are user-defined and can only be added or updated manually. + +Both standard and custom labels are propagated to the relevant metrics collected by the PMM Client. These labels are preserved during metric collection and can be used in PromQL queries. **Examples** +| **Label Type**| **Object**| **Label name** | **Example** | +|---------------|-----------|-----------------|--------------------------------------| +| **Standard** | Node | node_id | 5bdfb1b4-c6c4-4086-83a2-e8daa0b84d4b | +| **Standard** | Service | service_type | mysql, mongodb, postgresql etc. | +| **Custom** | Node, Service, Agent | Any string matching the regular expression:
[a-zA-Z_][a-zA-Z0-9_]*.
Also, it cannot start with two underscores.| owner="joe"
_rack="12345"| -| **Label Type**| **Object**| **Label name **| **Example** | -|----------|--------|-------|------------------------------| -| **Standard** | Node | node_id |123| -| | Service|service_type | - mysql, mongodb, postgresql etc. -| **Custom**| Node, Service, Agent| Any string matching regular expression:
[a-zA-Z_][a-zA-Z0-9_]*.
Also, it cannot start with two underscores.| owner="joe"
_rack="12345"| +## Adding labels when creating services -## Adding labels +You can add standard or custom labels while adding a service to monitoring in PMM. -You can add custom or standard labels in PMM while adding a service for monitoring in PMM. +=== "Using the PMM UI" + To set the labels via the user interface: + {.power-number} -### Using PMM UI + 1. From the **Main** menu, go to **PMM Configuration > PMM Services > Add Service**. -To set the labels using the user interface: -{.power-number} + 2. Select the service you want to monitor. + + 3. Complete the required connection details. + + 4. Enter standard labels via the input section `Labels`. + + 5. Enter custom labels via section `Custom labels`. + + ![PMM Inventory - Add Service](../../../images/lbac/PMM_access_control_add_labels_services.png) + +=== "Using pmm-admin" -1. From the **Main** menu, go to **PMM Configuration > PMM Services > Add Service**. + You can also add standard and custom labels using [pmm-admin](../../../use/commands/pmm-admin.md). -2. Select the service you want to add to PMM for monitoring. The page to add the service opens. +## Modifying existing labels +PMM allows modifying certain standard labels after a service is created: -3. Enter the details such as *Hostname, Service name, Port, Username, Password,* etc., along with Label or Custom labels. +- `environment` +- `cluster` +- `replication_set` +- `external_group` - ![!](../../../images/PMM_access_control_add_labels_services.png) +For other standard labels that cannot be modified directly, you must remove the service and re-add it with the desired labels. -### Using pmm-admin +This can be done either via PMM UI or via an [API endpoint](https://percona-pmm.readme.io/reference/changeservice). - You can also assign labels using [pmm-admin](../../../use/commands/pmm-admin.md). +Modifying the custom labels can be done as well via PMM UI of via the same [API endpoint](https://percona-pmm.readme.io/reference/changeservice). diff --git a/documentation/docs/admin/roles/access-control/manage_roles.md b/documentation/docs/admin/roles/access-control/manage_roles.md index 39990259eaf..e7e3a97b624 100644 --- a/documentation/docs/admin/roles/access-control/manage_roles.md +++ b/documentation/docs/admin/roles/access-control/manage_roles.md @@ -8,11 +8,12 @@ To edit access roles: {.power-number} 1. From [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option. + 2. Go to **Administration > Users and access > Access Roles**. 3. On the role you want to edit, click the **ellipsis (three vertical dots) > edit role** in the **Options** column. The **Edit** role page opens. - ![!](../../../images/PMM_access_control_edit_role.png) + ![PMM Access Control - Edit role](../../../images/lbac/PMM_access_control_edit_role.png) 4. Make the required changes to the role. @@ -26,7 +27,9 @@ To set a role as default, do the following: {.power-number} 1. From [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option. + 2. Go to **Administration > Users and access > Access Roles**. + 3. On the role you want to set as default, click the **ellipsis (three vertical dots) → set as default** in the **Options** column. diff --git a/documentation/docs/admin/roles/access-control/use_cases.md b/documentation/docs/admin/roles/access-control/use_cases.md new file mode 100644 index 00000000000..21bee9750ad --- /dev/null +++ b/documentation/docs/admin/roles/access-control/use_cases.md @@ -0,0 +1,39 @@ +# Implementing LBAC: practical scenarios + +Here are a few practical examples of how label-based access control can be implemented in PMM to meet specific organizational needs. + +## Infrastructure overview +The diagram below shows a sample infrastructure monitored by PMM. Notice how the metrics stored in VictoriaMetrics include labels like **environment** and **region** that can be used for access control. + + + ![PMM Access Control - Metrics collection](../../../images/lbac/pmm-lbac-collect-metrics.jpg) + +## Use case 1: Simple selectors + +This scenario demonstrates how to create three distinct roles with different levels of access: + +![PMM Access Control - Basic Roles](../../../images/lbac/pmm-lbac-query-metrics-1.jpg) + +| Role | Access needs | Label selectors | Effect | +|------|--------------|-----------------|--------| +| **Admin** | Complete visibility across all environments | `environment=prod` OR `environment=qa` | Full access to all metrics in both production and QA environments across all regions | +| **DBA** | Production database management | `environment=prod` | Access to all production metrics across all regions, but no visibility into QA | +| **QA** | Testing environment monitoring | `environment=qa` | Access to all QA metrics across all regions, but no visibility into production | + +This approach allows for a clear separation of responsibilities while ensuring each team has access to exactly what they need. + +## Use case 2 - Compound selectors + +This advanced use case demonstrates how compound selectors create more granular access control by combining multiple label conditions using logical operators (AND, OR). + +By requiring matches on multiple labels simultaneously, you can implement sophisticated access patterns that reflect real-world organizational structures and security requirements. + + +![PMM Access Control - Roles](../../../images/lbac/pmm-lbac-query-metrics-2.jpg) + + +| Role | Access needs | Label selectors | Effect | +|------|--------------|-----------------|--------| +| **Admin** | Complete visibility across all environments and regions | `environment=prod` OR `environment=qa` | Full access to all metrics in both production and QA environments across all regions | +| **DBA** | Production database management in EMEA region | `environment=prod` AND `region=emea` | Access only to production metrics in the EMEA region | +| **QA** | Testing environment monitoring in US-East region | `environment=qa` AND `region=us-east` | Access only to QA metrics in the US-East region | \ No newline at end of file diff --git a/documentation/docs/admin/roles/access-control/usecase.md b/documentation/docs/admin/roles/access-control/usecase.md deleted file mode 100644 index 4076ce5f295..00000000000 --- a/documentation/docs/admin/roles/access-control/usecase.md +++ /dev/null @@ -1,50 +0,0 @@ -# Use Case - -## Use case 1 - -This use case demonstrates the following scenario: - -**Labels** - -- Environments: **prod** and **qa** - -- Projects: **shop** and **bank** - -**Roles** - -- Roles: Admin, Dev and QA - -An overview of the infrastructure can be seen in the diagram below. PMM monitors several services. The metrics that are stored in VictoriaMetrics have the appropriate labels. - - ![!](../../../images/PMM_access_control_usecase_metrics.jpg) - - This diagram shows several roles within a company structure that have access to PMM, as well as the permissions they should be granted: - -- Admin role - has access to all the metrics -- DBA role - has access to all metrics within **env=prod** only -- QA role - has access to all metrics within **env=qa** only - - ![!](../../../images/PMM_access_control_usecase_roles.jpg) - - -## Use case 2 - -The use case demonstrates the following scenario: - -**Labels** - -- Environments: prod and dev - -- Services: postgresql and mysql - -**Roles** - -- role_postresql -- role_mysql - - -| |**Role assigned**|**Labels applied to the role**|**Accessible Metrics** | -|----------|--------|---------------------------------------------- |-------------------------------------------------------------------------------------------------------------| -| **User 1** | role_postresql|dev, service_name=postgresql|The metrics for service postgresql will be accessible.| -| **User 2** | role_mysql |prod, service_name=mysql|The metrics for service mysql will be accessible.| -| **User 3** | role_postgresql and role_mysql|dev, service_name=postgresql and
prod, service_name=mysql |The metrics for both the services mysql and postresql will be accessible.| diff --git a/documentation/docs/images/PMM_access_control_usecase_metrics.jpg b/documentation/docs/images/PMM_access_control_usecase_metrics.jpg deleted file mode 100644 index 6bd7473ff4a..00000000000 Binary files a/documentation/docs/images/PMM_access_control_usecase_metrics.jpg and /dev/null differ diff --git a/documentation/docs/images/PMM_access_control_usecase_roles.jpg b/documentation/docs/images/PMM_access_control_usecase_roles.jpg deleted file mode 100644 index 78338216c22..00000000000 Binary files a/documentation/docs/images/PMM_access_control_usecase_roles.jpg and /dev/null differ diff --git a/documentation/docs/images/PMM_access_control_add_labels_services.png b/documentation/docs/images/lbac/PMM_access_control_add_labels_services.png similarity index 100% rename from documentation/docs/images/PMM_access_control_add_labels_services.png rename to documentation/docs/images/lbac/PMM_access_control_add_labels_services.png diff --git a/documentation/docs/images/PMM_access_control_create_role.png b/documentation/docs/images/lbac/PMM_access_control_create_role.png similarity index 100% rename from documentation/docs/images/PMM_access_control_create_role.png rename to documentation/docs/images/lbac/PMM_access_control_create_role.png diff --git a/documentation/docs/images/PMM_access_control_edit_role.png b/documentation/docs/images/lbac/PMM_access_control_edit_role.png similarity index 100% rename from documentation/docs/images/PMM_access_control_edit_role.png rename to documentation/docs/images/lbac/PMM_access_control_edit_role.png diff --git a/documentation/docs/images/PMM_access_control_select_role.png b/documentation/docs/images/lbac/PMM_access_control_select_role.png similarity index 100% rename from documentation/docs/images/PMM_access_control_select_role.png rename to documentation/docs/images/lbac/PMM_access_control_select_role.png diff --git a/documentation/docs/images/lbac/pmm-lbac-collect-metrics.jpg b/documentation/docs/images/lbac/pmm-lbac-collect-metrics.jpg new file mode 100644 index 00000000000..aeea780984f Binary files /dev/null and b/documentation/docs/images/lbac/pmm-lbac-collect-metrics.jpg differ diff --git a/documentation/docs/images/lbac/pmm-lbac-query-metrics-1.jpg b/documentation/docs/images/lbac/pmm-lbac-query-metrics-1.jpg new file mode 100644 index 00000000000..ce396ad4bf6 Binary files /dev/null and b/documentation/docs/images/lbac/pmm-lbac-query-metrics-1.jpg differ diff --git a/documentation/docs/images/lbac/pmm-lbac-query-metrics-2.jpg b/documentation/docs/images/lbac/pmm-lbac-query-metrics-2.jpg new file mode 100644 index 00000000000..44ff87f347d Binary files /dev/null and b/documentation/docs/images/lbac/pmm-lbac-query-metrics-2.jpg differ diff --git a/documentation/docs/reference/ui/log_in.md b/documentation/docs/reference/ui/log_in.md index f926616c916..908db511ff1 100644 --- a/documentation/docs/reference/ui/log_in.md +++ b/documentation/docs/reference/ui/log_in.md @@ -3,26 +3,24 @@ To log into PMM: {.power-number} -1. Start a web browser and in the address bar enter the server name or IP address of the PMM Server host. +1. Start a web browser and enter the server name or IP address of the PMM Server host in the address bar. 2. The page loads showing the PMM log in screen. - ![!](../../images/PMM_Login.jpg) + ![PMM Login](../../images/PMM_Login.jpg) 3. Enter the username and password given to you by your system administrator. The defaults are: - - Username: `admin` - - - Password: `admin` + - Username: `admin` + - Password: `admin` 4. Click **Log in**. 5. If this is your first time logging in, you'll be asked to set a new password. We recommend you do. - - enter a new password in both fields and click **Submit**, or, - - - click **Skip** to use the default password. + - enter a new password in both fields and click **Submit**, or, + - click **Skip** to use the default password. 6. The PMM Home dashboard loads: - ![!PMM Home dashboard](../../images/PMM_Home_Dashboard.png) + ![PMM Home dashboard](../../images/PMM_Home_Dashboard.png) diff --git a/documentation/docs/reference/ui/ui_components.md b/documentation/docs/reference/ui/ui_components.md index 766ed84a6ba..95e5da3cd27 100644 --- a/documentation/docs/reference/ui/ui_components.md +++ b/documentation/docs/reference/ui/ui_components.md @@ -1,8 +1,8 @@ # UI components -Percona Monitoring and Management (PMM) provides a web-based user interface (UI), built on [Grafana](https://grafana.com/docs/grafana/latest/), for monitoring and managing your database environments. +This section explains how to access the interface, navigate the layout, and use the various controls within PMM. -Here's how the UI is laid out, and what the controls do: +Here's how the UI is laid out, and what the controls do: ![PMM Interface with numbered components](../../images/PMM_Home_Dashboard_Numbered.png) @@ -23,8 +23,8 @@ You'll find these options in the left-side menu: | | Starred | Mark important dashboards as favorites. Starred dashboards can be set as your home page and are visible to all users, helping teams identify important monitoring views. | | | Dashboards | Create and organize dashboards, create [folders](../../use/dashboards-panels/manage-dashboards/create-folders.md), import dashboards, create playlists, and manage snapshots. | | | Operating System (OS) | Monitor server-level metrics including CPU, memory, disk, and network performance. | -| | MySQL | View specialized dashboards for MySQL database performance monitoring. | -| | PostgreSQL | Access PostgreSQL-specific monitoring dashboards and metrics. | +| :simple-mysql: | MySQL | View specialized dashboards for MySQL database performance monitoring. | +| :simple-postgresql: | PostgreSQL | Access PostgreSQL-specific monitoring dashboards and metrics. | | | Query Analytics (QAN) | Analyze database queries over time, identify slow queries, optimize performance, and troubleshoot issues. | | | Explore | Run ad-hoc queries with [PromQL](https://prometheus.io/docs/prometheus/latest/querying/basics/) to investigate specific metrics without creating dashboards. | | | Drilldown | Run detailed analysis with specialized views for database metrics. This enables you to dive deeper into specific metrics by clicking through related data points and exploring underlying patterns. Learn more about drilling down into metrics in the [Grafana documentation](https://grafana.com/docs/grafana/latest/explore/simplified-exploration/metrics/drill-down-metrics/). | diff --git a/documentation/docs/use/qan/index.md b/documentation/docs/use/qan/index.md index 9d035a600cc..67c4904e073 100644 --- a/documentation/docs/use/qan/index.md +++ b/documentation/docs/use/qan/index.md @@ -1,11 +1,9 @@ -# About query analytics (QAN) +# About Query Analytics (QAN) The Query Analytics dashboard shows how queries are executed and where they spend their time. It helps you analyze database queries over time, optimize database performance, and find and remedy the source of problems. ![!image](../../images/PMM_Query_Analytics.jpg) -## Supported databases - Query Analytics supports MySQL, MongoDB and PostgreSQL with the following minimum requirements: === "MySQL requirements" @@ -37,16 +35,28 @@ Query Analytics supports MySQL, MongoDB and PostgreSQL with the following minimu ## Dashboard components Query Analytics displays metrics in both visual and numeric form. Performance-related characteristics appear as plotted graphics with summaries. +## Dashboard layout The dashboard contains three panels: - the [Filters panel](panels/filters.md) - the [Overview panel](panels/overview.md) - the [Details panel](panels/details.md) + ### Data retrieval delays Query Analytics data retrieval is not instantaneous because metrics are collected once per minute. When collection delays occur, no data is reported and gaps will appear in the sparkline. +## Label-based access control + +Query Analytics integrates with PMM's[label-based access control (LBAC)](../../admin/roles/access-control/intro.md) to enforce data security and user permissions. + +When LBAC is enabled: + +- users see only queries from databases and services permitted by their assigned roles +- filter dropdown options are dynamically restricted based on user permissions +- data visibility is controlled through Prometheus-style label selectors + ## Limitation: Missing query examples in MySQL Performance Schema When using MySQL's Performance Schema as the query source, you may encounter the message *“Sorry, no examples found”* in the QAN dashboard. This typically occurs due to the way MySQL handles query sampling and can be influenced by the volume of unique queries, and Performance Schema settings. @@ -87,3 +97,4 @@ PMM Agent includes a configurable **Performance Schema Refresh Rate** that can h If you're still missing some query examples, consider [using the slow query log (`slowlog`)](../../../docs/install-pmm/install-pmm-client/connect-database/mysql/mysql.md#configure-data-source) as the query source instead. The `slowlog` retains actual query texts over time and can help capture examples even when Performance Schema history buffers are exhausted. + diff --git a/documentation/docs/use/qan/panels/filters.md b/documentation/docs/use/qan/panels/filters.md index 1f25798412f..8d0b1fa17ce 100644 --- a/documentation/docs/use/qan/panels/filters.md +++ b/documentation/docs/use/qan/panels/filters.md @@ -2,12 +2,12 @@ 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) ## 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. +- When [label-based access control (LBAC)](../../../admin/roles/access-control/intro.md) is enabled, filter options are automatically limited to match your role's permissions. You will only see databases, services, and environments you have access to. - 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. diff --git a/documentation/mkdocs-base.yml b/documentation/mkdocs-base.yml index 3a40faea514..b23a59f2f3e 100644 --- a/documentation/mkdocs-base.yml +++ b/documentation/mkdocs-base.yml @@ -328,11 +328,11 @@ nav: - Label-based access control: - admin/roles/access-control/intro.md - admin/roles/access-control/labels.md - - admin/roles/access-control/config_access_cntrl.md + - admin/roles/access-control/enable_access_control.md - admin/roles/access-control/create_roles.md - admin/roles/access-control/manage_roles.md - admin/roles/access-control/assign_roles.md - - admin/roles/access-control/usecase.md + - admin/roles/access-control/use_cases.md - Troubleshoot: - troubleshoot/index.md