Skip to content
logo
Percona Monitoring and Management
pmm-agent - PMM Client agent
Initializing search
    percona/pmm-doc
    percona/pmm-doc
    • Welcome
        • Network
        • Docker
        • Podman
        • Helm
        • Virtual Appliance
        • AWS Marketplace
        • Easy-install script
        • MySQL
        • MongoDB
        • PostgreSQL
        • ProxySQL
        • Amazon RDS
        • Microsoft Azure
        • Google Cloud Platform
        • Linux
        • External Services
        • HAProxy
        • Remote instances
      • User Interface
      • Percona Alerting
        • Prepare a storage location
          • MongoDB backup prerequisites
          • Create MongoDB on-demand and scheduled backups
          • Create MongoDB PITR backups
          • Restore a MongoDB backup
          • MongoDB Backup and Restore support matrix
          • MySQL backup prerequisites
          • Create a MySQL backup
          • Restore a MySQL backup
        • Edit a scheduled backup
        • Delete a backup
        • Configure access control
        • Labels for access control
        • Create access roles
        • Manage access roles
        • Assign roles to users
        • Use Case
      • Query Analytics
      • Working with Advisors
      • Configure
      • Manage users
      • Upgrade
      • Secure
      • Optimize
      • Annotate
      • Share dashboards and panels
      • Extend Metrics
      • Resolve issues
        • Check Percona Portal account information
      • Architecture
      • UI components
      • PMM components and versions
      • Data handling in PMM
      • Develop Advisor checks
      • PMM Inventory
        • Manage dashboards
            • Advanced Data Exploration
            • VictoriaMetrics
            • VictoriaMetrics Agents Overview
            • Environment Summary
            • Kubernetes Pods Status
            • Kubernetes Volumes
          • DBaas
            • Disk Details
            • Network Details
            • Memory Details
            • Node Temperature Details
            • Nodes Compare
            • Nodes Overview
            • Node Summary
            • NUMA Details
            • Processes Details
            • Prometheus Exporters Overview
            • MySQL Command/Handler Counters Compare
            • MySQL InnoDB Compression Details
            • MySQL InnoDB Details
            • MySQL MyISAM/Aria Details
            • MySQL MyRocks Details
            • MySQL Instance Summary
            • MySQL Instances Compare
            • MySQL Instances Overview
            • MySQL Wait Event Analyses Details
            • MySQL Performance Schema Details
            • MySQL Query Response Time Details
            • MySQL Replication Summary
            • MySQL Group Replication Summary
            • MySQL Table Details
            • MySQL User Details
            • MySQL TokuDB Details
            • Experimental MongoDB Collection Details
            • Experimental MongoDB Oplog Details
            • MongoDB Cluster Summary
            • MongoDB Instance Summary
            • MongoDB Instances Overview
            • MongoDB Instances Compare
            • MongoDB ReplSet Summary
            • MongoDB InMemory Details
            • MongoDB MMAPv1 Details
            • MongoDB WiredTiger Details
            • PostgreSQL Instance Summary
            • PostgreSQL Instances Compare
            • Experimental PostgreSQL Vacuum Monitoring
          • ProxySQL Dashboards
            • PXC/Galera Cluster Summary
            • Experimental PXC/Galera Cluster Summary
            • PXC/Galera Nodes Compare
            • HAProxy Instance Summary
        • pmm-admin - PMM Administration Tool
        • pmm-agent - PMM Client agent
          • NAME
          • SYNOPSIS
          • DESCRIPTION
          • COMMANDS
          • OPTIONS AND ENVIRONMENT
          • USAGE AND EXAMPLES OF paths-base FLAG
          • LOGGING
      • API
      • VictoriaMetrics
      • ClickHouse
      • PostgreSQL
      • Glossary
      • Introduction
      • DBaaS architecture
        • Setting up DBaaS
        • Create a Kubernetes Cluster
        • Deleting Kubernetes clusters
        • Activating DBaaS
        • Add a Kubernetes cluster automatically
        • Add a Kubernetes cluster manually
        • Manage allowed component versions
          • OLM installation
          • Operators installation
        • Add a DB Cluster
        • Manage a DB Cluster
        • Delete a DB Cluster
        • Create a database cluster from a template
      • Backup and restore
    • FAQ
      • PMM 2.39.0
      • PMM 2.38.1
      • PMM 2.38.0
      • PMM 2.37.1
      • PMM 2.37.0
      • PMM 2.36.0
      • PMM 2.35.0
      • PMM 2.34.0
      • PMM 2.33.0
      • PMM 2.32.0
      • PMM 2.31.0
      • PMM 2.30.0
      • PMM 2.29.1
      • PMM 2.29.0
      • PMM 2.28.0
      • PMM 2.27.0
      • PMM 2.26.0
      • PMM 2.25.0
      • PMM 2.24.0
      • PMM 2.23.0
      • PMM 2.22.0
      • PMM 2.21.0
      • PMM 2.20.0
      • PMM 2.19.0
      • PMM 2.18.0
      • PMM 2.17.0
      • PMM 2.16.0
      • PMM 2.15.1
      • PMM 2.15.0
      • PMM 2.14.0
      • PMM 2.13.0
      • PMM 2.12.0
      • PMM 2.11.1
      • PMM 2.11.0
      • PMM 2.10.1
      • PMM 2.10.0
      • PMM 2.9.1
      • PMM 2.9.0
      • PMM 2.8.0
      • PMM 2.7.0
      • PMM 2.6.1
      • PMM 2.6.0
      • PMM 2.5.0
      • PMM 2.4.0
      • PMM 2.3.0
      • PMM 2.2.2
      • PMM 2.2.1
      • PMM 2.2.0
      • PMM 2.1.0
      • PMM 2.0.1
      • PMM 2.0.0
      • Copyright and licensing information
      • Trademark policy

    • NAME
    • SYNOPSIS
    • DESCRIPTION
    • COMMANDS
    • OPTIONS AND ENVIRONMENT
    • USAGE AND EXAMPLES OF paths-base FLAG
    • LOGGING

    pmm-agent - PMM Client agent¶

    NAME¶

    pmm-agent - The PMM Client daemon program.

    SYNOPSIS¶

    pmm-agent [command] [options]

    DESCRIPTION¶

    pmm-agent, part of the PMM Client package, runs as a daemon process on all monitored hosts.

    COMMANDS¶

    pmm-agent run
    Run pmm-agent (default).
    pmm-agent setup [node-address] [node-type] [node-name]
    Configure local pmm-agent (requires root permissions)
    pmm-agent help [command]
    Show help (for command) and exit.

    OPTIONS AND ENVIRONMENT¶

    Most options can be set via environment variables (shown in parentheses).

    Option Environment variable Description
    --server-password=SERVER-PASSWORD PMM_AGENT_SERVER_PASSWORD Password to connect to PMM Server.
    --server-username=SERVER-USERNAME PMM_AGENT_SERVER_USERNAME Username to connect to PMM Server.
    --server-address=host:port PMM_AGENT_SERVER_ADDRESS PMM Server address and port number.
    --server-insecure-tls PMM_AGENT_SERVER_INSECURE_TLS Skip PMM Server TLS certificate validation.
    --az=AZ PMM_AGENT_SETUP_AZ Node availability zone.
    --config-file=path_to/pmm-agent.yaml PMM_AGENT_CONFIG_FILE Configuration file path and name.
    --container-id=CONTAINER-ID PMM_AGENT_SETUP_CONTAINER_ID Container ID.
    --container-name=CONTAINER-NAME PMM_AGENT_SETUP_CONTAINER_NAME Container name.
    --debug PMM_AGENT_DEBUG Enable debug output.
    --distro=distro PMM_AGENT_SETUP_DISTRO Node OS distribution (default is auto-detected).
    --force PMM_AGENT_SETUP_FORCE Remove Node with that name and all dependent Services and Agents (if existing).
    --id=/agent_id/... PMM_AGENT_ID ID of this pmm-agent.
    --listen-address=LISTEN-ADDRESS PMM_AGENT_LISTEN_ADDRESS Agent local API address.
    --listen-port=LISTEN-PORT PMM_AGENT_LISTEN_PORT Agent local API port.
    --machine-id=machine-id PMM_AGENT_SETUP_MACHINE_ID Node machine ID (default is auto-detected).
    --metrics-mode=auto PMM_AGENT_SETUP_METRICS_MODE Metrics flow mode for agents node-exporter. Can be push (agent will push metrics), pull (server scrapes metrics from agent) or auto (chosen by server).
    --node-model=NODE-MODEL PMM_AGENT_SETUP_NODE_MODEL Node model.
    --paths-base=PATH PMM_AGENT_PATHS_BASE Base path for PMM client, where all binaries, tools and collectors are located. If not set, default is /usr/local/percona/pmm2.
    --paths-exporters_base=PATH PMM_AGENT_PATHS_EXPORTERS_BASE Base path for exporters to use. If not set, or set to a relative path, uses value of --paths-base prepended to it.
    --paths-mongodb_exporter=PATH PMM_AGENT_PATHS_MONGODB_EXPORTER Path to mongodb_exporter.
    --paths-mysqld_exporter=PATH PMM_AGENT_PATHS_MYSQLD_EXPORTER Path to mysqld_exporter.
    --paths-node_exporter=PATH PMM_AGENT_PATHS_NODE_EXPORTER Path to node_exporter.
    --paths-postgres_exporter=PATH PMM_AGENT_PATHS_POSTGRES_EXPORTER Path to postgres_exporter.
    --paths-proxysql_exporter=PATH PMM_AGENT_PATHS_PROXYSQL_EXPORTER Path to proxysql_exporter.
    --paths-pt-summary=PATH PMM_AGENT_PATHS_PT_SUMMARY Path to pt-summary.
    --paths-pt-mysql-summary=PATH PMM_AGENT_PATHS_PT_MYSQL_SUMMARY Path to pt-mysql-summary.
    --paths-pt-pg-summary=PATH PMM_AGENT_PATHS_PT_PG_SUMMARY Path to pt-pg-summary.
    --paths-tempdir=PATH PMM_AGENT_PATHS_TEMPDIR Temporary directory for exporters.
    --ports-max=PORTS-MAX PMM_AGENT_PORTS_MAX Highest allowed port number for listening sockets.
    --ports-min=PORTS-MIN PMM_AGENT_PORTS_MIN Lowest allowed port number for listening sockets.
    --region=REGION PMM_AGENT_SETUP_REGION Node region.
    --skip-registration PMM_AGENT_SETUP_SKIP_REGISTRATION Skip registration on PMM Server.
    --trace PMM_AGENT_TRACE Enable trace output (implies --debug).
    -h, --help Show help (synonym for pmm-agent help).
    --version Show application version, PMM version, time-stamp, git commit hash and branch.

    USAGE AND EXAMPLES OF paths-base FLAG¶

    Since 2.23.0 this flag could be used for easier setup of pmm agent. With this flag, the root permissions for PMM client aren’t needed anymore, and it will be

    Since 2.23.0 this flag could be used for easier setup of PMM agent. With this flag the root permissions for PMM client aren’t needed anymore and it will be fully working.

    Examples:

    • Case 1: There are no root permissions for /usr/local/percona/pmm2 folder or there is a need to change default folder for PMM files. Command:

      pmm-agent setup --paths-base=/home/user/custom/pmm2 --config-file=pmm-agent-dev.yaml --server-insecure-tls --server-address=127.0.0.1:443 --server-username=admin --server-password=admin
      
      Config output:
      # Updated by `pmm-agent setup`.
      ---
      id: /agent_id/be568008-b1b4-4bd9-98c7-392d1f4b724e
      listen-address: 127.0.0.1
      listen-port: 7777
      server:
          address: 127.0.0.1:443
          username: admin
          password: admin
          insecure-tls: true
      paths:
          paths_base: /home/user/custom/pmm2
          exporters_base: /home/user/custom/pmm2/exporters
          node_exporter: /home/user/custom/pmm2/exporters/node_exporter
          mysqld_exporter: /home/user/custom/pmm2/exporters/mysqld_exporter
          mongodb_exporter: /home/user/custom/pmm2/exporters/mongodb_exporter
          postgres_exporter: /home/user/custom/pmm2/exporters/postgres_exporter
          proxysql_exporter: /home/user/custom/pmm2/exporters/proxysql_exporter
          rds_exporter: /home/user/custom/pmm2/exporters/rds_exporter
          azure_exporter: /home/user/custom/pmm2/exporters/azure_exporter
          vmagent: /home/user/custom/pmm2/exporters/vmagent
          tempdir: /tmp
          pt_summary: /home/user/custom/pmm2/tools/pt-summary
          pt_pg_summary: /home/user/custom/pmm2/tools/pt-pg-summary
          pt_mysql_summary: /home/user/custom/pmm2/tools/pt-mysql-summary
          pt_mongodb_summary: /home/user/custom/pmm2/tools/pt-mongodb-summary
      ports:
          min: 42000
          max: 51999
      debug: false
      trace: false
      
      As could be seen above, base for all exporters and tools was changed only by setting --paths-base. With this tag the folder for PMM that doesn’t require root access could be specified.

    • Case 2: The older --paths-exporters_base flag could be passed along with the --paths-base Command:

      pmm-agent setup --paths-base=/home/user/custom/pmm2 --paths-exporters_base=/home/user/exporters --config-file=pmm-agent-dev.yaml --server-insecure-tls --server-address=127.0.0.1:443 --server-username=admin --server-password=admin
      
      Config output:
      # Updated by `pmm-agent setup`.
      ---
      id: /agent_id/afce1917-8836-4857-b3e5-ad372c2ddbe5
      listen-address: 127.0.0.1
      listen-port: 7777
      server:
          address: 127.0.0.1:443
          username: admin
          password: admin
          insecure-tls: true
      paths:
          paths_base: /home/user/custom/pmm2
          exporters_base: /home/user/exporters
          node_exporter: /home/user/exporters/node_exporter
          mysqld_exporter: /home/user/exporters/mysqld_exporter
          mongodb_exporter: /home/user/exporters/mongodb_exporter
          postgres_exporter: /home/user/exporters/postgres_exporter
          proxysql_exporter: /home/user/exporters/proxysql_exporter
          rds_exporter: /home/user/exporters/rds_exporter
          azure_exporter: /home/user/exporters/azure_exporter
          vmagent: /home/user/exporters/vmagent
          tempdir: /tmp
          pt_summary: /home/user/custom/pmm2/tools/pt-summary
          pt_pg_summary: /home/user/custom/pmm2/tools/pt-pg-summary
          pt_mysql_summary: /home/user/custom/pmm2/tools/pt-mysql-summary
          pt_mongodb_summary: /home/user/custom/pmm2/tools/pt-mongodb-summary
      ports:
          min: 42000
          max: 51999
      debug: false
      trace: false
      
      As could be seen above the behavior for the --paths-base was the same, but paths for all exporters were overwritten by the --paths-exporter_base flag.

    Summary: Flag --paths-base will set path for all exporters and tools, but each one could be overridden by specific flag (like --paths-mongodb_exporter, --paths-pt-mysql-summary and etc).

    LOGGING¶

    By default, pmm-agent sends messages to stderr and to the system log (syslogd or journald on Linux).

    To get a separate log file, edit the pmm-agent start-up script.

    systemd-based systems

    • Script file: /usr/lib/systemd/system/pmm-agent.service
    • Parameter: StandardError
    • Default value: file:/var/log/pmm-agent.log

    Example:

    StandardError=file:/var/log/pmm-agent.log
    

    initd-based systems

    • Script file: /etc/init.d/pmm-agent
    • Parameter: pmm_log
    • Default value: /var/log/pmm-agent.log

    Example:

    pmm_log="/var/log/pmm-agent.log"
    

    If you change the default log file name, reflect the change in the log rotation rules file /etc/logrotate.d/pmm-agent-logrotate.

    Contact us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: 2023-09-22
    Percona LLC, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better. Read more about Percona Cookie Policy.