percona / pmm-doc

Percona Monitoring and Management (PMM) Technical Documentation

Percona Monitoring and Management (PMM) Documentation

Percona Monitoring and Management (PMM) is a database monitoring solution that is free and open-source.

This repo holds the source files for the official PMM technical documentation.

To contribute to that documentation, you can:

• report a general problem -- open a Jira issue.

• fix a problem yourself -- Use the Edit this page link to take you to the Markdown source file for that page. Make your changes (you'll have to fork the repo unless you're Percona staff) and submit a PR which we'll review and adjust where necessary before merging and publishing. If the changes are more than a few lines, you might want to build the website locally to see how it looks in context. That's what the rest of this README covers.

Introduction

We use MkDocs to convert Markdown files into a static HTML website (or PDF). This process is called building the documentation.

The documentation source files are in the docs directory. (Other files in this repo are explained in Directories and files.)

The two major PMM versions are kept in separate branches:

• main is for PMM 2.x (latest)

• 1.x is for PMM 1.x

Before you start, it helps to know what Git, Python and Docker are, what Markdown is and how to write it, and how to install and use those things on the command line. (If you don't, consider opening a Jira issue instead.)

Building the documentation

If you'd like to have a local copy of PMM documentation, or are thinking about contributing, it helps if you can build the documentation to see how it will look when published. The easiest way is to use Docker, as this avoids having to install MkDocs and its dependencies.

With Docker

1. Install Docker.

2. Clone this repository.

3. Change directory to pmm-doc.

4. Use our PMM documentation Docker image to build the documentation:

   docker run --rm -v $(pwd):/docs perconalab/pmm-doc-md mkdocs build

5. Find the site directory, open index.html in a browser to view the first page of documentation.

If you want to see how things look as you edit, MkDocs has a built-in server for live previewing. After (or instead of) building, run:

docker run --rm -v $(pwd):/docs -p 8000:8000 perconalab/pmm-doc-md mkdocs serve --dev-addr=0.0.0.0:8000

Wait until you see INFO - Start detecting changes then point your browser to http://0.0.0.0:8000.

Without Docker

If you don't use Docker, you must install MkDocs and all its dependencies.

1. Install Python.

2. Install MkDocs and required extensions:

   pip install -r requirements.txt

3. Build the site:

   mkdocs build

4. Open site/index.html

Or, to run the built-in web server:

mkdocs serve

View the site at http://0.0.0.0:8000

PDF

How to create a PDF version of the documentation.

1. (For Percona staff) If building for a release of PMM, edit mkdocs-base.yml and change:

   • The release number in plugins.with-pdf.output_path
   • The release number and date in plugins.with-pdf.cover_subtitle

2. Build

   • With Docker:

     docker run --rm -v $(pwd):/docs -e ENABLE_PDF_EXPORT=1 perconalab/pmm-doc-md mkdocs build -f mkdocs-pdf.yml

   • Without:

     ENABLE_PDF_EXPORT=1 mkdocs build -f mkdocs-pdf.yml

3. The PDF is in site/_pdf.

Directories and files

• mkdocs-percona.yml: MkDocs configuration file. Creates unthemed HTML for hosting on percona.com.

• mkdocs.yml: Default MkDocs configuration file. Creates (Material) themed HTML for hosting anywhere.

• mkdocs-pdf.yml: MkDocs configuration file. Creates themed PDF.

• docs:

  • *.md: Markdown files.

  • _images/*: Images, image resources, videos.

  • css: Styling.

  • js: JavaScript files.

• _resources:

  • bin

    • glossary.tsv: Export from a spreadsheet of glossary entries.

    • make_glossary.pl: Script to write Markdown page from glossary.tsv.

    • grafana-dashboards-descriptions.py: Script to extract dashboard descriptions from https://github.com/percona/grafana-dashboards/.

  • templates: Stylesheet for PDF output (used by mkdocs-with-pdf extension).

  • theme:

    • main.html: MkDocs template for HTML published on percona.com.

• requirements.txt: Python package dependencies.

• variables.yml: Values used throughout the Markdown, including the current PMM version/release number.

• .spelling: Words regarded as correct by mdspell (See Spelling and grammar.)

• .github:

  • workflows:

    • build.yml: Workflow specification for building the documentation via a GitHub action. (Uses mike which puts HTML in publish branch.)

• site: When building locally, directory where HTML is put.

Version switching

We use mike to build different versions of the documentation. Currently, only two are built, the latest PMM 1 and PMM 2 versions.

A GitHub actions workflow runs mike which in turn runs mkdocs. The HTML is committed and pushed to the publish branch. The whole branch is then copied (by an internal Percona Jenkins job) to our web server.

Image overlays

docs/using/interface.md uses an image of the home dashboard overlaid with numbered boxes to identify menu bars and control. This approach means the home dashboard image and its numbered version always look the same. You need only recreate the home page image in 1280x1280 format, then merge with the numbered overlay.

Here's how it's done.

• PMM_Home_Dashboard.jpg is created by pmm-screenshots-pw. If snapped by hand, it should be 1280x1280 pixels, to match the overlay image.

• PMM_Home_Dashboard_Overlay.png is exported from docs/_images/PMM_Home_Dashboard_Overlay.drawio using https://app.diagrams.net/.

  1. Go to https://app.diagrams.net/

  2. If it's your first time, select Device at the Save diagrams to: dialog

  3. Click Open existing diagram

  4. Navigate to pmm-doc/docs/_images and select PMM_Home_Dashboard_Overlay.drawio

  5. If the dashboard layout has changed, replace the Guide Layer with a new screenshot and adjust the elements on the Overlay layer as required (To show layers, click View --> Layers). Untick the Guide Layer so it is not exported.

  6. Click File --> Export as --> PNG

  7. In the Image settings dialog, use these settings:

     • Zoom: 100%, Border Width: 0

     • Size: Page (The page dimensions in inches should be as close to the base image as possible, i.e. 1280x1280)

     • Transparent Background: ON

     • Shadow: OFF

     • Grid: OFF

     • Include a copy of my diagram: OFF

  8. Click Export

  9. Click Device

  10. Navigate to pmm-doc/docs/_images and click PMM_Home_Dashboard_Overlay.png

  11. Click Save and overwrite the current file

The overlay image is merged with a copy of the latest home dashboard using composite, one of the ImageMagick tools.

composite docs/_images/PMM_Home_Dashboard_Overlay.png docs/_images/PMM_Home_Dashboard.jpg docs/_images/PMM_Home_Dashboard_Numbered.png

Spelling and grammar

The GitHub actions build job performs a basic spell check. (A grammar check is currently commented out in the actions file.) You can do these yourself on the command line if you have Node.js installed.

npm i markdown-spellcheck -g
mdspell --report --en-us --ignore-acronyms --ignore-numbers docs/<path to file>.md

To check all files:

mdspell --report --en-us --ignore-acronyms --ignore-numbers "docs/**/*.md"

Add any custom dictionary words to .spelling. The results of the spell check are printed, but the job ignores the return status.

Grammar is checked using write-good.

npm i write-good -g
write-good docs/<path to file>.md

To check all files:

write-good docs/**/*.md

Link checking

We're using the mkdocs-htmlproofer-plugin link checking plugin to detect broken URLs. It works well, but increases the build time significantly (by between 10 and 50 times longer).

The plugin is installed in our PMM documentation Docker image and by the GitHub action, but it is commented out in mkdocs.yml.

To enable it for local builds, uncomment the line with htmlproofer in the plugins section of mkdocs.yml and parse the build output for warnings.

pmm-doc's Issues

PMM2: doc issue on page 'Docker' (setting-up/server/docker.html)

Please describe the issue here:
You wrote "Running PMM Client as a Docker container", but I think it's about PMM-server.

PMM2: doc issue on page 'Welcome' (index.html)

In Section PMM Client is typo:

s/MongDB/MongoDB

PMM user creation instructions for MySQL 8 on Amazon RDS don't work and are harmful

When reading https://docs.percona.com/percona-monitoring-and-management/setting-up/client/aws.html#setting-up-the-amazon-rds-db-instance you see,

CREATE USER 'pmm'@'%' IDENTIFIED BY 'pass';
GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO 'pmm'@'%';
ALTER USER 'pmm'@'%' WITH MAX_USER_CONNECTIONS 10;
GRANT SELECT, UPDATE, DELETE, DROP ON performance_schema.* TO 'pmm'@'%';

The problem is, running this script on an AWS RDS MySQL 8 database "aggressively" doesn't work. It closed my client connection after complaining about an invalid GRANT. It then blocked the replication process of our replica, failing on the GRANT instructions (Context: we are migrating our Primary from 5.7 to 8.0.x so our 8.0.x replica failed quite hard).

After a chat with GPT, it explained that in MySQL 8 the default authentication method changed and that running this script instead would work,

-- Create user with caching_sha2_password authentication plugin
CREATE USER 'pmm'@'%' IDENTIFIED WITH 'caching_sha2_password' BY 'pass';

-- Grant necessary privileges using the new syntax
GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO 'pmm'@'%';
GRANT SELECT, UPDATE, DELETE, DROP ON performance_schema.* TO 'pmm'@'%';

-- Set maximum user connections
ALTER USER 'pmm'@'%' WITH MAX_USER_CONNECTIONS 10;

I tried it and indeed it seems to work.

I'm not expert here on the why and how; we should probably use the mysql_native_password plugin instead, I don't know. But I know that the current instructions in the documentation were very harmful for us.

Thanks !

Fix Headline Hierarchy for Subsections of Slow query log

The sections Applicable versions etc. following the Slow query log paragraph refer to the latter only. Thus, they should be nested below it, but are shown on the same level right now.

PS: I hope it's okay that I'm creating an issue for this detail. If I got time, I may provide a PR later on. Just didn't want to forget sharing this information.

PMM2: doc issue on page 'MySQL and variants' (setting-up/client/mysql.html) can't use "slow query log"

Hi,

In case the PMM Client is deployed via docker container (https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/client/index.html#docker) or docker-compose (https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/client/index.html#docker-compose) it can't use MySQL's slow query log as described at
https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/client/mysql.html#slow-query-log as soon as '/var/lib/mysql' directory is not mounted into docker container from host machine.

And it can't rotate 'slowquery.log' file due to the same reason.

Please adjust the instructions accordingly.

pmmserver升级container中postgresql迁移报错

INFO[2022-10-19T06:31:13.718+00:00] Migrating database... component=migration
WARN[2022-10-19T06:31:13.718+00:00] Failed to migrate database: dial tcp 127.0.0.1:5432: connect: connection refused. component=migration
INFO[2022-10-19T06:31:14.718+00:00] Migrating database... component=migration
WARN[2022-10-19T06:31:14.718+00:00] Failed to migrate database: dial tcp 127.0.0.1:5432: connect: connection refused. component=migration
INFO[2022-10-19T06:31:15.719+00:00] Migrating database... component=migration
WARN[2022-10-19T06:31:15.720+00:00] Failed to migrate database: dial tcp 127.0.0.1:5432: connect: connection refused. component=migration
INFO[2022-10-19T06:31:16.720+00:00] Migrating database...

Clarify Docker Setup for PMM Agent/Client

I'm trying to setup the PMM client/agent with docker for the first time. Setting up the server with docker was pretty straightforward, but I feel like the client setup documentation is quite confusing.

In the last part of the relevant section the following is given:

Run the container to start PMM Agent in setup mode.
[...]
You can now add services with pmm-admin by prefixing commands with docker exec pmm-client.

Isn't there missing something in between? How do I run the container without the setup mode? If I just restart the container, it complains that the associated node name is already registered. If I remove all environment vars from the call, it fails after complaining that you should run a setup. I tried setting PMM_AGENT_SETUP from 1 to 0, but that didn't help either.

---

Furthermore, the next section after the Install -> Docker one is once again Register. That doesn't make sense, does it? Shouldn't the latter affect only the non-docker ways of installing?

---

Maybe I'm just missing something obvious. Support for clarification is appreciated very much!

PMM2: doc issue on page 'Client' (setting-up/client/index.html) - No list of supported ENV vars

Please consider adding the list of supported ENV vars for PMM Client in the same way as it exists for PMM Server (https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/server/docker.html#docker "Docker environment variables")

Question about integration with Grafana OSS

Hello,

We are working with OSS PPM, we implement and things is amazing especially QAN, but we are asking ourselves, if we can use some external Grafana and Victoria Metrics? Why I'm asking this because our company has great features in our corporative grafana to alarm ans show metrics, and we'd like only to plug PMM in this Grafana OSS

PMM2: doc issue on page 'MySQL and variants' (setting-up/client/mysql.html) fix adding a service CLI examples

Hi,

There are the following examples at https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/client/mysql.html#add-a-service "On the command line"

sudo pmm-admin add mysql --username=pmm --password=pass

and similar.

But in case the PMM Client is deployed via docker container (https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/client/index.html#docker) or docker-compose (https://www.percona.com/doc/percona-monitoring-and-management/2.x/setting-up/client/index.html#docker-compose) there is no 'sudo' in container:

bash-4.2$ sudo pmm-admin add mysql --username=pmm --password=pas

bash: sudo: command not found

Please adjust the examples accordingly.

Fix typos

You can fix typos, spelling mistakes, or grammatical errors in the documentation.
If you want to make a bigger change, create a new issue instead and assign someone from the documentation team to review the changes: @catalinaadam or @rasika-chivate.

Percona follows the principle of simple documentation. For information on this, check out the Percona Documentation Style Guide

PMM2: doc issue on page 'HAProxy Instance Summary' (details/dashboards/dashboard-haproxy-instance-summary.html)

Page appears empty currently. Are there other pages for HAPROXY information/setup/configuration? I will search...