pmm - Moses Yebei

The Problem

Customers need a single pane of glass to monitor MySQL, MongoDB, PostgreSQL, Valkey and Redis deployments, collect query‑level metrics, and receive real‑time alerts. Existing agents are scattered, and integrating them into a unified UI requires duplicated code and ad‑hoc scripts.

What This Does

The pmm repository is a portfolio of 14 loosely coupled projects that together implement Percona Monitoring and Management (PMM).

agent/ (≈ 242 Go source files) contains the database collectors (MySQL slow‑log, MongoDB oplog, PostgreSQL pg‑stat). Entry points such as agent/agents/mongodb/mongolog/mongodb.go expose a Run function that streams metrics to the server.
managed/ (≈ 411 Go files) provides the server‑side services, including telemetry, HA orchestration and alert templates (managed/services/ha/services.go).
ui/ (≈ 428 TSX/TS files) is a React front‑end, built with Yarn, that talks to the server via ui/apps/pmm/src/api/api.ts.
admin/ (admin/cmd/pmm-admin/main.go) offers a CLI for bootstrap, user management and server lifecycle.
qan‑api2/ implements the Query Analytics API and ships a Docker‑compose stack (qan-api2/docker-compose.yml).

Common techniques across the projects are Go modules for back‑end services, Protocol Buffers for RPC (api/agent/pb/), and a shared Docker‑based dev environment (.devcontainer/Dockerfile).

How It Is Wired

Execution starts in admin/cmd/pmm-admin/main.go (func main). It parses CLI flags, then calls Run, which reaches 70 internal functions and eventually invokes the server bootstrap in managed/services/ha/services.go. The bootstrap creates the telemetry datasource (managed/models/location_model.go) and starts the HTTP API (api/agent/pb/agent_grpc.pb.go).

On the data‑collection side, each agent binary is built from the agent/cmd/pmm-agent-entrypoint/main.go entry point. For MongoDB, Run in agent/agents/mongodb/mongolog/mongodb.go opens a DB connection (db.ExecContext), reads the oplog, and writes JSON files (os.Remove later). The call chain is short: Run → updateAllExternalExporterStatuses → hasExternalExporters → db.QueryRow.

The UI loads data via the hub module ui/apps/pmm/src/api/api.ts. Twelve other UI modules import this hub, making it the highest‑blast‑radius component (12 dependents). The hub calls the Go HTTP server’s JSON endpoints, which ultimately invoke the same Run‑style functions in the agents.

The most connected back‑end symbols are generic helpers such as Run, New, Parse, Close and ReadFile, each called from dozens of locations (e.g., Run from 98 places). No circular import cycles were detected, but deep nesting (up to 8 levels) and duplicated validation blocks (≈ 655 occurrences) increase cognitive load.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/pmm
cd pmm

# Build server and agents (requires Go 1.22+ and Docker)
make -f admin/Makefile build          # builds pmm-admin binary
make -f agent/Makefile build          # builds agent binaries

# Start a dev stack (Docker Compose defined in qan-api2)
docker compose -f qan-api2/docker-compose.yml up -d

# Set required env (example) – see .env.example
export QANAPI_DSN="user:pass@tcp(localhost:3306)/qan"

# Run the admin CLI to bootstrap the server
./admin/cmd/pmm-admin/pmm-admin bootstrap

The UI can be launched with Yarn:

cd ui/apps/pmm
yarn install
yarn start

Real‑World Use

A SaaS provider deploys the PMM server container on each Kubernetes cluster. Their CI pipeline builds the agent binaries, stores them in a private registry, and runs the pmm-admin bootstrap command to provision Grafana dashboards and alert rules. Application teams then install the agent binary on each DB host; the agents push metrics to the server, which the UI visualizes for capacity planning.

Code Health & Issues

Critical – Committed credentials in qan-api2/.env. Rotate, remove from Git, and replace with *.example.
High – Same .env is tracked despite .gitignore; git rm --cached and rotate.
High – Untracked secret file agent/utils/tests/testdata/mongodb/*.pem. Add to .gitignore.
Medium – No pre‑commit secret scan; add a hook (e.g., git-secrets).
Medium – Large JSON fixtures (metrics.part_*.json) > 5 MiB; move to Git LFS or external storage.
Medium – GitHub Actions checkout persists token; set persist-credentials: false.
Low – Workflow jobs lack timeout-minutes; add sensible limits.
Low – Repository lacks standard convention files (.editorconfig, formatter config); add them.

Measured static analysis also reported 56 instances of deep nesting, 655 duplicated validation blocks, and high branching density in ui/apps/pmm/src/components/icon/Icon.constants.ts. Refactoring these hotspots will lower maintenance cost.

The Bottom Line

PMM provides a full‑stack, open‑source monitoring solution with clearly separated agent, server, and UI components. The codebase is functional but suffers from secret leakage, large binary blobs and maintainability hotspots (deep nesting, duplicated validation). Teams comfortable with Go, Docker and React can adopt it quickly, provided they address the critical credential issues and consider refactoring the identified high‑impact modules.

What the analyser found

Deployment readiness

6/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

3,270 files

Go1222
Markdown450
TypeScript269
YAML261
JSON160
TSX150

ReactDockerKubernetes

Dependencies

134 declared dependencies, none a major version behind. Resolved 14 of 134 against the registry.

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them agent/utils/tests/testdata/mongodb/client.pem, agent/utils/tests/testdata/mongodb/server.pem, build/ansible/roles/clickhouse/files/dhparam.pem

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical2

high3

medium3

low2

Upgrade the pinned dependency carrying a critical advisorycritical31 occurrences

golang.org/x/crypto@0.48.0 CVE-2026-42508 (critical) +26 more; google.golang.org/grpc@1.79.1 CVE-2026-33186 (critical) +3 more

The manifest pins the exact version the advisory covers, so this is not a warning about drift: the vulnerable code is what installs, and a critical rating means it is reachable over the network without credentials or user interaction.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Rotate the credentials in the committed environment filecritical

qan-api2/.env

QANAPI_DSN hold generated values

These values are loaded by the application at boot, so a generated value here is a working credential for something that runs.

Fix: Rotate each named credential, remove the file from the index, and replace it with a keys-only example.

Untrack the file your own .gitignore says to ignorehigh

qan-api2/.env

tracked although .gitignore excludes it

The author already decided this file must never be committed, so its presence is an accident nobody noticed, which means the credentials in it are the ones actually in use.

Fix: git rm --cached the path and rotate; the ignore rule is already correct.

Upgrade the pinned dependency carrying a published advisoryhigh12 occurrences

github.com/prometheus/prometheus@0.310.0 CVE-2026-42154 (high) +7 more; markdown@3.5.2 CVE-2025-69534 (high) +1 more; go.mongodb.org/mongo-driver@1.17.6 CVE-2026-2303 (medium) +1 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Remove the committed .env and rotate what it holdshigh

qan-api2/.env

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Move large binaries to Git LFS or out of the repositorymedium9 occurrences

qan-api2/fixture/metrics.part_2019-01-01_03.json

9 blobs over 5MB: metrics.part_2019-01-01_03.json 50.2MB, metrics.part_2019-01-02_03.json 50.2MB, metrics.part_2019-01-01_04.json 50.2MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/main.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Set timeout-minutes on the workflow jobslow3 occurrences

.github/workflows/api-tests.yml

3 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.