pmm-admin - PMM Administration Tool¶
NAME¶
pmm-admin
- Administer PMM
SYNOPSIS¶
pmm-admin [FLAGS]
pmm-admin config [FLAGS] --server-url=server-url
pmm-admin add DATABASE [FLAGS] [NAME] [ADDRESS]
DATABASE:= [MongoDB | MySQL | PostgreSQL | ProxySQL]
pmm-admin add --pmm-agent-listen-port=LISTEN_PORT DATABASE [FLAGS] [NAME] [ADDRESS]
pmm-admin add external [FLAGS] [NAME] [ADDRESS]
(CAUTION: Technical preview feature)
pmm-admin add haproxy [FLAGS] [NAME]
pmm-admin add external [FLAGS] [NAME] [ADDRESS]
pmm-admin add external-serverless [FLAGS] [NAME] [ADDRESS]
pmm-admin remove [FLAGS] service-type [service-name]
pmm-admin register [FLAGS] [node-address] [node-type] [node-name]
pmm-admin list [FLAGS] [node-address]
pmm-admin status [FLAGS] [node-address]
pmm-admin summary [FLAGS] [node-address]
pmm-admin annotate [--node|--service] [--tags <tags>] [node-name|service-name]
pmm-admin help [COMMAND]
DESCRIPTION¶
pmm-admin
is a command-line tool for administering PMM using a set of COMMAND keywords and associated FLAGS.
PMM communicates with the PMM Server via a PMM agent process.
COMMON FLAGS¶
-h
,--help
- Show help and exit.
--help-long
- Show extended help and exit.
--help-man
- Generate
man
page. (Usepmm-admin --help-man | man -l -
to view.) --debug
- Enable debug logging.
--trace
- Enable trace logging (implies debug).
--json
- Enable JSON output.
--version
- Show the application version and exit.
--server-url=server-url
- PMM Server URL in
https://username:password@pmm-server-host/
format. --server-insecure-tls
- Skip PMM Server TLS certificate validation.
--group=<group-name>
- Group name for external services. Default:
external
COMMANDS¶
GENERAL COMMANDS¶
pmm-admin help [COMMAND]
- Show help for
COMMAND
.
INFORMATION COMMANDS¶
pmm-admin list --server-url=server-url [FLAGS]
- Show Services and Agents running on this Node, and the agent mode (push/pull).
pmm-admin status --server-url=server-url [FLAGS]
-
Show the following information about a local pmm-agent, and its connected server and clients:
- Agent: Agent ID, Node ID.
- PMM Server: URL and version.
- PMM Client: connection status, time drift, latency,
vmagent
status,pmm-admin
version. - Agents: Agent ID path and client name.
FLAGS:
--wait=<period><unit>
- Time to wait for a successful response from pmm-agent. period is an integer. unit is one of
ms
for milliseconds,s
for seconds,m
for minutes,h
for hours.
pmm-admin summary --server-url=server-url [FLAGS]
-
Creates an archive file in the current directory with default file name
summary_<hostname>_<year>_<month>_<date>_<hour>_<minute>_<second>.zip
. The contents are two directories,client
andserver
containing diagnostic text files.FLAGS:
--filename="filename"
- The Summary Archive filename.
--skip-server
- Skip fetching
logs.zip
from PMM Server. --pprof
- Include performance profiling data in the summary.
CONFIGURATION COMMANDS¶
pmm-admin config
¶
pmm-admin config [FLAGS] [node-address] [node-type] [node-name]
-
Configure a local
pmm-agent
.FLAGS:
--node-id=node-id
- Node ID (default is auto-detected).
--node-model=node-model
- Node model.
--region=region
- Node region.
--az=availability-zone
- Node availability zone.
--metrics-mode=mode
- Metrics flow mode for agents node-exporter. Allowed values:
-
auto
: chosen by server (default). -push
: agent will push metrics. -pull
: server scrapes metrics from agent. --paths-base=dir
- Base path where all binaries, tools and collectors of PMM client are located
pmm-admin register
¶
pmm-admin register [FLAGS] [node-address] [node-type] [node-name]
-
Register the current Node with the PMM Server.
--server-url=server-url
- PMM Server URL in
https://username:password@pmm-server-host/
format. --machine-id="/machine_id/9812826a1c45454a98ba45c56cc4f5b0"
- Node machine-id (default is auto-detected).
--distro="linux"
- Node OS distribution (default is auto-detected).
--container-id=container-id
- Container ID.
--container-name=container-name
- Container name.
--node-model=node-model
- Node model.
--region=region
- Node region.
--az=availability-zone
- Node availability zone.
--custom-labels=labels
- Custom user-assigned labels.
pmm-admin add --pmm-agent-listen-port=LISTEN_PORT
¶
pmm-admin add --pmm-agent-listen-port=LISTEN_PORT DATABASE [FLAGS] [NAME] [ADDRESS]
-
Configure the PMM agent with a listen port.
--pmm-agent-listen-port=LISTEN_PORT
- The PMM agent listen port.
DATABASE:= [MongoDB | MySQL | PostgreSQL | ProxySQL]
pmm-admin remove
¶
pmm-admin remove [FLAGS] service-type [service-name]
-
Remove Service from monitoring.
--service-id=service-id
- Service ID.
--force
- Remove service with that name or ID and all dependent services and agents.
When you remove a service, collected data remains on PMM Server for the specified retention period.
pmm-admin annotate
¶
pmm-admin annotate [--node|--service] <annotation> [--tags <tags>] [--node-name=<node>] [--service-name=<service>]
-
Annotate an event. (Read more)
<annotation>
- The annotation string. If it contains spaces, it should be quoted.
--node
- Annotate the current node or that specified by
--node-name
. --service
- Annotate all services running on the current node, or that specified by
--service-name
. --tags
- A quoted string that defines one or more comma-separated tags for the annotation. Example:
"tag 1,tag 2"
. --node-name
- The node name being annotated.
--service-name
- The service name being annotated.
Combining flags
Flags may be combined as shown in the following examples.
--node
- Current node.
--node-name
- Node with name.
--node --node-name=NODE_NAME
- Node with name.
--node --service-name
- Current node and service with name.
--node --node-name --service-name
- Node with name and service with name.
--node --service
- Current node and all services of current node.
-node --node-name --service --service-name
- Service with name and node with name.
--service
- All services of the current node.
--service-name
- Service with name.
--service --service-name
- Service with name.
--service --node-name
- All services of current node and node with name.
--service-name --node-name
- Service with name and node with name.
--service --service-name -node-name
- Service with name and node with name.
Tip
If node or service name is specified, they are used instead of other parameters.
DATABASE COMMANDS¶
MongoDB¶
pmm-admin add mongodb [FLAGS] [node-name] [node-address]
-
Add MongoDB to monitoring.
FLAGS:
--node-id=node-id
- Node ID (default is auto-detected).
--pmm-agent-id=pmm-agent-id
- The pmm-agent identifier which runs this instance (default is auto-detected).
--username=username
- MongoDB username.
--password=password
- MongoDB password.
--agent-password=password
-
Override the default password for accessing the
/metrics
endpoint. (Username ispmm
and default password is the agent ID.)Avoid using special characters like ‘', ‘;’ and ‘$’ in the custom password.
--query-source=profiler
- Source of queries, one of:
profiler
,none
(default:profiler
). --environment=environment
- Environment name.
--cluster=cluster
- Cluster name.
--replication-set=replication-set
- Replication set name.
--custom-labels=custom-labels
- Custom user-assigned labels.
--skip-connection-check
- Skip connection check.
--tls
- Use TLS to connect to the database.
--tls-skip-verify
- Skip TLS certificates validation.
--tls-certificate-key-file=PATHTOCERT
- Path to TLS certificate file.
--tls-certificate-key-file-password=IFPASSWORDTOCERTISSET
- Password for TLS certificate file.
--tls-ca-file=PATHTOCACERT
- Path to certificate authority file.
--metrics-mode=mode
- Metrics flow mode for agents node-exporter. Allowed values:
-
auto
: chosen by server (default). -push
: agent will push metrics. -pull
: server scrapes metrics from agent.
Advanced Options¶
-
PMM starts the MongoDB exporter by default only with
diagnosticdata
andreplicasetstatus
collectors enabled.FLAGS:
--enable-all-collectors
- Enable all collectors.
--disable-collectors
- Comma-separated list of collector names to exclude from exporter.
--max-collections-limit=-1
-
Disable collstats, dbstats, topmetrics and indexstats if there are more than
collections. 0: No limit. Default is -1, PMM automatically sets this value. A very high limit of
max-collections-limit
could impact the CPU and Memory usage. Check--stats-collections
to limit the scope of collections and DB’s metrics to be fetched. --stats-collections=db1,db2.col1
- Collections for collstats & indexstats.
Enable all collectors¶
To enable all collectors, pass the parameter --enable-all-collectors
in the pmm-admin add mongodb
command.
This will enable collstats
, dbstats
, indexstats
, and topmetrics
collectors.
Disable some collectors¶
To enable only some collectors, pass the parameter --enable-all-collectors
along with the parameter --disable-collectors
.
For example, if you want all collectors except topmetrics
, specify:
--enable-all-collectors --disable-collectors=topmetrics
Limit dbStats, collStats and indexStats¶
By default, PMM decides the limit for the number of collections to monitor the collStats and indexStats collectors.
You can also set an additional limit for the collStats, indexStats, dbStats, and topmetrics collectors with the –max-collections-limit parameter.
Set the value of the parameter --max-collections-limit
to:
- 0: which indicates that collStats and indexStats can handle unlimited collections.
- n, which indicates that collStats and indexStats can handle <=n collections. If the limit is crossed - exporter stops collecting monitoring data for the collStats and indexStats collectors.
- -1 (default) doesn’t need to be explicitly set. It indicates that PMM decides how many collections it would monitor, currently <=200 (subject to change).
To further limit collections to monitor, enable collStats and indexStats for some databases or collections:
- Specify the databases and collections that collStats and indexStats will use to collect data using the parameter
--stats-collections
. This parameter receives a comma-separated list of namespaces in the formdatabase[.collection]
.
Examples¶
To add MongoDB with all collectors (diagnosticdata
, replicasetstatus
, collstats
, dbstats
, indexstats
, and topmetrics
) with default limit detected by PMM (currently <=200 collections, but subject to change):
pmm-admin add mongodb --username=admin --password=admin_pass --enable-all-collectors mongodb_srv_1 127.0.0.1:27017
To add MongoDB with all collectors (diagnosticdata, replicasetstatus, collstats, dbstats, indexstats, and topmetrics) with max-collections-limit
set to 1000:
pmm-admin add mongodb --username=admin --password=admin_pass --enable-all-collectors --max-collections-limit=1000 mongodb_srv_1 127.0.0.1:27017
To enable all the collectors with an unlimited number of collections monitored:
pmm-admin add mongodb --username=admin --password=admin_pass --enable-all-collectors --max-collections-limit=0 mongodb_srv_1 127.0.0.1:27017
To add MongoDB with default collectors (diagnosticdata
and replicasetstatus
):
pmm-admin add mongodb --username=admin --password=admin_pass mongodb_srv_1 127.0.0.1:27017
Disable collstats
collector and enable all the others without limiting max-collections-limit
:
pmm-admin add mongodb --username=admin --password=admin_pass --enable-all-collectors --max-collections-limit=0 --disable-collectors=collstats mongodb_srv_1 127.0.0.1:27017
If --stats-collections=db1,db2.col1
then the collectors are run as follows:
Database | Collector is run on |
---|---|
db1 | All the collections |
db2 | Only for collection col1 |
Enable all collectors and limit monitoring for dbstats
, indexstats
, collstats
and topmetrics
for all collections in db1
and col1
collection in db2
, without limiting max-collections-limit
for a number of collections in db1
:
pmm-admin add mongodb --username=admin --password=admin_pass --enable-all-collectors --max-collections-limit=0 --stats-collections=db1,db2.col1 mongodb_srv_1 127.0.0.1:27017
Resolutions¶
PMM collects metrics in two resolutions to decrease CPU and Memory usage: high and low resolutions.
In high resolution we collect metrics from collectors which work fast: - diagnosticdata - replicasetstatus - topmetrics
In low resolution we collect metrics from collectors which could take some time: - dbstats - indexstats - collstats
MySQL¶
pmm-admin add mysql [FLAGS] node-name node-address | [--name=service-name] --address=address[:port] | --socket
-
Add MySQL to monitoring.
FLAGS:
--address
- MySQL address and port (default: 127.0.0.1:3306).
--socket=socket
- Path to MySQL socket. (Find the socket path with
mysql -u root -p -e "select @@socket"
.) --node-id=node-id
- Node ID (default is auto-detected).
--pmm-agent-id=pmm-agent-id
- The pmm-agent identifier which runs this instance (default is auto-detected).
--username=username
- MySQL username.
--password=password
- MySQL password.
--agent-password=password
-
Override the default password for accessing the
/metrics
endpoint. (Username ispmm
and default password is the agent ID.)Avoid using special characters like ‘', ‘;’ and ‘$’ in the custom password.
--query-source=slowlog
- Source of SQL queries, one of:
slowlog
,perfschema
,none
(default:slowlog
). Forslowlog
query source you need change permissions for specific files. Root permissions are needed for this. --size-slow-logs=N
-
Rotate slow log file at this size. If
0
, use server-defined default. Negative values disable log rotation. A unit suffix must be appended to the number and can be one of:KiB
,MiB
,GiB
,TiB
for base 2 units (1024, 1048576, etc).
--disable-queryexamples
- Disable collection of query examples.
--disable-tablestats
-
Disable table statistics collection.
Excluded collectors for low-resolution time intervals:
--collect.auto_increment.columns
--collect.info_schema.tables
--collect.info_schema.tablestats
--collect.perf_schema.indexiowaits
--collect.perf_schema.tableiowaits
--collect.perf_schema.file_instances
Excluded collectors for medium-resolution time intervals:
--collect.perf_schema.tablelocks
--disable-tablestats-limit=disable-tablestats-limit
- Table statistics collection will be disabled if there are more than specified number of tables (default: server-defined). 0=no limit. Negative value disables collection.
--environment=environment
- Environment name.
--cluster=cluster
- Cluster name.
--replication-set=replication-set
- Replication set name.
--custom-labels=custom-labels
- Custom user-assigned labels.
--skip-connection-check
- Skip connection check.
--tls
- Use TLS to connect to the database.
--tls-skip-verify
- Skip TLS certificates validation.
--tls-cert-file=PATHTOCERT
- Path to TLS client certificate file.
--tls-key=PATHTOCERTKEY
- Key for TLS client certificate file.
--tls-ca-file=PATHTOCACERT
- Path to certificate authority file.
--ssl-ca=PATHTOCACERT
- The path name of the Certificate Authority (CA) certificate file. If used must specify the same certificate used by the server. (-ssl-capath is similar but specifies the path name of a directory of CA certificate files.)
--ssl-cert=PATHTOCERTKEY
- The path name of the client public key certificate file.
--ssl-key
- The path name of the client private key file.
--ssl-skip-verify
- Skip SSL certificate verification.
--metrics-mode=mode
- Metrics flow mode for agents node-exporter. Allowed values:
-
auto
: chosen by server (default). -push
: agent will push metrics. -pull
: server scrapes metrics from agent.
PostgreSQL¶
pmm-admin add postgresql [FLAGS] [node-name] [node-address]
-
Add PostgreSQL to monitoring.
FLAGS:
--node-id=<node id>
- Node ID (default is auto-detected).
--pmm-agent-id=<pmm agent id>
- The pmm-agent identifier which runs this instance (default is auto-detected).
--username=<username>
- PostgreSQL username.
--password=<password>
- PostgreSQL password.
--database=<database>
- PostgreSQL database (default: postgres).
--agent-password=password
-
Override the default password for accessing the
/metrics
endpoint. (Username ispmm
and default password is the agent ID.)Avoid using special characters like ‘', ‘;’ and ‘$’ in the custom password.
--query-source=<query source>
- Source of SQL queries, one of:
pgstatements
,pgstatmonitor
,none
(default:pgstatements
). --environment=<environment>
- Environment name.
--cluster=<cluster>
- Cluster name.
--replication-set=<replication set>
- Replication set name.
--custom-labels=<custom labels>
- Custom user-assigned labels.
--skip-connection-check
- Skip connection check.
--tls
- Use TLS to connect to the database.
--tls-skip-verify
- Skip TLS certificates validation.
--tls-ca-file
- TLS CA certificate file.
--tls-cert-file
- TLS certificate file.
--tls-key-file
- TLS certificate key file.
--metrics-mode=mode
- Metrics flow mode for agents node-exporter. Allowed values:
-
auto
: chosen by server (default). -push
: agent will push metrics. -pull
: server scrapes metrics from agent.
ProxySQL¶
pmm-admin add proxysql [FLAGS] [node-name] [node-address]
-
Add ProxySQL to monitoring.
FLAGS:
--node-id=node-id
- Node ID (default is auto-detected).
--pmm-agent-id=pmm-agent-id
- The pmm-agent identifier which runs this instance (default is auto-detected).
--username=username
- ProxySQL username.
--password=password
- ProxySQL password.
--agent-password=password
-
Override the default password for accessing the
/metrics
endpoint. (Username ispmm
and default password is the agent ID.)Avoid using special characters like ‘', ‘;’ and ‘$’ in the custom password.
--environment=environment
- Environment name.
--cluster=cluster
- Cluster name.
--replication-set=replication-set
- Replication set name.
--custom-labels=custom-labels
- Custom user-assigned labels.
--skip-connection-check
- Skip connection check.
--tls
- Use TLS to connect to the database.
--tls-skip-verify
- Skip TLS certificates validation.
--metrics-mode=mode
- Metrics flow mode for agents node-exporter. Allowed values:
-
auto
: chosen by server (default). -push
: agent will push metrics. -pull
: server scrapes metrics from agent. --disable-collectors
- Comma-separated list of collector names to exclude from exporter.
HAProxy¶
pmm-admin add haproxy [FLAGS] [NAME]
-
Add HAProxy to monitoring.
FLAGS:
--server-url=SERVER-URL
- PMM Server URL in
https://username:password@pmm-server-host/
format. --server-insecure-tls
- Skip PMM Server TLS certificate validation.
--username=USERNAME
- HAProxy username.
--password=PASSWORD
- HAProxy password.
--scheme=SCHEME
- Scheme to generate URI to exporter metrics endpoints (http or https).
--metrics-path=METRICS-PATH
- Path under which metrics are exposed, used to generate URI (default: /metrics).
--listen-port=LISTEN-PORT
- Listen port of haproxy exposing the metrics for scraping metrics (Required).
--service-node-id=SERVICE-NODE-ID
- Node ID where service runs (default is auto-detected).
--environment=ENVIRONMENT
- Environment name like ‘production’ or ‘qa’.
--cluster=CLUSTER
- Cluster name.
--replication-set=REPLICATION-SET
- Replication set name.
--custom-labels=CUSTOM-LABELS
- Custom user-assigned labels. Example: region=east,app=app1.
--metrics-mode=MODE
- Metrics flow mode for agents node-exporter. Allowed values:
-
auto
: chosen by server (default). -push
: agent will push metrics. -pull
: server scrapes metrics from agent. --skip-connection-check
- Skip connection check.
OTHER COMMANDS¶
pmm-admin add external [FLAGS]
-
Add External source of data (like a custom exporter running on a port) to be monitored.
FLAGS:
--service-name="current-hostname"
- Service name (autodetected defaults to the hostname where
pmm-admin
is running). --agent-node-id=AGENT-NODE-ID
- Node ID where agent runs (default is autodetected).
--username=USERNAME
- External username.
--password=PASSWORD
- External password.
--scheme=http or https
- Scheme to generate URI to exporter metrics endpoints.
--metrics-path=/metrics
- Path under which metrics are exposed, used to generate URI.
--listen-port=LISTEN-PORT
- Listen port of external exporter for scraping metrics. (Required.)
--service-node-id=SERVICE-NODE-ID
- Node ID where service runs (default is autodetected).
--environment=prod
- Environment name like ‘production’ or ‘qa’.
--cluster=east-cluster
- Cluster name.
--replication-set=rs1
- Replication set name.
--custom-labels=CUSTOM-LABELS
- Custom user-assigned labels. Example:
region=east,app=app1
. --metrics-mode=auto
- Metrics flow mode, can be
push
: agent will push metrics,pull
: server scrape metrics from agent orauto
: chosen by server. --group="external"
- Group name of external service. (Default:
external
.)
pmm-admin add external-serverless [FLAGS]
-
Add External Service on Remote node to monitoring.
Usage example:
pmm-admin add external-serverless --url=http://1.2.3.4:9093/metrics
.Also, individual parameters can be set instead of
--url
like:pmm-admin add external-serverless --scheme=http --host=1.2.3.4 --listen-port=9093 --metrics-path=/metrics --container-name=ddd --external-name=e125
.Note that some parameters are mandatory depending on the context. For example, if you specify
--url
,--schema
and other related parameters are not mandatory. But if you specify--host
you must provide all other parameters needed to build the destination URL, or you can specify--address
instead of host and port as individual parameters.FLAGS:
--url=URL
- Full URL to exporter metrics endpoints.
--scheme=https
- Scheme to generate URL to exporter metrics endpoints.
--username=USERNAME
- External username.
--password=PASSWORD
- External password.
--address=1.2.3.4:9000
- External exporter address and port.
--host=1.2.3.4
- External exporters hostname or IP address.
--listen-port=9999
- Listen port of external exporter for scraping metrics.
--metrics-path=/metrics
- Path under which metrics are exposed, used to generate URL.
--environment=testing
- Environment name.
--cluster=CLUSTER
- Cluster name.
--replication-set=rs1
- Replication set name.
--custom-labels='app=myapp,region=s1'
- Custom user-assigned labels.
--group="external"
- Group name of external service. (Default:
external
.) --machine-id=MACHINE-ID
- Node machine-id.
--distro=DISTRO
- Node OS distribution.
--container-id=CONTAINER-ID
- Container ID.
--container-name=CONTAINER-NAME
- Container name.
--node-model=NODE-MODEL
- Node model.
--region=REGION
- Node region.
--az=AZ
- Node availability zone.
EXAMPLES¶
pmm-admin add mysql --query-source=slowlog --username=pmm --password=pmm sl-mysql 127.0.0.1:3306
MySQL Service added.
Service ID : /service_id/a89191d4-7d75-44a9-b37f-a528e2c4550f
Service name: sl-mysql
pmm-admin add mysql --username=pmm --password=pmm --service-name=ps-mysql --host=127.0.0.1 --port=3306
pmm-admin status
pmm-admin status --wait=30s
Agent ID: /agent_id/c2a55ac6-a12f-4172-8850-4101237a4236
Node ID : /node_id/29b2cc24-3b90-4892-8d7e-4b44258d9309
PMM Server:
URL : https://x.x.x.x:443/
Version: 2.5.0
PMM Client:
Connected : true
Time drift: 2.152715ms
Latency : 465.658µs
pmm-admin version: 2.5.0
pmm-agent version: 2.5.0
Agents:
/agent_id/aeb42475-486c-4f48-a906-9546fc7859e8 mysql_slowlog_agent Running
Disable collectors¶
pmm-admin add mysql --disable-collectors='heartbeat,global_status,info_schema.innodb_cmp' --username=pmm --password=pmm --service-name=db1-mysql --host=127.0.0.1 --port=3306
For other collectors that you can disable with the --disable-collectors
option, please visit the official repositories for each exporter: