Buy Percona ServicesBuy Now!

Managing PMM Client

Use the pmm-admin tool to manage PMM Client.

USAGE

pmm-admin [OPTIONS] [COMMAND]

Note

The pmm-admin tool requires root access (you should either be logged in as a user with root privileges or be able to run commands with sudo).

To view all available commands and options, run pmm-admin without any commands or options:

$ sudo pmm-admin

OPTIONS

The following options can be used with any command:

-c, --config-file
Specify location of PMM configuration file (default /usr/local/percona/pmm-client/pmm.yml).
-h, --help
Print help for any command and exit.
-v, --version
Print version of PMM Client.
--verbose
Print verbose output.

COMMANDS

pmm-admin add
Add a monitoring service.
pmm-admin check-network
Check network connection between PMM Client and PMM Server.
pmm-admin config
Configure how PMM Client communicates with PMM Server.
pmm-admin help
Print help for any command and exit.
pmm-admin info
Print information about PMM Client.
pmm-admin list
List all monitoring services added for this PMM Client.
pmm-admin ping
Check if PMM Server is alive.
pmm-admin purge
Purge metrics data on PMM Server.
pmm-admin remove, pmm-admin rm
Remove monitoring services.
pmm-admin repair
Remove orphaned services.
pmm-admin restart
Restart monitoring services.
pmm-admin show-passwords
Print passwords used by PMM Client (stored in the configuration file).
pmm-admin start
Start monitoring service.
pmm-admin stop
Stop monitoring service.
pmm-admin uninstall
Clean up PMM Client before uninstall.

Adding monitoring services

Use the pmm-admin add command to add monitoring services.

USAGE

pmm-admin add [OPTIONS] [SERVICE]

OPTIONS

The following option can be used with the pmm-admin add command:

--dev-enable
Enable experimental features.
--service-port
Specify the service port.

You can also use global options that apply to any other command.

SERVICES

Specify a monitoring service alias, along with any relevant additional arguments.

For more information, run sudo pmm-admin add --help.

Adding general system metrics service

Use the linux:metrics alias to enable general system metrics monitoring.

USAGE

pmm-admin add linux:metrics [NAME] [OPTIONS]

This creates the pmm-linux-metrics-42000 service that collects local system metrics for this particular OS instance.

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following option can be used with the linux:metrics alias:

--force
Force to add another general system metrics service with a different name for testing purposes.

You can also use global options that apply to any other command, as well as options that apply to adding services in general.

For more information, run sudo pmm-admin add linux:metrics --help.

Adding MySQL query analytics service

Use the mysql:queries alias to enable MySQL query analytics.

USAGE

pmm-admin add mysql:queries [NAME] [OPTIONS]

This creates the pmm-mysql-queries-0 service that is able to collect QAN data for multiple remote MySQL server instances.

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following options can be used with the mysql:queries alias:

--create-user
Create a dedicated MySQL user for PMM Client (named pmm).
--create-user-maxconn
Specify maximum connections for the dedicated MySQL user (default is 10).
--create-user-password
Specify password for the dedicated MySQL user.
--defaults-file
Specify path to my.cnf.
--disable-queryexamples
Disable collection of query examples.
--force
Force to create or update the dedicated MySQL user.
--host
Specify the MySQL host name.
--password
Specify the password for MySQL user with admin privileges.
--port
Specify the MySQL instance port.
--query-source

Specify the source of data:

  • auto: Select automatically (default).
  • slowlog: Use the slow query log.
  • perfschema: Use Performance Schema.
--socket
Specify the MySQL instance socket file.
--user
Specify the name of MySQL user with admin privileges.

You can also use global options that apply to any other command, as well as options that apply to adding services in general.

DETAILED DESCRIPTION

When adding the MySQL query analytics service, the pmm-admin tool will attempt to automatically detect the local MySQL instance and MySQL superuser credentials. You can use options to provide this information, if it cannot be detected automatically.

You can also specify the --create-user option to create a dedicated pmm user on the MySQL instance that you want to monitor. This user will be given all the necessary privileges for monitoring, and is recommended over using the MySQL superuser.

For example, to set up remote monitoring of QAN data on a MySQL server located at 192.168.200.2, use a command similar to the following:

sudo pmm-admin add mysql:queries --user root --password root --host 192.168.200.2 --create-user

QAN can use either the slow query log or Performance Schema as the source. By default, it chooses the slow query log for a local MySQL instance and Performance Schema otherwise. For more information about the differences, see Performance Schema.

You can explicitely set the query source when adding a QAN instance using the --query-source option.

For more information, run sudo pmm-admin add mysql:queries --help.

Adding MySQL metrics service

Use the mysql:metrics alias to enable MySQL metrics monitoring.

USAGE

pmm-admin add mysql:metrics [NAME] [OPTIONS]

This creates the pmm-mysql-metrics-42002 service that collects MySQL instance metrics.

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following options can be used with the mysql:metrics alias:

--create-user
Create a dedicated MySQL user for PMM Client (named pmm).
--create-user-maxconn
Specify maximum connections for the dedicated MySQL user (default is 10).
--create-user-password
Specify password for the dedicated MySQL user.
--defaults-file
Specify path to my.cnf.
--disable-binlogstats
Disable collection of binary log statistics.
--disable-processlist
Disable collection of process state metrics.
--disable-tablestats
Disable collection of table statistics.
--disable-tablestats-limit
Specify maximum number of tables for which collection of table statistics is enabled (by default, the limit is 1 000 tables).
--disable-userstats
Disable collection of user statistics.
--force
Force to create or update the dedicated MySQL user.
--host
Specify the MySQL host name.
--password
Specify the password for MySQL user with admin privileges.
--port
Specify the MySQL instance port.
--socket
Specify the MySQL instance socket file.
--user
Specify the name of MySQL user with admin privileges.

You can also use global options that apply to any other command, as well as options that apply to adding services in general.

DETAILED DESCRIPTION

When adding the MySQL metrics monitoring service, the pmm-admin tool will attempt to automatically detect the local MySQL instance and MySQL superuser credentials. You can use options to provide this information, if it cannot be detected automatically.

You can also specify the --create-user option to create a dedicated pmm user on the MySQL host that you want to monitor. This user will be given all the necessary privileges for monitoring, and is recommended over using the MySQL superuser.

For example, to set up remote monitoring of MySQL metrics on a server located at 192.168.200.3, use a command similar to the following:

sudo pmm-admin add mysql:metrics --user root --password root --host 192.168.200.3 --create-user

For more information, run sudo pmm-admin add mysql:metrics --help.

Adding MongoDB query analytics service

Use the mongodb:queries alias to enable MongoDB query analytics.

Note

Query analytics for MongoDB is experimental. To add it in a non-production environment, use the --dev-enable option for pmm-admin add.

USAGE

pmm-admin add mongodb:queries [NAME] [OPTIONS]

This creates the pmm-mongodb-queries-0 service that is able to collect QAN data for multiple remote MongoDB server instances.

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following options can be used with the mongodb:queries alias:

--uri

Specify the MongoDB instance URI with the following format:

[mongodb://][user:pass@]host[:port][/database][?options]

By default, it is localhost:27017.

You can also use global options that apply to any other command, as well as options that apply to adding services in general.

For more information, run sudo pmm-admin add mongodb:queries --help.

Adding MongoDB metrics service

Use the mongodb:metrics alias to enable MongoDB metrics monitoring.

USAGE

pmm-admin add mongodb:metrics [NAME] [OPTIONS]

This creates the pmm-mongodb-metrics-42003 service that collects local MongoDB metrics for this particular MongoDB instance.

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following options can be used with the mongodb:metrics alias:

--cluster
Specify the MongoDB cluster name.
--uri

Specify the MongoDB instance URI with the following format:

[mongodb://][user:pass@]host[:port][/database][?options]

By default, it is localhost:27017.

You can also use global options that apply to any other command, as well as options that apply to adding services in general.

For more information, run sudo pmm-admin add mongodb:metrics --help.

Adding ProxySQL metrics service

Use the proxysql:metrics alias to enable ProxySQL performance metrics monitoring.

USAGE

pmm-admin add proxysql:metrics [NAME] [OPTIONS]

This creates the pmm-proxysql-metrics-42004 service that collects local ProxySQL performance metrics.

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following option can be used with the proxysql:metrics alias:

--dsn
Specify the ProxySQL connection DSN. By default, it is stats:stats@tcp(localhost:6032)/.

You can also use global options that apply to any other command, as well as options that apply to adding services in general.

For more information, run sudo pmm-admin add proxysql:metrics --help.

Checking network connectivity

Use the pmm-admin check-network command to run tests that verify connectivity between PMM Client and PMM Server.

USAGE

pmm-admin check-network [OPTIONS]

OPTIONS

The pmm-admin check-network command does not have its own options, but you can use global options that apply to any other command

DETAILED DESCRIPTION

Connection tests are performed both ways, with results separated accordingly:

  • Client --> Server

    Pings Consul API, Query Analytics API, and Prometheus API to make sure they are alive and reachable.

    Performs a connection performance test to see the latency from PMM Client to PMM Server.

  • Client <-- Server

    Checks the status of Prometheus endpoints and makes sure it can scrape metrics from corresponding exporters.

    Successful pings of PMM Server from PMM Client do not mean that Prometheus is able to scrape from exporters. If the output shows some endpoints in problem state, make sure that the corresponding service is running (see pmm-admin list). If the services that correspond to problematic endpoints are running, make sure that firewall settings on the PMM Client host allow incoming connections for corresponding ports.

OUTPUT EXAMPLE

$ sudo pmm-admin check-network
PMM Network Status

Server Address | 192.168.100.1
Client Address | 192.168.200.1

* System Time
NTP Server (0.pool.ntp.org)         | 2017-05-03 12:05:38 -0400 EDT
PMM Server                          | 2017-05-03 16:05:38 +0000 GMT
PMM Client                          | 2017-05-03 12:05:38 -0400 EDT
PMM Server Time Drift               | OK
PMM Client Time Drift               | OK
PMM Client to PMM Server Time Drift | OK

* Connection: Client --> Server
-------------------- -------------
SERVER SERVICE       STATUS
-------------------- -------------
Consul API           OK
Prometheus API       OK
Query Analytics API  OK

Connection duration | 166.689µs
Request duration    | 364.527µs
Full round trip     | 531.216µs

* Connection: Client <-- Server
---------------- ----------- -------------------- -------- ---------- ---------
SERVICE TYPE     NAME        REMOTE ENDPOINT      STATUS   HTTPS/TLS  PASSWORD
---------------- ----------- -------------------- -------- ---------- ---------
linux:metrics    mongo-main  192.168.200.1:42000  OK       YES        -
mongodb:metrics  mongo-main  192.168.200.1:42003  PROBLEM  YES        -

For more information, run sudo pmm-admin check-network --help.

Configuring PMM Client

Use the pmm-admin config command to configure how PMM Client communicates with PMM Server.

USAGE

pmm-admin config [OPTIONS]

OPTIONS

The following options can be used with the pmm-admin config command:

--bind-address
Specify the bind address, which is also the local (private) address mapped from client address via NAT or port forwarding By default, it is set to the client address.
--client-address
Specify the client address, which is also the remote (public) address for this system. By default, it is automatically detected via request to server.
--client-name
Specify the client name. By default, it is set to the host name.
--force
Force to set the client name on initial setup after uninstall with unreachable server.
--server

Specify the address of the PMM Server host. If necessary, you can also specify the port after colon, for example:

pmm-admin config --server 192.168.100.6:8080

By default, port 80 is used with SSL disabled, and port 443 when SSL is enabled.

--server-insecure-ssl
Enable insecure SSL (self-signed certificate).
--server-password
Specify the HTTP password configured on PMM Server.
--server-ssl
Enable SSL encryption for connection to PMM Server.
--server-user
Specify the HTTP user configured on PMM Server (default is pmm).

You can also use global options that apply to any other command.

For more information, run sudo pmm-admin config --help.

Getting help for any command

Use the pmm-admin help command to print help for any command.

USAGE

pmm-admin help [COMMAND]

This will print help information and exit. Actual command is not run and options are ignored.

Note

You can also use the global -h or --help option after any command to get the same help information.

COMMANDS

You can print help information for any command or service alias.

Getting information about PMM Client

Use the pmm-admin info command to print basic information about PMM Client.

USAGE

pmm-admin info [OPTIONS]

OPTIONS

The pmm-admin info command does not have its own options, but you can use global options that apply to any other command

OUTPUT

The output provides the following info:

  • Version of pmm-admin
  • PMM Server host address, and local host name and address (this can be configured using pmm-admin config)
  • System manager that pmm-admin uses to manage PMM services
  • Go version and runtime information

For example:

$ sudo pmm-admin info
pmm-admin 1.1.3

PMM Server      | 192.168.100.1
Client Name     | ubuntu-amd64
Client Address  | 192.168.200.1
Service manager | linux-systemd

Go Version      | 1.8
Runtime Info    | linux/amd64

For more information, run sudo pmm-admin info --help.

Listing monitoring services

Use the pmm-admin list command to list all enabled services with details.

USAGE

pmm-admin list [OPTIONS]

OPTIONS

The pmm-admin list command does not have its own options, but you can use global options that apply to any other command

OUTPUT

The output provides the following info:

  • Version of pmm-admin
  • PMM Server host address, and local host name and address (this can be configured using pmm-admin config)
  • System manager that pmm-admin uses to manage PMM services
  • A table that lists all services currently managed by pmm-admin, with basic information about each service

For example, if you enable general OS and MongoDB metrics monitoring, output should be similar to the following:

$ sudo pmm-admin list
pmm-admin 1.1.3

PMM Server      | 192.168.100.1
Client Name     | ubuntu-amd64
Client Address  | 192.168.200.1
Service manager | linux-systemd

---------------- ----------- ----------- -------- ---------------- --------
SERVICE TYPE     NAME        LOCAL PORT  RUNNING  DATA SOURCE      OPTIONS
---------------- ----------- ----------- -------- ---------------- --------
linux:metrics    mongo-main  42000       YES      -
mongodb:metrics  mongo-main  42003       YES      localhost:27017

Pinging PMM Server

Use the pmm-admin ping command to verify connectivity with PMM Server.

USAGE

pmm-admin ping [OPTIONS]

If the ping is successful, it returns OK.

OPTIONS

The pmm-admin ping command does not have its own options, but you can use global options that apply to any other command.

For more information, run sudo pmm-admin ping --help.

Purging metrics data

Use the pmm-admin purge command to purge metrics data associated with a service on PMM Server. This is usually required after you remove a service and do not want its metrics data to show up on graphs.

USAGE

pmm-admin purge [SERVICE [NAME]] [OPTIONS]

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

SERVICES

Specify a monitoring service alias. To see which services are enabled, run pmm-admin list.

OPTIONS

The pmm-admin purge command does not have its own options, but you can use global options that apply to any other command

For more infomation, run sudo pmm-admin purge --help.

Removing monitoring services

Use the pmm-admin rm command to remove monitoring services.

USAGE

pmm-admin rm [OPTIONS] [SERVICE]

When you remove a service, collected data remains in Metrics Monitor on PMM Server. To remove collected data, use the pmm-admin purge command.

OPTIONS

The following option can be used with the pmm-admin rm command:

--all
Remove all monitoring services.

You can also use global options that apply to any other command.

SERVICES

Specify a monitoring service alias. To see which services are enabled, run pmm-admin list.

EXAMPLES

  • To remove all services enabled for this PMM Client:

    sudo pmm-admin rm --all
    
  • To remove all services related to MySQL:

    sudo pmm-admin rm mysql
    
  • To remove only MongoDB metrics service:

    sudo pmm-admin rm mongodb:metrics
    

For more information, run sudo pmm-admin rm --help.

Removing orphaned services

Use the pmm-admin repair command to remove information about orphaned services from PMM Server. This can happen if you removed services locally while PMM Server was not available (disconnected or shut down), for example, using the pmm-admin uninstall command.

USAGE

pmm-admin repair [OPTIONS]

OPTIONS

The pmm-admin repair command does not have its own options, but you can use global options that apply to any other command.

For more information, run sudo pmm-admin repair --help.

Restarting monitoring services

Use the pmm-admin restart command to restart services managed by this PMM Client. This is the same as running pmm-admin stop and pmm-admin start.

USAGE

pmm-admin restart [SERVICE [NAME]] [OPTIONS]

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following option can be used with the pmm-admin restart command:

--all
Restart all monitoring services.

You can also use global options that apply to any other command.

SERVICES

Specify a monitoring service alias that you want to restart. To see which services are available, run pmm-admin list.

EXAMPLES

  • To restart all available services for this PMM Client:

    sudo pmm-admin restart --all
    
  • To restart all services related to MySQL:

    sudo pmm-admin restart mysql
    
  • To restart only MongoDB metrics service:

    sudo pmm-admin restart mongodb:metrics
    

For more information, run sudo pmm-admin restart --help.

Getting passwords used by PMM Client

Use the pmm-admin show-passwords command to print credentials stored in the configuration file (by default: /usr/local/percona/pmm-client/pmm.yml).

USAGE

pmm-admin show-passwords [OPTIONS]

OPTIONS

The pmm-admin show-passwords command does not have its own options, but you can use global options that apply to any other command

OUTPUT

This command prints HTTP authentication credentials and the password for the pmm user that is created on the MySQL instance if you specify the --create-user option when adding a service.

$ sudo pmm-admin show-passwords
HTTP basic authentication
User     | aname
Password | secr3tPASS

MySQL new user creation
Password | g,3i-QR50tQJi9M1yl9-

For more information, run sudo pmm-admin show-passwords --help.

Starting monitoring services

Use the pmm-admin start command to start services managed by this PMM Client.

USAGE

pmm-admin start [SERVICE [NAME]] [OPTIONS]

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following option can be used with the pmm-admin start command:

--all
Start all monitoring services.

You can also use global options that apply to any other command.

SERVICES

Specify a monitoring service alias that you want to start. To see which services are available, run pmm-admin list.

EXAMPLES

  • To start all available services for this PMM Client:

    sudo pmm-admin start --all
    
  • To start all services related to MySQL:

    sudo pmm-admin start mysql
    
  • To start only MongoDB metrics service:

    sudo pmm-admin start mongodb:metrics
    

For more information, run sudo pmm-admin start --help.

Stopping monitoring services

Use the pmm-admin stop command to stop services managed by this PMM Client.

USAGE

pmm-admin stop [SERVICE [NAME]] [OPTIONS]

Note

It should be able to detect the local PMM Client name, but you can also specify it explicitly as an argument.

OPTIONS

The following option can be used with the pmm-admin stop command:

--all
Stop all monitoring services.

You can also use global options that apply to any other command.

SERVICES

Specify a monitoring service alias that you want to stop. To see which services are available, run pmm-admin list.

EXAMPLES

  • To stop all available services for this PMM Client:

    sudo pmm-admin stop --all
    
  • To stop all services related to MySQL:

    sudo pmm-admin stop mysql
    
  • To stop only MongoDB metrics service:

    sudo pmm-admin stop mongodb:metrics
    

For more information, run sudo pmm-admin stop --help.

Cleaning up PMM Client before uninstall

Use the pmm-admin uninstall command to remove all services even if PMM Server is not available. To uninstall PMM correctly, you first need to remove all services, then uninstall PMM Client, and then stop and remove PMM Server. However, if PMM Server is not available (disconnected or shut down), pmm-admin rm will not work. In this case, you can use pmm-admin uninstall to force the removal of monitoring services enabled for PMM Client.

Note

Information about services will remain in PMM Server, and it will not let you add those services again. To remove information about orphaned services from PMM Server, once it is back up and available to PMM Client, use the pmm-admin repair command.

USAGE

pmm-admin uninstall [OPTIONS]

OPTIONS

The pmm-admin uninstall command does not have its own options, but you can use global options that apply to any other command.

For more information, run sudo pmm-admin uninstall --help.

Monitoring Service Aliases

The following aliases are used to designate PMM services that you want to add, remove, restart, start, or stop:

Alias Services
linux:metrics General system metrics monitoring service
mysql:metrics MySQL metrics monitoring service
mysql:queries MySQL query analytics service
mongodb:metrics MongoDB metrics monitoring service
mongodb:queries MongoDB query analytics service
proxysql:metrics ProxySQL metrics monitoring service
mysql

Complete MySQL instance monitoring:

  • linux:metrics
  • mysql:metrics
  • mysql:queries
mongodb

Complete MongoDB instance monitoring:

  • linux:metrics
  • mongodb:metrics
  • mongodb:queries
Visit Percona Store


General Inquiries

For general inquiries, please send us your question and someone will contact you.