Skip navigation links
15.3.3.7 Troubleshooting the Agent »
Section Navigation      [Toggle]

15.3.3.6. Advanced Agent Configuration

[+/-]

15.3.3.6.1. MySQL Enterprise Monitor Agent (mysql-monitor-agent.ini) Configuration
15.3.3.6.2. MySQL Server (agent-instance.ini) Configuration
15.3.3.6.3. Monitoring Multiple MySQL Servers
15.3.3.6.4. Configuring an Agent to Monitor a Remote MySQL Server
15.3.3.6.5. Monitoring Outside the Firewall with an SSH Tunnel
15.3.3.6.6. Generating a new UUID

The MySQL Enterprise Monitor Agent is configured through files located within the etc directory within the directory where you installed the agent.

Configuration is stored in multiple files, according to a predetermined file and directory layout. The primary configuration file contains specific information about the agent and how the agent communicates with MySQL Enterprise Service Manager. The main configuration is located within the mysql-monitor-agent.ini file.

Additional configuration files contain information about the MySQL server that is being monitored. You can configure which directory is used for storing this information within the mysql-monitor-agent.ini file. The default location is the etc/instances directory within the MySQL Enterprise Monitor Agent directory.

The server you want to monitor should have a directory within the specified location, optionally using the name of the server you are monitoring, and within that directory, an agent-instance.ini file. This file contains the configuration information for connecting to the MySQL server, including the host name, port, user credentials and display name.

You can see an example of the file layout of the etc directory: 

.
./init.d
./init.d/mysql-monitor-agent
./instances
./instances/agent
./instances/agent/agent-instance.ini
./mysql-monitor-agent.ini

For more information on the configuration of the mysql-monitor-agent.ini file, see Section 15.3.3.6.1, “MySQL Enterprise Monitor Agent (mysql-monitor-agent.ini) Configuration”. For details on the content of the individual MySQL instance configuration files, see Section 15.3.3.6.2, “MySQL Server (agent-instance.ini) Configuration”.

15.3.3.6.1. MySQL Enterprise Monitor Agent (mysql-monitor-agent.ini) Configuration

The mysql-monitor-agent.ini files contains the base configuration information for the MySQL Enterprise Monitor Agent. The file sets the core information about the supported functionality for the entire agent.

You can see a sample of the configuration file below: 

# WARNING - the UUID defined below must be unique for each agent.
#
# To use this .ini file as a template for configuring additional
# agents, do not simply copy and start a new agent without first
# modifying the UUID.
#
# Refer to the documentation for more detailed information and
# instructions.
#
# Version: 20080718_230416_r7011

[mysql-proxy]

plugins=proxy,agent
agent-mgmt-hostname = http://agent:password@monitor-server:18080/heartbeat
mysqld-instance-dir= etc/instances
agent-item-files = share/mysql-proxy/items/quan.lua,share/mysql-proxy/items/items-mysql-monitor.xml
proxy-address=:6446
proxy-backend-addresses = 127.0.0.1:3306
proxy-lua-script        = share/mysql-proxy/quan.lua


agent-uuid = 8770ead5-3632-4b29-a413-4a7c92437e26
log-file = mysql-monitor-agent.log
pid-file=/Applications/mysql/enterprise/agent/mysql-monitor-agent.pid

Note

Do not copy the agent configuration information from one machine to another without changing the agent-uuid. Each agent instance must have a unique agent id.

The main configuration information must be located within the [mysql-proxy] section of the configuration file. The main configurable parameters within this file are:

  • plugins — configures the plugins to be used by the agent. When monitoring servers you must have the agent plugin configured. If you want to support Query Analyzer then you must also have the proxy module enabled. Plugins should be specified as a comma separated list of plugin names.

    If you selected to support Query Analyzer during installation of the agent, the default value will be proxy,agent. If you disabled Query Analysis during installation, the default value will be agent.

  • log-level — sets the logging level of the agent. The default level is critical.

    Valid values for log-level are as follows:

    • debug — provides detailed information about what the agent is doing and the information being provided by the agent to the MySQL Enterprise Service Manager.

    • critical — lists critical messages highlighting problems with the agent.

    • error — lists error messages.

    • warning — provides only warning messages generated by the agent.

    • message — provides information about the agent and basic processing information.

    • info — provides messages used for informational purposes.

    Warning

    Be careful when setting the log-level to debug. Doing this will rapidly increase the size of your mysql-monitor-agent.log file. To avoid disk space problems, put the log files on a different drive from your MySQL server and the MySQL Enterprise Dashboard.

    It is strongly recommended that you use a log-level of critical or error in a production server. Use the higher-levels to provide more detailed information only for debugging problems with your agent.

    Under Windows, if you restart the agent from the command line after setting the log-level to debug, extensive debug information is displayed to the console as well as to the log file.

  • agent-mgmt-hostname — sets the URL to use when reporting information. This value will be automatically set to your MySQL Enterprise Service Manager during installation.

  • mysqld-instance-dir — sets the directory where the configuration files that specify the MySQL servers to be monitored can be located.

  • agent-item-files — sets the information that is provided up to the MySQL Enterprise Service Manager when the agent is reporting status information. You should leave this item with the default setting of the share/mysql-proxy/items/quan.lua (which provides Query Analyzer data) and share/mysql-proxy/items/items-mysql-monitor.xml (which provides the core agent monitoring data).

  • proxy-address — sets the address and/or port number for the proxy to listen to for connections. The setting is used when employing Query Analysis as the address/port that you must configure your application to use in place of your normal MySQL server. By default this item is set during installation.

    The default value is 6446. If you want to support a different local host name/IP address and port, specify the host name and the port number, separated by a colon.

  • proxy-backend-addresses — sets the host name and port number to be used when communicating the backend MySQL server when employing query analyzer. This is the MySQL server where packets from the client are sent when communicating with the proxy on the host name/port set by the proxy-address.

  • proxy-lua-script — sets the Lua script to be used by the proxy when forwarding queries. To use Query Analyzer, this parameter should be set to share/mysql-proxy/quan.lua. This is the default value.

  • agent-uuid — sets the UUID (Universally Unique ID) of the agent. This value should be unique for all agents communicating with the same server, as the UUID is used to uniquely ID the agent within MySQL Enterprise Service Manager

    If you are setting up multiple hosts and copying the configuration between hosts, make sure that the agent-uuid is unique. You can have the agent create a new UUID by leavig this configuration property blank.

  • log-file — sets the location of the log file used to record information about the agent when it is running. If you do not specify a full path name, then the log file location is considered to be relative to the installation directory of the agent.

  • pid-file — sets the location of the file used to record the Process ID of the agent. This is used by the script that shuts down the agent to identify the process to be shutdown. The default value is the mysql-monitor-agent.pid file within the base installation directory as created by the agent installer.

15.3.3.6.2. MySQL Server (agent-instance.ini) Configuration

For the MySQL server that you want to monitor, you must create an agent-instance.ini within the directory specified by the mysqld-instance-dir configuration parameter within the main mysql-monitor-agent.ini file.

The agent-instance.ini file contains the host name and user credentials for connecting to the MySQL server that you want the agent to monitor. The format of the file is as follows: 

# To use this .ini file as a template for configuring additional
# instances to monitor, do not simply copy and start a new agent
# without first modifying the displayname.
#
# Refer to the documentation for more detailed information and
# instructions.
#
# Version: 20080718_230416_r7011

[mysqld]
hostname = 127.0.0.1
port     = 3306
user     = root
password =

The individual configuration parameters can be defined as follows:

  • hostname — the host name of the MySQL server that you want to monitor.

  • port — the TCP/IP port of the MySQL server that you want to monitor.

  • user — the user to use when connecting to the MySQL server that you want to monitor.

  • password — the corresponding password to use when connecting to the MySQL server that you want to monitor.

It is also possible to configure the agent to use sockets. This can be done during installation by selecting “socket” rather than “TCP/IP” from the menu and then specifying the socket name. This can also be configured after installation by editing the agent-instance.ini configuration file, and adding the line: 

socket = /full/path/to/mysql.sock
15.3.3.6.3. Monitoring Multiple MySQL Servers

You can monitor multiple MySQL servers (either on the same machine, or across different machines) using two different methods:

  • By using a single agent instance to monitor multiple MySQL servers. You can use this method if you want to monitor multiple servers, but do not want or need to support Query Analysis on the additional servers.

  • By using multiple copies of the MySQL Enterprise Monitor Agent to monitor each server individually. Using this method requires additional overhead to monitor each server, while also allowing you to supply Query Analyzer data.

Using a Single Agent Instance

Warning

Do not use the single agent instance method if you want to use Query Analyzer. If you set your application to use the proxy port provided by the single instance then the queries may not be directed to the correct server. Using Query Analyzer, the proxy, and the single agent instance method is not supported.

Warning

When using the single agent instance method, the agent will attempt to determine the right information about the backend server that it is monitoring in order to use the information when applying rule and advisor information. Currently, this operation is performed for only one of the servers in the list of configured servers. If the servers being monitoring are using different MySQL versions then the rules applied to the servers may be incorrect, and you could get wrong or misleading advice about issues or problems on a given server.

To use a single agent to monitor multiple instances, you can create additional directories and configuration files within the instances directory for the agent. For example, you can see the default structure of the agent configuration directory: 

./init.d
./init.d/mysql-monitor-agent
./instances
./instances/agent
./instances/agent/agent-instance.ini
./mysql-monitor-agent.ini

Within the instances directory, you can add further directories, one for each monitored server. Each additional directory must have a suitable agent-instance.ini file containing the connection information for the new MySQL server instance. For example, the following structure demonstrates an agent monitoring four MySQL servers: 

./init.d
./init.d/mysql-monitor-agent
./instances
./instances/agent
./instances/agent/agent-instance.ini
./instances/mysql2
./instances/mysql2/agent-instance.ini
./instances/mysql-rep
./instances/mysql-rep/agent-instance.ini
./instances/mysql-backup
./instances/mysql-backup/agent-instance.ini
./mysql-monitor-agent.ini

To add another MySQL monitored server, follow these steps:

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

  2. Copy an existing configuration directory and configuration files to the new directory: 

    shell> cp -R etc/instances/agent etc/instances/mysql2

  3. Edit the configuration file within the new directory, for example mysql2/agent-instance.ini, and set the user, password and either the hostname and port, or socket parameters.

  4. Restart the agent: 

    shell> mysql-monitor-agent restart

Using Multiple Agent Instances

To use multiple agents to monitor multiple MySQL servers you need to create a new configuration structure for both the agent and the MySQL server instances you need to monitor, including the binaries and configuration files, and then update the configuration to set the corresponding parameters to monitor the new server. Using this method allows you to enable query analyis by redirecting requests to the target server using the built-in proxy service within the agent.

For example, the directory structure below shows the configuration directory for two agents monitoring a single MySQL server each: 

./init.d
./init.d/mysql-monitor-agent
./instances
./instances/agent
./instances/agent/agent-instance.ini
./instances-second/agent
./instances-second/agent/agent-instance.ini
./mysql-monitor-agent.ini
./mysql-second-agent.ini

The mysql-monitor-agent.ini file contains the configuration for the first agent, with the MySQL servers monitored defined within the instances directory. The mysql-second-agent.ini file contains the configuration information for the second agent, with the MySQL servers monitor defined within the instances-second directory.

To set up multiple agents:

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

  2. You need to generate a new UUID for the new agent: 

    shell> /opt/mysql/enterprise/agent/bin/mysql-monitor-agent --agent-generate-uuid
ee9296d7-f7cd-4fee-8b26-ead884ebf398
2009-03-05 11:49:37: (critical) shutting down normally

    Keep a record of the UUID to update the configuration file.

    Note, the agent should not be running when the UUID is generated.

  3. Copy the main agent configuration file, which is by default in /opt/mysql/enterprise/agent/etc/mysql-monitor-agent.ini: 

    shell> cp mysql-monitor-agent.ini mysql-second-agent.ini

  4. Edit the new configuration file, changing the following settings:

    • Change the mysqld-instance-dir to the new directory that will contain the individual MySQL server configuration files.

    • Change the proxy-address to a different value than the first agent configuration.

    • Change the proxy-backend-addresses to specify the IP address and MySQL port number for the MySQL server.

    • Change the agent-uuid to the new value obtained in an earlier step.

    • Change the log-file parameter to specify a different file to use when logging errors and problems. You cannot log to the same file from two different agents.

    • Change the pid-file parameter to specify the file that will be used to store the process ID of the agent.

  5. Copy an existing configuration directory and configuration files to the new directory: 

    shell> cp -R etc/instances etc/instances-second

  6. Edit the configuration file, instances/second/agent/agent-instance.ini within the new directory, and set the user, password and either the hostname and port, or socket parameters.

  7. With multiple instances, you must start each agent individually, specifying the location of the main configuration file. For example, to start the original (default) service: 

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

    To start the second instance: 

    shell> /opt/mysql/enterprise/agent/etc/init.d/mysql-monitor-agent start /opt/mysql/monitor/agent/etc/mysql-second-agent.ini
15.3.3.6.4. Configuring an Agent to Monitor a Remote MySQL Server

Typically, the agent runs on the same machine as the MySQL server it is monitoring. Fortunately, this is not a requirement. If you want to monitor a MySQL server running on an operating system for which there is no agent available, 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 Section 15.3.3, “Monitor Agent Installation”. Follow the directions given there, being careful to 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.

Don't forget that the agent must be given 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 15.3.3.1, “Creating a MySQL User Account for the Monitor Agent”.

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

Note

Remote agents do not report the OS information for either the host or the agent.

If your subscription level entitles you to 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 Section 15.11, “The Replication Page”.

15.3.3.6.5. 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 hostname value specified in the [mysql-proxy] section of the .ini file. (For more information about the contents and location of the .ini file see Section 15.3.3.6.1, “MySQL Enterprise Monitor Agent (mysql-monitor-agent.ini) Configuration”.) Stop the agent and change the hostname value as shown in the following: 

hostname = http://agent_name:password@localhost:18080/heartbeat

Replace the agent_name and password with suitable values. Likewise replace port 18080 if you are not running the dashboard 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 18080:Dashboard_Host:18080 -l user_name -N Dashboard_Host

When prompted, enter the password for user_name.

If you are not running the MySQL Enterprise Service Manager on port 18080, substitute the appropriate port number. Likewise, replace Dashboard_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:

15.3.3.6.6. Generating a new UUID

For MySQL Enterprise Monitor to operate correctly, each agent must have a unique UUID in order to uniquely identify the agent with the MySQL Enterprise Service Manager.

Warning

Ensure that you do not reuse or duplicate a UUID. Running two agents with the same identification number yields unpredictable results

In Unix go to the command line and type: 

shell> /opt/mysql/enterprise/agent/bin/mysql-monitor-agent --agent-generate-uuid

In Mac OS X go to the command line and type: 

shell> /Applications/mysql/enterprise/agent/bin/mysql-monitor-agent --agent-generate-uuid

This should display a line similar to the following: 

ee9296d7-f7cd-4fee-8b26-ead884ebf398

Paste this line into the [mysql-proxy] section of the mysql-monitor-agent.ini file for the agent-uuid parameter: 

[mysql-proxy]
...
agent-uuid=ee9296d7-f7cd-4fee-8b26-ead884ebf398

In Windows, go to the command line and change to the MySQL Enterprise Monitor Agent installation directory and update the UUID by executing mysql-monitor-agent -uf mysql-monitor-agent-3307.ini. For example: 

C:\> cd C:\Program Files\MySQL\Enterprise\Agent
C:\> mysql-monitor-agent -uf mysql-monitor-agent.ini (or your .ini file name)

This updates the configuration file directly with the new UUID.