Chapter 5 Monitor Agent Installation
Prev |  | Next

## Chapter 5 Monitor Agent Installation

A MySQL Enterprise Monitor Agent monitors a MySQL server and sends data to the MySQL Enterprise Service Manager. The data is interpreted by the MySQL Enterprise Advisors and displayed in the MySQL Enterprise Monitor User Interface. The following section describes how to install the Agent on all platforms.

Important

Due to changes in TLS support, as of MySQL Enterprise Monitor 3.0.22, it is not possible for the MySQL Enterprise Service Manager to communicate with earlier versions of the MySQL Enterprise Monitor Agent.

It is strongly recommended that MySQL Enterprise Monitor Agent 3.1 are installed for use with the MySQL Enterprise Service Manager 3.1.

## 5.1 General Agent Related Notes

This section describes important features of the Agent.

- The Agent uses three users with different connection levels: Admin, General (optional), and Limited (optional). These can be created manually or by the installation and configuration process.

- Typically, one Agent is installed per host, and the Agent monitors the host and all MySQL instances on it. An Agent may also monitor remote MySQL instances.

- Agents automatically detect MySQL instances on a host. Adding the new MySQL instance may be performed in the MySQL Enterprise Monitor UI or from the command line.

- Choosing a MySQL Instance to monitor during the installation is optional. If you choose to define a MySQL Instance while running the Installer, additional MySQL Instances on the host are detected and reported in the MySQL Enterprise Monitor User Interface. From there, you can add the appropriate configuration information.

- In order to properly detect a local connection in IPv6, the Agent requires that forward resolution exists on the system from localhost to `::1`, which could mean editing the `/etc/hosts` configuration file.

  This is because the "SHOW PROCESSLIST" statement always reports "localhost" even when bound to ::1 without an address resolution. If localhost resolution is not configured for IPv6, the Agent cannot detect a local IPv6 MySQL server connection, even when it occurs.

- Proxy and Aggregator

  Note

  The Proxy and Aggregator are not included in the MySQL Enterprise Monitor Agent 3.1.0 installer. As of version 3.0.14, the Proxy and Aggregator have a dedicated installation package. For more information, see Chapter 11, Proxy and Aggregator Installation

- You can assign a monitored MySQL instance to a group via the Agent installer, which is displayed in the MySQL Enterprise Service Manager.

- The old Agent's configuration files (`mysql-monitor-agent.ini` and `agent-instance.ini`) no longer exist. Use `custom.xml` instead.

- Passwords are now stored in an encrypted format, so you can no longer recover passwords by looking in the configuration files.

- The Service Manager now bundles an Agent, which monitors the host on which it is installed, scans for all MySQL instances on the host, and also monitors the Service Manager repository database.

  Note

  It is recommended to install MySQL Enterprise Service Manager on a dedicated server with no other MySQL instances installed.

- For a list of supported platforms that the Agent installation supports, see http://www.mysql.com/support/supportedplatforms/enterprise-monitor.html.

## 5.2 Creating MySQL User Accounts for the Monitor Agent

The MySQL Enterprise Monitor Agent requires a user configured within each MySQL instance that is being monitored with suitable privileges to collect information about the server, including variable names, replication, and storage engine status information.

The Agent requires the `Admin` user, and can optionally use `General` or `Limited` users, or both, depending on the system's security requirements. During the installation process, you are prompted to create General and Limited users. You can allow the agent to connect to the database using the Admin user for all tasks but it is recommended to create the General or Limited users for tasks which do not require root access to the database. It is not necessary to create both users. It is possible to create one or the other. The Agent uses the user with the lowest, required privileges for the query and changes to a user with higher privileges only if the query requires it.

- `Admin`: a user that has the `SUPER`, `CREATE`, and `INSERT` privileges on the schema the inventory table will be created on (the inventory table stores unique identifiers for the MySQL instance, and is created in the `mysql` schema by default). The `SUPER` privilege is required to temporarily switch off replication when creating and populating the inventory table, as well as running certain statements such as `SHOW MASTER LOGS` or `SHOW ENGINE INNODB STATUS`, depending on the version that is being monitored.

  If you intend to automatically create the less-privileged users, General and Limited, you must also grant the Admin user `CREATE USER`, `SHOW VIEW`, `PROCESS`, `REPLICATION CLIENT`, `SELECT` and `SHOW DATABASES` privileges globally, and `UPDATE` on the `performance_schema.threads` table, WITH `GRANT OPTION` for all..

  If you intend to install the sys schema from within MySQL Enterprise Monitor, in addition to the privileges listed above, you must also grant the Admin user `CREATE ROUTINE`, `CREATE TEMPORARY TABLES`, `CREATE VIEW`, and `TRIGGER`.

- `General`: This optional user handles general monitoring tasks that do not require `SUPER` level privileges. Lower privileged users are used until higher privileges are required. In which case, MEM temporarily logs in as the SUPER privileged user, and then falls back to the general user.

  If you are manually managing this user, it should have at least the `PROCESS`, `REPLICATION CLIENT`, `SELECT`, and `SHOW DATABASES` privileges globally, and `UPDATE` on the `performance_schema.threads` table. If you intend to use EXPLAIN on views, you must also grant `SHOW VIEWS`.

  Important

  If you are monitoring MySQL 5.1.63, or earlier, you must grant the `SUPER` privilege to the General user. The agent requires this privilege to use the `SHOW BINARY LOGS` statement on the monitored instance.

- `Limited`: This optional user is used for statements that should be limited to a single connection.

  Examples of these types of statements include getting database metadata from `INFORMATION_SCHEMA` tables (which with large numbers of databases and tables can become costly), or any custom SQL that is used to monitor application specific statistics.

  If you are manually managing this user, it should have at least the `SELECT` and `SHOW DATABASES` privileges globally, and `UPDATE` on the `performance_schema.threads` table. If you intend to use EXPLAIN on views, you must also grant `SHOW VIEWS`.

### Creating the Admin User

If you do not want to supply the root user information to the installer, create a user manually within your MySQL server and provide these credentials as the agent user/password combination during installation. The privileges required for this user account vary depending on the information you gather using the MySQL Enterprise Monitor Agent. The following privileges allow the Monitor Agent to perform its assigned duties without limitation:

- `SHOW DATABASES`: The MySQL Enterprise Monitor Agent can gather inventory about the monitored MySQL server.

- `REPLICATION CLIENT`: The MySQL Enterprise Monitor Agent can gather Replication master/slave status data. This privilege is only needed if you use the MySQL Replication Advisor Rules.

- `SELECT`: The MySQL Enterprise Monitor Agent can collect statistics for table objects.

- `SUPER`: The MySQL Enterprise Monitor Agent can execute `SHOW ENGINE INNODB STATUS` to collect data about InnoDB tables. This privilege is also required to obtain replication information using `SHOW MASTER STATUS`, and to temporarily switch off replication when populating the `mysql.inventory` table used to identify the MySQL instance.

- `PROCESS`: When monitoring a MySQL server running MySQL 5.1.24 or above with `InnoDB`, the `PROCESS` privilege is required to execute `SHOW ENGINE INNODB STATUS`.

- `INSERT`: Required to create the UUID required by the agent.

- `CREATE`: The MySQL Enterprise Monitor Agent can create tables. During discovery, the agent creates the table `inventory` within the `mysql` database that stores the UUID for the server. Without this table, the agent cannot determine the UUID of the server, which it sends along with other information to MySQL Enterprise Service Manager.

- `UPDATE` on the `performance_schema.threads` table. This is done to prevent SQL Statement Generates Warnings or Errors events which can be triggered by EXPLAIN plans run by the Query Analyzer. These warnings are generated because the `Performance_Schema` captures only 1024 characters of each query. Granting this privilege enables the connection to `Performance_Schema` to be dropped before the `EXPLAIN` and reconnected after the `EXPLAIN` finishes.

  Note

  If you manage your General and Limited users manually, you must also grant this privilege to those users.

For example, the following `GRANT` statement gives the agent the required `SELECT`, `REPLICATION CLIENT`, `SHOW DATABASES` and `SUPER` rights:

    GRANT SELECT, CREATE USER, REPLICATION CLIENT, SHOW DATABASES, SUPER, PROCESS
      ON *.*
      TO  'mysqluser'@'localhost'
      IDENTIFIED BY 'agent_password';

Note

When using Auto-Create Less Privileged Users, also add `WITH GRANT OPTION` to the above query.

For security reasons, you might limit the `CREATE` and `INSERT` privileges to the agent so that it can only create tables within the `mysql` database:

    GRANT CREATE, INSERT
      ON mysql.*
      TO  'mysqluser'@'localhost'
      IDENTIFIED BY 'agent_password';

To let replication discovery work, grant the `SELECT` privilege on the `mysql.inventory` table for each user with replication privileges on the corresponding replication master. This is required to let the MySQL Enterprise Monitor Agent read the replication master UUID. For example:

    GRANT SELECT
      ON mysql.inventory
      TO  'replicationuser'@'%'
      IDENTIFIED BY 'replication_password';

Note

Perform this step after after running the agent on the corresponding MySQL server to ensure that the `mysql.inventory` table is created correctly. Run the agent, shut the agent down, run the above `GRANT` statement, and then restart the agent.

If the agent cannot access the information from the table, a warning containing this information is written to the agent log.

Note

You might disable logging for the grant statement to prevent the grant information being replicated to the slaves. In this case, execute the statement `SET SQL_LOG_BIN=0` before executing the above `GRANT` statement.

### Creating the Limited and General Users

If the Admin user has the necessary privileges to create other users, you can check the Auto-Create Less Privileged Users checkbox, enter credentials for those users, and they are created for you.

If the Auto-Create Less Privileged Users box is unchecked and the credentials for the General and Limited users blank, the Agent only uses the Admin user for monitoring.

If the Auto-Create Less Privileged Users box is unchecked, you can enter credentials for the General and Limited users. If you define these users. you must create them on the monitored assets manually. The installer attempts to validate these users and displays a warning message if they are invalid. The installation process continues, and the Agent works properly, but you must create those users later.

In a typical configuration, the Agent runs on the same host as the MySQL server it is monitoring, so the host name is often `localhost`. If the Agent is running on a machine other than the monitored MySQL server(s), then change `localhost` to the appropriate value. For more information about remote monitoring, see Section 5.7, “Configuring an Agent to Monitor a Remote MySQL Server”.

## 5.3 Java Considerations on Linux

The MySQL Enterprise Monitor Agent installers and updaters for UNIX-based platforms are delivered with and without a compatible JVM. For those installers which do not include a compatible JVM, you must download and install a compatible version if you do not already have one installed. Consult your platform's support documentation for information on appropriate installations.

Important

On 64-bit platforms, it is recommended to use a 32-bit JRE with the 32-bit MySQL Enterprise Monitor Agent. The 32-bit version uses considerably less RAM than the 64-bit version. For more information, see Compatibility Libraries.

### Compatibility Libraries

If you intend to use a 32-bit JVM on a 64-bit platform, ensure that you have the correct compatibility libraries installed, enabling the 64-bit application to run with a 32-bit JVM.

These libraries differ between Linux versions. For example, on Debian or Ubuntu, you must ensure Multiarch is installed or, if using earlier versions, `ia32-libs`. On RedHat, or CentOS, you must ensure that the `glibc.i686`, `libXext.i686` and `libXtst.i686` libraries are installed. Consult your platform documentation for more information on compatibility.

## 5.4 Monitoring Agent Graphical Installation Wizard

This section describes how to install the Agent using the Installation Wizard. The steps are identical in the command line installation method.

Note

To install to the default directory (`/opt/mysql/enterprise/agent`), log in as `root` first. Installing as an unprivileged user installs to the `/home/`user_name`/mysql/enterprise/agent` directory.

To automatically start the agent upon rebooting, you must install while logged in as root. If you install as an unprivileged user, you must start the agent yourself after each reboot.

Note

If MySQL Enterprise Monitor Agent is installed as the root user, directories and files that the Agent writes to are owned by the `mysql` user in the `mysql` group, which includes `logs/`, `spool/`, and `etc/agentManaged`. The Agent is started by, and runs as, the `mysql` user.

You can also install the Monitor Agent in `unattended` mode. For more information on unattended installation, see Section 8.1, “Unattended Installation”.

Note

To install multiple agents on the same machine, use the `agentservicename` option with the installer to set a unique service name each time. For more information, see `installer_agentservicename`.

Note

On FreeBSD, the Agent Installer does not bundle the required JRE 8.

Note

There is no 64-bit agent installation for Microsoft Windows platform.

To install the Agent, do the following:

1. Run the installer as required by your operating system.

2. The Language Selection dialog is displayed. Select your language, and click OK.

   The Installation directory dialog is displayed.

3. Either change the installation directory, or accept the default value, and choose the connection type for the agent.

   - Installation directory: enables you to change the installation path.

   - TCP/IP: select if the agent uses TCP/IP to connect to the monitored database. This option is not available on Microsoft Windows platforms. TCP/IP is used by default.

   - Socket: select if the agent uses socket to connect to the monitored database. This is only possible if the agent is monitoring a local database. This option is not available on Microsoft Windows platforms.

     If you choose Socket, you must enter the path to the socket later in the installation process.

   Click Forward. The Monitoring Options dialog is displayed. The installation starts and the files are copied to the installation directory.

4. You can choose whether to monitor the host on which the agent is installed, or the host and a MySQL instance. If you select host only, you have to configure the connection to the MySQL Enterprise Service Manager, but no other configuration is required. If you select host and database, you must also configure the database connection parameters.

   Click Forward. If you are installing on Apple OS X, the Install as a service dialog is displayed. This dialog enables you to install the agent as a service, which restarts each time the host is restarted. This option requires an Administrator's password.

   On all other platforms, the MySQL Enterprise Monitor Options dialog is displayed.

5. The MySQL Enterprise Monitor Options dialog is displayed. Complete the following:

   - Hostname or IP address: the hostname or IP address of the server where the MySQL Enterprise Service Manager is installed.

   - Tomcat SSL Port: the SSL port the MySQL Enterprise Service Manager is listening on.

   - Agent Username: the agent username. This is the username all agents must use to connect to the MySQL Enterprise Service Manager.

   - Agent Password: the agent's password. This is the password all agents must use to connect to the MySQL Enterprise Service Manager.

   - Re-enter: re-enter the agent's password.

   Click Forward. The Monitored Database Configuration Options dialog is displayed.

6. The Monitored Database Configuration Options enables you to choose the remaining steps of the installation. The following options are available:

   - Validate hostname, port, and Admin account privileges: select this option to attempt a test connection to the database with the supplied credentials, defined in the Monitored Database Information dialog. If you do not select this option, the installer does not attempt a test connection to the database with the supplied credentials.

     Note

     It is recommended to validate the connection.

   - Configure encryption settings for user accounts: select this to configure the Encryption Settings dialog. If selected, this dialog is displayed after the Monitored Database Information dialog. The Encryption Settings dialog enables you to define the SSL options for connections to SSL-enabled MySQL Instances.

     Important

     Ensure the MySQL instance is SSL-enabled.

   - Configure less-privileged user accounts: select if you intend to define the less-privileged user accounts, `General` and `Limited.`

   Make your selection and click Forward.

   The Monitored Database Information dialog is displayed.

7. The Monitored Database Information dialog enables you to define the connection parameters for the MySQL instance the agent will monitor.

   - MySQL hostname or IP address: the IP address or hostname of the server on which the MySQL instance is running.

   - MySQL Port: the port the MySQL instance is listening on.

   - Admin User: the admin user the agent uses. This can be the `root` user, or another user with the `SUPER` privilege.

   - Admin Password: the password of the admin user.

   - Re-enter Password: re-enter the admin user's password.

   - Monitor Group: the group to which you want the instance to be added in MySQL Enterprise Service Manager. If the group does not exist, it is created, and the monitored instance added to it.

   Click Forward. If you selected Validate hostname, port, and Admin account privileges on the Monitored Database Configuration Options dialog, the supplied credentials are verified against the MySQL instance.

   If you selected Configure encryption settings for user accounts on the Monitored Database Configuration Options dialog, the Encryption Settings dialog is displayed.

8. The Encryption Settings dialog enables you to define the SSL connection parameters for your connection to the SSL-enabled MySQL Instance.

   - Require Encryption: enforces encrypted connections between the agent and the MySQL instance.

   - Allow Self-Signed Certificates: specifies whether self-signed certificates are permitted.

   - CA Certificate: the path to the CA certificate.

9. If you selected Configure less-privileged user accounts on the Monitored Database Configuration Options, the Less Privileged User Account Creation dialog is displayed.

   - Auto-create Less Privileged Users: select to automatically create the users, using the credentials supplied. If you do not create these users, all agent queries are run as the Admin user.

   - General Username: username of the General user.

   - General Password: password of the General user.

   - Limited Username: username of the Limited user.

   - Limited Password: password of the Limited user.

   Click Forward to create the Agent account and complete the installation.

## 5.5 Starting/Stopping the MySQL Enterprise Monitor Agent

The MySQL Enterprise Monitor Agent can be started and stopped at any time. When not running, information about the current status of your server is not available, and MySQL Enterprise Service Manager provides a warning if an agent and the MySQL server that it monitors is unavailable.

### 5.5.1 Starting/Stopping the Agent on Windows

You have the option of starting the Monitor Agent from the final installation screen. Otherwise you can do this by going to the `Start Menu` and under `Programs` find `MySQL` and then the `MySQL Enterprise Monitor Agent` entry. Simply select the `Start MySQL Enterprise Monitor Agent` option.

Note

On Windows Vista or later, starting the agent requires administrative privileges—you must be logged in as an administrator. To start or stop the agent right-click the menu item and choose the Run as Administrator menu option. The same restriction applies to starting the agent from the command line. To open an administrator `cmd` window right-click the `cmd` icon and choose the Run as Administrator menu option.

Warning

To report its findings, the agent needs to be able to connect to the Monitor UI through the port specified during installation. The default value for this port is `18443`; ensure that this port is not blocked. If you need help troubleshooting the agent installation see, Section 5.10, “Troubleshooting the Agent”.

Alternately, you can start the agent from the command line by entering:

    shell> sc start MySQLEnterpriseMonitorAgent

or:

    shell> net start MySQLEnterpriseMonitorAgent

You can also start the agent by issuing the command, agentctl.bat start. Stop the agent by passing the argument, `stop`. This batch file is found in the `Agent` directory.

For confirmation that the service is running you can open the Microsoft Management Console Services window. To do this go to the Control Panel, find `Administrative Tools` and click the link to `Services`. Locate the service named `MySQL Enterprise Monitor Agent` and look under the Status column.

You can also start the agent from this window rather than from the `Start` menu or the command line. Simply right-click `MySQL Enterprise Monitor Agent` and choose `Start` from the pop-up menu. Starting the agent from this window opens an error dialog box if the agent cannot connect to the MySQL server it is monitoring. No error is displayed if the agent is unable to connect to the MySQL Enterprise Service Manager.

The pop-up menu for starting the agent also offers the option of stopping the agent. To stop the agent from the command line you only need type:

    shell> sc stop MySQLEnterpriseMonitorAgent

or:

    shell> net stop MySQLEnterpriseMonitorAgent

Note

`MySQLEnterpriseMonitorAgent` is the default name of the Monitor Agent service.

### 5.5.2 Starting/Stopping the Agent on Mac OS X

#### Using launchd

The preferred method is to use `launchd` to load the Agent as a service. After selecting "Install as a service" during the installation process, you may load or unload the Agent service using the following commands.

To start (load) the Agent:

    shell> sudo launchctl load /Library/LaunchDaemons/mysql.agent.plist

To stop (unload) the Agent:

    shell> sudo launchctl unload /Library/LaunchDaemons/mysql.agent.plist

#### Using init

Alternatively, an init.d script to start the Agent on Mac OS X is located in the `/Applications/mysql/enterprise/agent/etc/init.d` directory. To start the Agent navigate to this directory and at the command line type:

    shell> ./mysql-monitor-agent start

To stop the Agent, use the `stop` command:

    shell> ./mysql-monitor-agent stop

If the agent cannot be stopped because the `pid` file that contains the agent's process ID cannot be found, you can use kill to send a `TERM` signal to the running process:

    shell> kill -TERM PID

If you run more than one agent on a specific machine, you must also specify the path to the `ini` file when you stop the agent. Executing `mysql-monitor-agent stop` without an `ini` file only stops the agent associated with the default `ini` file.

To verify that the agent is running, use the following command:

    shell> ./mysql-monitor-agent status

The resulting message indicates whether the agent is running. If the agent is not running, use the following command to view the last ten entries in the general Agent log file:

    shell> tail /Applications/mysql/enterprise/agent/logs/mysql-monitor-agent.log

For further information on troubleshooting the agent, see Section 5.10, “Troubleshooting the Agent”.

Installation creates the directory `/Applications/mysql/enterprise/agent`, and the `logs` directory is located immediately below the `agent` directory.

To see all the command-line options available when running the monitor agent, navigate to the `/Applications/mysql/enterprise/agent/etc/init.d` directory and execute `mysql-monitor-agent` `help`, which displays the usage message:

    Usage: ./mysql-monitor-agent {start|stop|restart|status}

Warning

To report its findings, the agent connects to the Monitor UI through the port specified during installation. The default value for this port is `18443`; ensure that this port is not blocked. To troubleshoot the agent installation, see Section 5.10, “Troubleshooting the Agent”.

### 5.5.3 Starting/Stopping the Agent on Unix

When installation is finished, you can start the monitor agent from the command line by typing:

    shell> /opt/mysql/enterprise/agent/etc/init.d/mysql-monitor-agent start

For a non-`root` installation the command would be:

    shell> /home/<user name>/mysql/enterprise/agent/etc/init.d/mysql-monitor-agent start

To stop the agent, use the `stop` command:

    shell> ./mysql-monitor-agent stop

If the agent cannot be stopped because the `pid` file that contains the agent's process ID cannot be found, you can use kill to send a `TERM` signal to the running process:

    shell> kill -TERM PID

To verify that the agent is running, use the following command:

    shell> ./mysql-monitor-agent status

The resulting message indicates whether the agent is running. If the agent is not running, use the following command to view the last ten entries in the general Agent log file:

    shell> tail /opt/mysql/enterprise/agent/logs/mysql-monitor-agent.log

For further information on troubleshooting the agent, see Section 5.10, “Troubleshooting the Agent”.

Installation creates the directory `/opt/mysql/enterprise/agent`, with the `logs` directory is located immediately below the `agent` directory.

To see all the command-line options available when running the monitor agent, navigate to the `/opt/mysql/enterprise/agent/etc/init.d` directory and execute `mysql-monitor-agent` `help`, which displays the usage message:

    Usage: ./mysql-monitor-agent {start|stop|restart|status}

Warning

To report its findings, the agent connects to the Monitor UI through the port specified during installation. The default value for this port is `18443`; ensure that this port is not blocked. To troubleshoot the agent installation, see Section 5.10, “Troubleshooting the Agent”.

### 5.5.4 sql_mode

On startup, the agent sets sql_mode=STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION,NO_AUTO_CREATE_USER on the monitored MySQL instance. If sql_mode=ONLY_FULL_GROUP_BY, agent queries can fail. The local agent of the MySQL Enterprise Service Manager also sets sql_mode=STRICT_TRANS_TABLES,NO_ENGINE_SUBSTITUTION on the repository.

## 5.6 Monitoring Multiple MySQL Servers

You can monitor multiple MySQL servers (either on the same machine, or remotely across different machines) using a single Agent.

Make sure that the MySQL instance that you want to monitor has a suitable user to use for connecting to the host. For more information, see Section 5.2, “Creating MySQL User Accounts for the Monitor Agent”.

Typically, an Agent will scan a host and report unmonitored MySQL instances to the MySQL Enterprise Monitor User Interface. For more information about how this works, see Section 1.2, “MySQL Enterprise Monitor Agent”. For information about how to change the status of a MySQL instance from unmonitored to monitored, see Chapter 15, MySQL Instances Dashboard.

## 5.7 Configuring an Agent to Monitor a Remote MySQL Server

Typically, the Agent runs on the same machine as the MySQL servers that it is monitoring. To monitor MySQL servers running on remote hosts, you can install the Agent on a machine other than the one hosting the MySQL server.

The process for installing an Agent to monitor a MySQL server on a remote machine is identical to the process described in Chapter 5, Monitor Agent Installation. Follow the directions given there, being careful to either select "host-only" and add remote MySQL instances later, or specify the correct IP address or host name for the MySQL Enterprise Service Manager and likewise for the MySQL server— since the Agent is not running on the same machine as the MySQL server, it cannot be the default (`localhost`).

Ensure that the Agent has the appropriate rights to log in to the MySQL server from a host other than `localhost` and that the port used by the MySQL server, typically `3306` must be open for remote access. For more information about the database credentials required by agents see, Section 5.2, “Creating MySQL User Accounts for the Monitor Agent”.

The Agent also needs to be able to log in to the MySQL Enterprise Service Manager, typically using port `18443`, so ensure that the appropriate port is open.

### Remote Monitoring Limitations

- Remote monitoring does not provide operating system level data, such as CPU, file, and network utilization information.

- Monitoring multiple MySQL instances with a single agent potentially means having a single point of failure. This is especially true for remote monitoring, as it might lose a connection, which means a black period, whereas a local Agent will continue monitoring and provides information upon reconnection.

- For replication autodiscovery, do not use remote monitoring with replication slaves or masters. The Agent must be installed on the same machine as the server you are monitoring in order for discovery to work properly. For more information, see Chapter 17, Replication Dashboard.

### Monitoring Amazon RDS

This section describes how to monitor a MySQL instance in an cloud environment, such as the Amazon Relational Database Service (Amazon RDS).

Important

It is recommended that you use MySQL 5.6 on RDS. It is also possible to use MySQL 5.5, but you must disable backup and replicas before attempting to monitor it using MySQL Enterprise Service Manager. After the agent has connected, you can enable backup and replicas again.

Remote monitoring is used when monitoring on a cloud. You can use any MySQL Enterprise Monitor Agent to monitor MySQL instances remotely, including the bundled Agent that is automatically installed and started with the MySQL Enterprise Service Manager.

When configuring a MySQL instance to monitor from the MySQL Instances Dashboard, do the following:

- Do not configure MySQL Enterprise Monitor to auto-create the less privileged `Limited` and `General` accounts, and instead use the Admin account for all monitoring.

  This is set in the Connection Settings tab when adding or editing a MySQL instance to be monitored. The Auto-Create Less Privileged Users setting defaults to `Yes`, ensure it is set to `No`.

- Also under Connection Settings is the Instance Address parameter. Set this to your endpoint, which is the entry point for your MySQL Server web service.

- Change the inventory table schema for MySQL Enterprise Monitor Agent from "`mysql`" to an existing, alternative schema.

  This is set in the Advanced Settings tab when adding (or editing) a MySQL instance to be monitored. The Inventory Table Schema setting defaults to `mysql`, which is typically not accessible to the Agent user in a cloud (or shared) environment. Change it to a schema you created.

Your MySQL instance is displayed on the MySQL Instances Dashboard.

## 5.8 Monitoring Outside the Firewall with an SSH Tunnel

If you run an SSH server on the machine that hosts the MySQL Enterprise Service Manager and an SSH client on the machine that hosts the agent, you can create an SSH tunnel so that the agent can bypass your firewall. First, you need to make an adjustment to the `agent-mgmt-hostname` value specified in the `etc/bootstrap.properties` configuration file. Stop the agent and change the `hostname` value as shown in the following:

    agent-mgmt-hostname = https://agent_name:password@localhost:18443/

Replace the `agent_name` and `password` with suitable values. Likewise replace port `18443` if you are not running the Monitor UI on this port. Use `localhost` for the host name, since the agent is connecting through an SSH tunnel.

Next, execute the following command on the machine where the agent is running:

    shell> ssh -L 18443:Monitor_UI_Host:18443 -l user_name -N Monitor_UI_Host

When prompted, enter the password for `user_name`.

If you are not running the MySQL Enterprise Service Manager on port `18443`, substitute the appropriate port number. Likewise, replace `Monitor_UI_Host` with the correct value. `user_name` represents a valid operating system user on the machine that hosts the MySQL Enterprise Service Manager.

Be sure to restart the agent so that the new value for the `hostname` takes effect. For instructions on restarting the agent see:

- Under Windows see, Section 5.5.1, “Starting/Stopping the Agent on Windows”.

- Under Unix see, Section 5.5.3, “Starting/Stopping the Agent on Unix”.

- Under Mac OS X see, Section 5.5.2, “Starting/Stopping the Agent on Mac OS X”.

## 5.9 HTTP Connection Timeout

The HTTP connection between agent and Service Manager has a default timeout of 250 seconds for an attempted connection and 300 seconds for an established connection. It is possible to override these values in `bootstrap.properties` by adding the following parameters:

1. http-connect-timeout-ms=N: Where N is the number of milliseconds to wait before timing-out a HTTP connection attempt.

2. http-socket-timeout-ms=N: Where N is the number of milliseconds to wait before timing-out a HTTP socket read or write.

If set to zero (0), no timeout is defined. Negative values are not supported.

## 5.10 Troubleshooting the Agent

The first step in troubleshooting the agent is finding out whether it is running or not. To do this see:

- Windows: Section 5.5.1, “Starting/Stopping the Agent on Windows”

- Unix: Section 5.5.3, “Starting/Stopping the Agent on Unix”

- Mac OS X: Section 5.5.2, “Starting/Stopping the Agent on Mac OS X”

Some additional tips are:

- To run on start-up, the agent requires correct login credentials for the monitored MySQL server. Log in to the monitored MySQL server and check the agent's credentials. Compare the values of the `Host`, and `User` fields in the `mysql.user` table with the values shown in the `etc/agentManaged/mysqlConnection`<id>`/bean/json` file. The passwords are encrypted so they can not be manually managed here, but the password can be altered from the MySQL Instances page in the MySQL Enterprise Monitor User Interface, or by using the agent connection tool (`agent.sh`) from the command line.

- Using incorrect credentials for logging in to the service manager creates an entry in the agent log file.

- An easy way to confirm that the agent can log in to the service manager is to type `https://`Monitor_UI_Host:18443`/heartbeat` into the address bar of your web browser, substituting the appropriate host name and port. When the HTTP authentication dialog box opens, enter the agent user name and password. The following message indicates a successful login:

      <exceptions>
      <error>E0401: NullAgentPayloadException: []</error>
      </exceptions>

  Note

  Despite the fact that the preceding listing shows an error, you have logged in successfully. This error appears because you have logged in but with no “payload”.

  If you can log in successfully in the way described above and the agent is running, then there may be errors in Agent's configuration. Compare the host name, port, agent name, and password used in the MySQL Enterprise Monitor User Interface, and also check it using `agent.sh`, with the values you entered into the address bar of your web browser.

- If HTTP authentication fails then you are using incorrect credentials for the agent. Attempting to log in to the service manager using incorrect credentials creates an entry in the agent log file.

  If no HTTP authentication dialog box appears, and you are unable to connect at all, then the host name or port might be specified incorrectly. Confirm the values you entered against those described as the `Application hostname and port:` in the `configuration_report.txt` file. Failure to connect could also indicate that the port is blocked on the machine hosting the MySQL Enterprise Service Manager.

- To check if a blocked port is the problem, temporarily bring down your firewall. If the agent is then able to connect, open up the port specified during installation and restart the agent. If necessary you can monitor outside the firewall using an SSH tunnel. For more information, see Section 5.8, “Monitoring Outside the Firewall with an SSH Tunnel”.

- Running the agent from the command line sometimes displays errors that fail to appear in the log file or on the screen when the agent is started from a menu option. To start the agent from the command line see the instructions given at the start of this section.

- If you have more than one agent running on the same machine, the `UUID` must be unique.

- If the agent and the MySQL server it is monitoring are running on different machines, ensure that the correct `host` is specified for the agent account. The correct port, typically 3306, must also be open for remote login. For more information about remote monitoring see, Section 5.7, “Configuring an Agent to Monitor a Remote MySQL Server”.

- The MySQL Enterprise Monitor Agent and MySQL Enterprise Service Manager use the unique host ID, stored within the `mysql.inventory` table on the monitored MySQL Server, to determine whether the instance being monitored is a clone. The host ID of the current server is checked against the stored value when the agent starts. If the generated host ID and stored host ID do not match, you get an error similar to the following in the agent log file:

      %s: [%s] the hostid from mysql.inventory doesn't match our agent's host-id (%s != %s)
      We assume that this is a cloned host and shutdown now.
      Please TRUNCATE TABLE mysql.inventory on this mysql-instance and restart the agent.
      If this is a master for replication, please also run SET SQL_LOG_BIN = 0; first.

  To fix the problem, connect to the MySQL server using the credentials configured when you installed the agent, and then truncate the `mysql.inventory` table:

      mysql> TRUNCATE mysql.inventory;

  Now restart the agent, which recreates the `mysql.inventory` table with the updated instance UUID and hostid information.

## 5.11 Agent Backlog

The agent backlog is a caching mechanism which stores monitoring data in the event the agent cannot communicate with the MySQL Enterprise Service Manager. The backlog can store 10MB of monitored data in active RAM.

- Monitoring one MySQL instance: the agent backlog can store up to 40 minutes of monitored data before the backlog cache is filled and data dropped.

- Monitoring 10 MySQL instances: the agent backlog can store up to 4 minutes of monitored data before the backlog cache is filled and data dropped.

Prev | Up | Next
Chapter 4 Service Manager Installation | Home | Chapter 6 Upgrading MySQL Enterprise Monitor Installations