Percona Agent¶

Percona Agent is a background service that collects performance data and sends it over a secure websocket connection to PCT.

Percona Agent code is open source, and available on GitHub.

To install Percona Agent:

Get the API key at https://cloud.percona.com/api-key.

Run the following command as root:

$ curl -s https://cloud.percona.com/install | bash /dev/stdin -api-key="<API key>"

The installer attempts to automatically detect necessary MySQL options, as described in System Requirements. If it fails, the installed Percona Agent will not be able to collect any MySQL metrics and query data, only general system metrics. For more control over the installation process, see Package Install.

Release Notes¶

System Requirements¶

Percona Agent requires the following:

Any 32-bit or 64-bit Linux distribution with root access
Outbound connection to *.percona.com (on ports 80 and 443)

For MySQL metrics monitoring and query analytics:

MySQL 5.1 or later (if using MySQL slow query log)
MySQL 5.6 or later (if using MySQL Performance Schema)

Note

For more information about the advantages and disadvantages of Performance Schema over slow query log, see Performance Schema.

The Percona Agent installer uses mysql --print-defaults to detect local MySQL instance and MySQL superuser credentials. Make sure that the necessary options are specified in ~/.my.cnf (for root). For example:

user=root
password=pass
socket=/var/run/mysqld/mysqld.sock

MySQL superuser credentials are used to create a MySQL user for Percona Agent with the following privileges:

SUPER, PROCESS, USAGE, SELECT ON *.* TO 'percona-agent'@'localhost'
UPDATE, DELETE, DROP ON performance_schema.* TO 'percona-agent'@'localhost'

Note

Instead of localhost, a specific IP (such as 127.0.0.1) or the % wildcard can be used.

Package Install¶

The Percona Agent distribution package contains an interactive install script that prompts the user for input when it is not able to detect necessary options. For example, the script prompts for the API key, unless you specify it using the -api-key option.

Download the archive with the latest Percona Agent distribution package.
Extract the archive and change to the directory it creates.
Run the ./install script as root.

There are many options that you can pass to the install script for specific cases:

Automated Install
Slave Install
Non-MySQL Install

For a complete list of options, run the install script with the -help option or see the Install Script Options reference section.

Automated Install¶

To automate installation and disable install script prompts, use the -interactive=false option. In this case, installation will be the same as during a Quick Install.

Note

If you run the install script in non-interactive mode, you have to specify the -api-key option.

If the installer fails to detect necessary MySQL options, Percona Agent will not be able to collect MySQL metrics and query data, only general system metrics. To avoid this, you can pass necessary MySQL options to the install script, for example:

$ ./install -interactive=false -api-key=1a2b3c -mysql-user=root -mysql-pass=pass -mysql-socket=/var/run/mysqld/mysqld.sock

Slave Install¶

After you install Percona Agent on the master, run the install script with the -create-mysql-user=false option on the slave. In this case, the install script will prompt you for existing Percona Agent user credentials on MySQL.

To install Percona Agent on the slave in automated mode, specify the agent’s MySQL user credentials as options for the install script, for example:

$ ./install -interactive=false -create-mysql-user=false -agent-mysql-user=name -agent-mysql-pass=pass

Note

Specifying -agent-mysql-user automatically disables -create-mysql-user.

Non-MySQL Install¶

If you want to install Percona Agent on a server without MySQL or you do not want to monitor a particular MySQL instance, pass the -mysql=false option to the install script:

$ ./install -mysql=false

In this case, Percona Agent will monitor only general system metrics.

Using Percona Software Repositories¶

Percona provides repositories for popular package managers:

yum (RPM packages for RedHat, CentOS, Amazon Linux AMI, etc.)
apt (.deb packages for Debian, Ubuntu, etc.)

You can use those package managers to install and update all Percona software with any dependencies.

Installing on RPM-based systems¶

To install Percona Agent using the yum manager:

Install an RPM that configures yum and installs the Percona GPG key:

$ yum install http://www.percona.com/downloads/percona-release/redhat/0.1-3/percona-release-0.1-3.noarch.rpm

Make sure that Percona packages are available from the repository:
```
$ yum list | grep percona
```
Install the Percona Agent package:
```
$ yum install percona-agent
```

Installing on Debian-based systems¶

To install using the apt manager:

Add Percona package key to apt:

$ apt-key adv --keyserver keys.gnupg.net --recv-keys 1C4CBDCDCD2EFD2A

Add Percona repository sources to /etc/apt/sources.list with the correct name of the distribution. For example, if you are running Ubuntu 14.04 (Trusty Tahr), add the following lines:
```
deb http://repo.percona.com/apt trusty main
deb-src http://repo.percona.com/apt trusty main
```
Update local cache:
```
$ apt-get update
```
Install the Percona Agent package:
```
$ apt-get install percona-agent
```

Managing Percona Agent¶

After installation, Percona Agent is started and run in the background as a service. You can control the percona-agent service as follows:

$ sudo /etc/init.d/percona-agent {start|stop|restart|status}

Alternatively, use the following:

$ sudo service percona-agent {start|stop|restart|status}

Updating Percona Agent¶

When a new version of Percona Agent is available, use either Quick Install or Package Install to update. The install script checks for the currently installed version and applies necessary updates.

If you installed Percona Agent using a package manager, as described in Using Percona Software Repositories, then you can update it as follows:

For yum, run the following command:
```
$ yum update percona-agent
```
Note

You can run the previous command without specifying the percona-agent package to make yum update all installed packages.
For apt, run the following command:
```
$ apt-get install --only-upgrade percona-agent
```
Note

You can also run the following command, which installs the newest versions of all packages installed on the system:
```
$ apt-get upgrade
```

Uninstalling Percona Agent¶

If you did a Quick Install, run the following command to uninstall Percona Agent:

$ curl -s https://cloud.percona.com/install | bash /dev/stdin -uninstall

If you did a Package Install, change to the directory where the Percona Agent archive was extracted and run the following command:

$ ./install -uninstall

To drop the Percona Agent user from any MySQL instance that the agent was monitoring, execute the following on the MySQL server:

> DROP USER 'percona-agent'@'localhost';
> DROP USER 'percona-agent'@'127.0.0.1';

To remove the agent’s configuration and data from Percona Cloud Tools, log in and delete the agent at https://cloud.percona.com/agents.

You can also delete any MySQL instances that the agent was monitoring at https://cloud.percona.com/instances/mysql.

Install Script Options¶

You can pass command-line options to the Percona Agent install script in special cases. For example, the installer may not be able to detect necessary MySQL options, or you may want the installer to perform non-standard procedures.

The general syntax for most options is the name of the option, followed by the equals sign and the argument value:

OPTION=ARG

Arguments can be one of the following types:

Boolean:	Specify either `true` or `false` to enable or disable something.
String:	Specify a string of characters, such as a name or an address. If the string contains spaces, enclose it in quotation marks.
Integer:	Specify an integer number.

Some options do not have arguments, you simply specify the option to enable something.

To get a list of install script options with short descriptions, run the install script with the -help option.

-agent-mysql-pass

Specify existing MySQL user password for Percona Agent.