Advisors & Checks
Relevant source files
The following files were used as context for generating this wiki page:
Advisors & Checks is a core system within Percona Monitoring and Management (PMM) designed to provide automated insights and recommendations for monitored database environments. This system identifies potential security threats, performance degradation, data loss, and corruption by executing regular checks against connected database instances.
The system is architected to separate the high-level grouping (Advisors) from the executable logic (Checks). Advisors categorize findings into domains such as security, configuration, and performance, while Checks contain the technical scripts—often written in Starlark—that query database variables and return structured results.
Sources: README.md:29-31, managed/CONTRIBUTING.md:144-147, api/advisors/v1/advisors.proto:110-120
System Architecture
The architecture consists of the PMM Server (managed) which handles the management of check definitions, execution scheduling, and result aggregation. The API layer provides a gRPC and REST interface for the UI to interact with these results and configure check behaviors.
The diagram shows the flow from the UI configuration through the API to the execution of Starlark scripts against monitored database targets.
Sources: managed/CONTRIBUTING.md:15-18, managed/CONTRIBUTING.md:157-159, api/advisors/v1/advisors.proto:145-210
Key Components
| Component | Description |
|---|---|
| Advisor | A high-level entity representing a category of checks (e.g., Security, Performance). |
| Advisor Check | The individual unit of execution containing metadata, interval settings, and database family compatibility. |
| Check Script | Executable logic (typically YAML/Starlark) that defines database queries and result evaluation. |
| Advisor Service | The gRPC service responsible for listing, starting, and modifying check configurations. |
Sources: api/advisors/v1/advisors.proto:90-140, managed/CONTRIBUTING.md:175-180
Data Structures and API
The Advisor system utilizes specific Protobuf messages to manage metadata and check results.
Advisor and Check Definitions
Advisors are machine-readable IDs linked to human-readable summaries and descriptions. An Advisor contains a collection of AdvisorCheck objects.
message Advisor {
string name = 1;
string description = 2;
string summary = 3;
string category = 5;
repeated AdvisorCheck checks = 6;
}
message AdvisorCheck {
string name = 1;
bool enabled = 2;
string summary = 4;
AdvisorCheckInterval interval = 5;
AdvisorCheckFamily family = 6;
}
Sources: api/advisors/v1/advisors.proto:91-131
Execution Intervals and Families
Checks are categorized by the database family they support and their execution frequency.
| Interval Type | Value | Description |
|---|---|---|
RARE | 3 | Checks executed at long intervals to minimize resource impact. |
STANDARD | 1 | The default execution frequency. |
FREQUENT | 2 | Checks executed often to catch rapid state changes. |
| Family Type | Description |
|---|---|
MYSQL | Specifically for MySQL/Percona Server/MariaDB instances. |
POSTGRESQL | Specifically for PostgreSQL instances. |
MONGODB | Specifically for MongoDB instances. |
Sources: api/advisors/v1/advisors.proto:10-25, ui/apps/pmm/src/pages/settings/Settings.messages.ts:40-44
Check Implementation (YAML/Starlark)
Advisor checks are defined in YAML files that include metadata and a Starlark script section. These scripts often define queries (e.g., MYSQL_SHOW VARIABLES) and a check_context function to evaluate the query results.
checks:
- version: 2
name: mysql_configuration_log_verbosity
summary: Check log verbosity
family: MYSQL
queries:
- type: MYSQL_SHOW
query: VARIABLES
script: |
def check_log_error_verbosity(log_error_verbosity):
if log_error_verbosity < 2:
return {
"summary": "Warnings are not printed on the error log",
"severity": "warning"
}
In this implementation, the script iterates through database variables (like log_error_verbosity) and returns a structured dictionary if a threshold is violated.
Sources: managed/data/checks/mysql_configuration_log_verbosity.yml:1-30, managed/CONTRIBUTING.md:172-174
Result Management and Reporting
When a check fails, the system generates an AdvisorCheckResult containing details about the service and how to resolve the issue.
Check Result Fields
- Summary/Description: Human-readable details of the failure.
- Severity: Level of importance (e.g., EMERGENCY, CRITICAL, WARNING).
- Read More URL: External link to documentation for resolution steps.
- Service Name/ID: Identifiers for the monitored instance where the failure occurred.
Sources: api/advisors/v1/advisors.proto:28-40, api/advisors/v1/advisors.proto:61-75
API Operations
The AdvisorService exposes several RPC methods for management:
- ListAdvisors: Returns available advisors and their constituent checks.
- StartAdvisorChecks: Manually triggers the execution of specified checks.
- ChangeAdvisorChecks: Enables/disables checks or modifies their intervals.
- ListFailedServices: Provides a summary count of failed checks per service, grouped by severity.
- GetFailedChecks: Retrieves the specific list of failing checks for a particular service ID.
Sources: api/advisors/v1/advisors.proto:145-210
Configuration and Settings
Users can manage the Advisor system through the PMM Settings UI. Global settings allow for:
- Enabling or disabling the Advisor system entirely.
- Setting the specific frequency for
Rare,Standard, andFrequentintervals. - Reviewing individual advisor insights to understand specific database threats.
Sources: ui/apps/pmm/src/pages/settings/Settings.messages.ts:38-48, managed/CONTRIBUTING.md:183-186
Summary
The Advisors & Checks system provides a robust framework for automated database auditing. By utilizing YAML-defined metadata and Starlark scripts, PMM can dynamically evaluate the health of MySQL, MongoDB, and PostgreSQL instances. The system's integration with the PMM Server API allows for both automated background execution and on-demand user-driven checks, with results surfaced directly in the PMM dashboard for administrative action.