Development Guide

Relevant source files

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

• CONTRIBUTING.md
• managed/CONTRIBUTING.md
• documentation/docs-contributing.md
• dashboards/CONTRIBUTING.md
• documentation/WRITERS-NOTES.md
• api/README.md
• admin/commands/base.go

This guide provides a comprehensive overview of the development processes, environment setup, and contribution standards for Percona Monitoring and Management (PMM). PMM is a complex, multi-repo project consisting of various backend services, frontend interfaces, and client-side agents designed for database monitoring.

The project encompasses multiple technologies including Go for backends, Grafana and React for frontends, and specialized exporters for different database engines. Developers are expected to follow specific workflows for code changes, documentation updates, and feature builds to maintain system integrity across all components.
Sources: CONTRIBUTING.md:1-20, managed/CONTRIBUTING.md:1-5

Repository Structure and Architecture

PMM is composed of several specialized repositories categorized by their role in the system.

Category	Repositories	Description
APIs	percona/pmm/api	Contains .proto definitions and generated API code.
Server (Backend)	pmm-managed, qan-api	Manages configuration, components (VictoriaMetrics, Grafana), and Query Analytics.
Server (Frontend)	grafana, ui, dashboards	User interfaces and monitoring dashboards.
Client	pmm-agent, pmm-admin, *_exporter	Monitoring agents and database-specific metric exporters.
Support	pmm-qa, documentation	QA tests, E2E tests, and project documentation.

Sources: CONTRIBUTING.md:23-56

The following diagram illustrates the relationship between the major components during development:

This diagram shows the high-level interaction between the management backend, the monitoring agents, and the data stores within the devcontainer environment.
Sources: CONTRIBUTING.md:23-56, managed/CONTRIBUTING.md:10-15

Local Development Environment

Devcontainer Setup

The core development of PMM Server components (like pmm-managed) is performed inside a "devcontainer". This ensures a consistent environment with all necessary tools.

1. Start Environment: Use make env-up to start the development container.
2. Access Container: Use make env to open a bash session inside the container or make env TARGET=<name> to run specific make targets.
3. Deploy Changes: The make run-managed target replaces the binary in /usr/sbin/pmm-managed and restarts the service using supervisorctl.

Sources: managed/CONTRIBUTING.md:13-43

Backend Development (Go)

Backend commands and services are primarily written in Go. The admin/commands package provides the base structure for CLI interactions.

type Command interface {
	RunCmd() (Result, error)
}

type CommandWithContext interface {
	RunWithContext(ctx context.Context) (Result, error)
}

Sources: admin/commands/base.go:61-72

Frontend Development (Dashboards and UI)

For dashboard development, a specialized Docker Compose environment is provided to populate panels with sample data.

cd pmm-app
docker-compose -f ./docker-compose.local.yml up -d
yarn dev

The ./pmm-app/dist folder is mapped to /var/lib/grafana/plugins inside the container so that changes to panels and dashboards are immediately available in Grafana.
Sources: dashboards/CONTRIBUTING.md:37-60

API Management

PMM APIs are defined using Protocol Buffers (.proto files). All generated files (Go code, Swagger specs) are stored in the repository.

• Documentation: Served via make serve using nginx.
• Modifying APIs: Edit the .proto files in the api/ directory.
• Generation: Run make gen to update the .pb.go and .pb.gw.go files. Manual edits to generated files are prohibited.

Sources: api/README.md:1-25

Documentation Standards

Documentation is written in Markdown and processed using MkDocs with the Material theme.

Formatting and Admonitions

• Line Wrapping: Most files do not use hard line wrapping; soft-wrap is preferred for editor flexibility.
• Admonitions: Used to highlight specific types of information.

Admonition	Color	Usage
note, info	Blue	Side topics or detached notes.
hint, tip	Green	Non-essential but useful advice.
caution, warning	Amber	Points requiring care or emphasis.
danger	Red	Potential for data or system damage.

Sources: documentation/WRITERS-NOTES.md:1-75

Local Documentation Build

Developers can preview documentation changes locally using Docker/Podman:

make docs-build # Build docs
make docs-serve # Preview with live reload

Sources: documentation/docs-contributing.md:52-64

Testing and Quality Assurance

PMM utilizes a three-tier testing strategy:

1. Unit Tests: Located within individual repositories; run via make test or make env TARGET=test.
2. API Tests: Located in the api-tests directory of the main PMM repo; these run inside an active PMM Server container.
3. End-to-End (E2E) Tests: Located in the percona/pmm-qa repository; includes UI and CLI testing.

Sources: CONTRIBUTING.md:112-132

Contribution Workflow

All contributions must follow the standard Pull Request (PR) process.

Key Rules

• CLA: All contributors must sign the Contributor License Agreement.
• Feature Builds (FB): Create an FB for every improvement. This involves creating a draft PR in pmm-submodules to build and test all components together.
• Reviewers: Assign pmm-review-be for backend changes and pmm-review-fe for UI/frontend changes.
• JIRA: Include the JIRA issue ID in commit messages (e.g., [PMM-5053] Description).

Sources: CONTRIBUTING.md:152-195, dashboards/CONTRIBUTING.md:17-21, dashboards/CONTRIBUTING.md:80-85

Summary

Development in PMM requires a coordinated approach across multiple specialized repositories. By utilizing the provided devcontainer environments, following the strict API modification workflow, and adhering to the multi-tier testing and documentation standards, developers can ensure their contributions integrate seamlessly into the broader PMM ecosystem.
Sources: CONTRIBUTING.md:197-200, managed/CONTRIBUTING.md:162-166