Writing Custom Advisors

Relevant source files

The following files were used as context for generating this wiki page:

• managed/CONTRIBUTING.md
• api/advisors/v1/advisors.proto
• managed/data/advisors/query_schema_design.yml
• managed/models/database.go
• ui/apps/pmm/src/pages/settings/Settings.messages.ts
• documentation/mkdocs-base.yml

Advisors are automated checks within Percona Monitoring and Management (PMM) designed to analyze monitored environments and provide actionable insights or recommendations. These checks help identify potential security threats, performance degradation, data loss, and configuration issues across various database families such as MySQL, MongoDB, and PostgreSQL.

Developers can extend PMM's capabilities by writing custom Advisors, which consist of two main components: the Advisor definition (YAML metadata) and the Advisor checks (executable logic). These components are managed by the pmm-managed service and can be configured to run at specific intervals.

Sources: managed/CONTRIBUTING.md:144-148, README.md:43-46, api/advisors/v1/advisors.proto:11-16

Advisor Architecture and Structure

Advisors in PMM are organized into categories by topic (e.g., configuration, security, performance). A single Advisor typically contains one or more checks.

Component Layout

• Advisor Definitions: Located in the managed/data/advisors directory. These YAML files define the Advisor's name, summary, description, and category.
• Advisor Checks: Located in the managed/data/checks directory. These files contain the actual logic executed by the Advisor.
• Database Schema: The pmm-managed service uses a PostgreSQL database to track check settings and results.

Sources: managed/CONTRIBUTING.md:162-171, managed/models/database.go:503-506

Data Flow Diagram

The following diagram illustrates how Advisor metadata and logic are processed by the system to produce failed check results displayed in the UI.

Explanation: This flowchart shows the relationship between the YAML definitions on the filesystem, the pmm-managed service, the persistent storage in PostgreSQL, and the final visualization in the PMM UI.
Sources: managed/CONTRIBUTING.md:162-177, managed/models/database.go:503-506

Defining Advisor Metadata

Advisor metadata is stored in YAML files. These files define the high-level identity of the Advisor.

YAML Specification

A typical Advisor definition includes the following fields:

Field	Type	Description
version	Integer	The schema version of the Advisor definition.
name	String	Machine-readable ID used in expressions and API calls.
summary	String	A short human-readable summary shown in the UI.
description	String	A detailed explanation of what the Advisor does.
category	String	The grouping for the Advisor (e.g., query, security).

Sources: managed/data/advisors/query_schema_design.yml:2-8, api/advisors/v1/advisors.proto:89-100

Code Snippet: Advisor Definition

---
advisors:
  - version: 1
    name: query_schema_design
    summary: Schema Design Query
    description: Helps create efficient database schemas by analyzing queries and offering suggestions for optimization.
    category: query

Sources: managed/data/advisors/query_schema_design.yml:1-8

Advisor Checks and Execution

Checks are the executable parts of an Advisor. They are assigned to specific database families and run at configurable intervals.

Execution Intervals

The execution frequency can be configured through the UI or API:

Interval	Description
RARE	Least frequent execution, minimizes resource impact.
STANDARD	Default execution frequency.
FREQUENT	Most frequent execution, catches issues faster.

Sources: api/advisors/v1/advisors.proto:8-16, ui/apps/pmm/src/pages/settings/Settings.messages.ts:40-45

Advisor Service API

The AdvisorService provides gRPC/REST endpoints to interact with Advisors:

• ListAdvisors: Returns all available Advisors.
• ListAdvisorChecks: Lists all checks available to the user.
• StartAdvisorChecks: Manually triggers the execution of specified checks.
• ChangeAdvisorChecks: Enables/disables checks or modifies their intervals.
• GetFailedChecks: Retrieves the results for checks that have failed.

Sources: api/advisors/v1/advisors.proto:143-186

Advisor Relationship Diagram

Explanation: This class diagram illustrates the hierarchical relationship between an Advisor, its constituent checks, and the results produced when those checks fail.
Sources: api/advisors/v1/advisors.proto:18-120

Development and Testing

When developing custom Advisors, it is recommended to work within the PMM "devcontainer" to ensure all backend services are available.

Testing Workflow

1. Setup Environment: Use make env-up to start the development container.
2. Add Logic: Place new Advisor definitions in managed/data/advisors and check logic in managed/data/checks.
3. Register Instances: Monitored database instances must be added so the Advisor has targets to check.
4. Verify: Check results appear in the PMM Advisor Dashboards. Any failed checks will generate a CheckResult containing a summary, description, and severity level (e.g., EMERGENCY, CRITICAL, WARNING).

Sources: managed/CONTRIBUTING.md:129-142, managed/CONTRIBUTING.md:162-171, api/advisors/v1/advisors.proto:44-63

Environmental Variables for Development

Several variables can be used to tune the Advisor service during development:

• PMM_DEV_ADVISOR_STARLARK_ALLOW_RECURSION: Allows recursive functions in check scripts (default: false).
• PMM_DEV_ADVISOR_CHECKS_FILE: Specifies a path to a local checks file, disabling automatic downloads.
• PMM_ADVISOR_CHECKS_DISABLE_START_DELAY: Disables the default startup delay for the checks service.

Sources: managed/CONTRIBUTING.md:85-88

Summary

Writing custom Advisors allows for tailored monitoring logic within PMM. By defining metadata in YAML and implementing check logic in the appropriate directories, developers can leverage the existing AdvisorService and UI dashboards to provide database insights. The system ensures that these checks run according to specified intervals and report results back to a centralized PostgreSQL store for visualization.