pt-agent

NAME

pt-agent - Agent for Percona Cloud Tools

SYNOPSIS

Usage

pt-agent [OPTIONS]

pt-agent is the client-side agent for Percona Cloud Tools. It is not a general command line tool like other tools in Percona Toolkit, it is configured and controlled through the web at https://cloud.percona.com. Visit https://cloud.percona.com for more information and to sign up.

DESCRIPTION

pt-agent is the client-side agent for Percona Cloud Tools (PCT). It is controlled and configured through the web app at https://cloud.percona.com. Visit https://cloud.percona.com for more information and to sign up.

pt-agent, or “the agent”, is a single, unique instance of the tool running on a server. Two agents cannot run on the same server (see --pid).

The agent is a daemon that runs as root. It should be started with --daemonize. It connects periodically to Percona to update its configuration and services, and it schedules --run-service and --send-data instances of itself using cron. Other than “INSTALLING” and starting the agent locally, all control and configuration is done through the web at https://cloud.percona.com.

INSTALLING

pt-agent must be installed and ran as root. It is possible to run as a non-root user, but this requires a more complicated and manual installation. Please contact Percona for help if you need to run pt-agent as a non-root user.

Installing the agent as root is very simple:

# pt-agent --install

The agent will prompt you for your Percona Cloud Tools API key. Then it will verify the API key, create a MySQL user for the agent, and run the agent. When the install process is complete, go to https://cloud.percona.com to enable services for agent.

Please contact Percona if you need help installing the agent.

SLAVE INSTALL

There are two ways to install pt-agent on a slave. The first and best way is to install the agent on the master so that the “MYSQL USER” is created on the master and replicates to slaves. This is best because it avoids writing to the slave. Then create the /etc/percona/agent/ directory on the slave and copy in to it /etc/percona/agent/my.cnf from the master. Run --install on the slave and pt-agent will automatically detect and use the MySQL user and password in /etc/percona/agent/my.cnf. Repeat the process for other slaves.

The second way to install pt-agent on a slave is not safe because it writes directly to the slave: specify --install-options force_dangerous_slave_install in addition to --install. As the install option name implies, this is dangerous, but it forces pt-agent to ignore that MySQL is a slave.

Percona XtraDB Cluster (PXC) INSTALL

Installing pt-agent on Percona XtraDB Cluster (PXC) nodes is the same as installing it safely on slaves. First install the agent on any node. This will create the “MYSQL USER” that will replicate to all other nodes. Then create the /etc/percona/agent/ directory on another node and copy in to it /etc/percona/agent/my.cnf from the first node where pt-agent was installed. Run --install on the node and pt-agent will automatically detect and use the MySQL user and password in /etc/percona/agent/my.cnf. Repeat the process for other nodes.

MYSQL USER

During --install, pt-agent creates the following MySQL user:

GRANT SUPER, USAGE ON *.* TO 'pt_agent'@'localhost' IDENTIFIED BY 'pass'

pass is a random string. MySQL options for the agent are stored in /etc/percona/agent/my.cnf. The SUPER privilege is required so that the agent can set global MySQL variables like long_query_time.

EXIT STATUS

pt-agent exists zero if no errors or warnings occurred, else it exits non-zero.

OPTIONS

--run-service and --send-data are mutually exclusive.

--status, --stop, and --reset are mutually exclusive.

--[no]agent-api

default: yes

Enable the agent API; do not use this option manually. This option is used internally to allow the agent to stop itself and shutdown quickly.

--agent-uuid

type: string

Existing agent UUID for re-installing an agent.

--api-key

type: string

Your secret Percona Cloud Tools API key.

--ask-pass

Prompt for MySQL password.

--check-interval

type: time; default: 1m

How often to check for a new configuration and services.

--config

type: Array

Read this comma-separated list of config files; if specified, this must be the first option on the command line.

See the --help output for a list of default config files.

--daemonize

Daemonize the agent. This causes the agent to fork into the background and --log all output.

Fork to the background and detach from the shell. POSIX operating systems only.

--defaults-file

short form: -F; type: string

Only read MySQL options from the given file. You must give an absolute pathname.

--disk-bytes-free

type: size; default: 100M

Stop all services if the disk has less than this much free space. This prevents the agent from filling up the disk with service data.

Valid size value suffixes are k, M, G, and T.

--disk-pct-free

type: int; default: 5

Stop all services if the disk has less than this percent free space. This prevents the agent from filling up the disk with service data.

This option works similarly to --disk-bytes-free but specifies a percentage margin of safety instead of a bytes margin of safety. The agent honors both options, and will not collect any data unless both margins are satisfied.

--help

Print the agent’s help and exit.

--host

short form: -h; type: string; default: localhost

MySQL host.

--install

Install pt-agent as root.

--install-options

type: Hash

Comma-separated list of --install options. Options are:

offline

Do not verify the API key or start the agent.

force_dangerous_slave_install

Like the option’s name suggests: this forces a dangerous slave install, so you should not use this option unless you are aware of the potential consequences. To install the agent on a slave, /etc/percona/agent/my.cnf must exist because it is not safe to create the agent’s MySQL user on a slave. The agent should be installed on the master first, then /etc/percona/agent/my.cnf copied from the master server to the slave server. Using this option forces the agent to create the agent’s MySQL user on the slave. WARNING: writing to a slave is dangerous and could cause replication to crash.
--interactive

Run in interactive mode (disables --[no]log-api).

--lib

type: string; default: /var/lib/pt-agent

Directory in which to save local data. pt-agent is remotely controlled and configured, but it also saves data locally. These files should not be edited manually.

--log

type: string; default: /var/log/pt-agent.log

Log all output to this file when daemonized.

--[no]log-api

default: yes

Log everything through the Percona Cloud Tools API.

--password

short form: -p; type: string

MySQL password.

--pid

type: string; default: /var/run/pt-agent.pid

Create the given PID file. The file contains the process ID of the script. The PID file is removed when the script exits. Before starting, the script checks if the PID file already exists. If it does not, then the script creates and writes its own PID to it. If it does, then the script checks the following: if the file contains a PID and a process is running with that PID, then the script dies; or, if there is no process running with that PID, then the script overwrites the file with its own PID and starts; else, if the file contains no PID, then the script dies.

--ping

Ping the Percona Cloud Tools API and exit.

--port

short form: -P; type: int

MySQL port number.

--reload

Force pt-agent to reload its configuration immediately.

--reset

cumulative: yes; default: 0

Reset pt-agent to a clean post-install state.

WARNING: all --spool data will be deleted.

--run-service

type: string

Run a service and spool its data for --send-data. You do not need to run :program:`pt-agent` with this option. The main pt-agent daemon schedules instances of itself with this option.

--send-data

type: string

Send data for a service to Percona. You do not need to run :program:`pt-agent` with this option. The main pt-agent daemon schedules instances of itself with this option.

--set-vars

type: Array

Set the MySQL variables in this comma-separated list of variable=value pairs.

By default, the agent sets:

wait_timeout=10000

Variables specified on the command line override these defaults. For example, specifying --set-vars wait_timeout=500 overrides the default value of 10000.

The agent prints a warning and continues if a variable cannot be set.

--socket

short form: -S; type: string

MySQL socket file.

--spool

type: string; default: /var/spool/pt-agent

Directory in which to save service data before sending to Percona. --run-service saves data in this directory, and --send-data reads data from this directory. Each service has its own subdirectory, like --spool/query-history for the Query History service. Data is removed by --send-data after it is successfully sent to Percona.

--status

Print the status of pt-agent.

--stop

Stop pt-agent and all services.

--uninstall

Completely remove pt-agent and all its data from the server. This does not delete the agent from https://cloud.percona.com.

--user

short form: -u; type: string

MySQL user, if not the current system user.

--version

Print the agent’s version and exit.

DSN OPTIONS

These DSN options are used to create a DSN. Each option is given like option=value. The options are case-sensitive, so P and p are not the same option. There cannot be whitespace before or after the = and if the value contains whitespace it must be quoted. DSN options are comma-separated. See the percona-toolkit manpage for full details.

  • A

dsn: charset; copy: yes

Default character set.

  • D

copy: no

Default database when connecting.

  • F

dsn: mysql_read_default_file; copy: yes

Defaults file for connection values.

  • h

dsn: host; copy: yes

MySQL host.

  • p

dsn: password; copy: yes

MySQL password.

  • P

dsn: port; copy: yes

MySQL port number.

  • S

dsn: mysql_socket; copy: no

MySQL socket file.

  • u

dsn: user; copy: yes

MySQL user, if not the current system user.

ENVIRONMENT

The environment variable PTDEBUG enables verbose debugging output to STDERR. To enable debugging and capture all output to a file, run the tool like:

PTDEBUG=1 pt-agent ... > FILE 2>&1

Be careful: debugging output is voluminous and can generate several megabytes of output.

SYSTEM REQUIREMENTS

pt-agent requires:

  • A Percona Cloud Tools account (https://cloud.percona.com)
  • Access to https://cloud-api.percona.com
  • Perl 5.8 or newer
  • Standard Linux bin tools (grep, awk, stat, etc.)
  • cron
  • A Bash shell
  • Core Perl modules
  • DBD::mysql Perl module
  • JSON Perl module
  • LWP (>= v5.813) Perl module
  • IO::Socket::SSL Perl module

BUGS

For a list of known bugs, see http://www.percona.com/bugs/pt-agent.

Please report bugs at https://bugs.launchpad.net/percona-toolkit. Include the following information in your bug report:

  • Complete command-line used to run the tool
  • Tool --version
  • MySQL version of all servers involved
  • Output from the tool including STDERR
  • Input files (log/dump/config files, etc.)

If possible, include debugging output by running the tool with PTDEBUG; see “ENVIRONMENT”.

DOWNLOADING

Visit http://www.percona.com/software/percona-toolkit/ to download the latest release of Percona Toolkit.

AUTHORS

Daniel Nichter

ABOUT PERCONA TOOLKIT

This tool is part of Percona Toolkit, a collection of advanced command-line tools developed by Percona for MySQL support and consulting. Percona Toolkit was forked from two projects in June, 2011: Maatkit and Aspersa. Those projects were created by Baron Schwartz and developed primarily by him and Daniel Nichter, both of whom are employed by Percona. Visit http://www.percona.com/software/ for more software developed by Percona.

VERSION

pt-agent 2.2.6

Percona Toolkit
Call Us
+1-888-316-9775 (USA - Sales)
+1-208-473-2904 (USA - Sales)
+44-208-133-0309 (UK - Sales)
0-800-051-8984 (UK - Sales)
0-800-181-0665 (GER - Sales)
+1-877-862-4316 (Emergency)
+1-855-55TRAIN (Training)
+1-925-271-5054 (Training)

Table Of Contents

Previous topic

Installation

Next topic

pt-align

This Page



© Copyright 2013, Percona LLC and/or its affiliates.
Except where otherwise noted, this documentation is licensed under the following license:
CC Attribution-ShareAlike 2.0 Generic
Created using Sphinx 1.1.3.
This documentation is developed in Launchpad as part of the Percona Toolkit source code.
If you spotted innacuracies, errors, don't understood it or you think something is missing or should be improved, please file a bug.
]]>