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

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

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

If incorrect credentials are specified for the agent login to the MySQL server that it is monitoring, then the agent will not run on start-up. Log in to the monitored MySQL server and check the agent's credentials. Compare the values of the Host, User, and Password fields in the mysql.user table with the values shown in the [mysqld] section of the etc/instances/mysql/agent-instance.ini. If incorrect credentials are specified in the ini file, simply correct them and restart the agent. Remember, changes to the ini file do not take effect until the agent is restarted.

The agent will not start up if incorrect credentials are specified for the service manager login. Using incorrect credentials for logging in to the service manager creates an entry in the agent log file. For the location of this log file see Agent Log and PID Files.

If the agent starts up but no server appears in the dashboard, check the hostname specified in the [mysql-proxy] portion of the mysql-monitor-agent.ini file. Incorrect credentials, IP address, or port will all cause the MySQL server to fail to appear in the dashboard. Also, ensure that the port specified in this file is not blocked on the machine hosting the MySQL Enterprise Service Manager.

An easy way to confirm that the agent can log in to the service manager is to type http://Dashboard_Host:18080/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. If you log in successfully, you should see the following message:

<exceptions>
<error>E1031:  Agent payload parameter NULL.</error>
</exceptions>

If you can log in successfully in the way described above and the agent is running, then there are errors in the mysql-monitor-agent.ini file. Compare the host name, port, agent name, and password found in the ini file 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. For the location of this log file see Agent Log and PID Files.

If no HTTP authentication dialog box appears, and you are unable to connect at all, then you may have specified an incorrect host name or port. 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 15.6.3.8, “Monitoring Outside the Firewall with an SSH Tunnel”.

You can also check the agent error log file to help determine any problems. An error such as the following might indicate a blocked port:

(critical) connection to  merlin-server
'http://agent:test@172.11.1.1:18080/heartbeat' failed:
"connect() timed out!" error.

For the location of the agent error log file see, Agent Log and PID Files.

Setting the log-level entry in your ini file is also a good debugging technique. For more information on this subject see, MySQL Enterprise Agent Configurable Options.

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 and the log-file and pid-file values must be different. For more information, see MySQL Server (agent-instance.ini) Configuration.

If the agent is not running on the same machine that hosts the MySQL server it is monitoring, then you must 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 15.6.3.7, “Configuring an Agent to Monitor a Remote MySQL Server”.

The MySQL Enterprise Agent and MySQL Enterprise Service Manager use the hostid, stored within the mysql.inventory table on the monitored MySQL Server to determine whether the instance being monitored is a clone. The hostid of the current server is checked against the stored value when the agent starts. If the generated hostid and stored hostid do not match then you will get an error similar 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 will recreate the mysql.inventory table with the updated instance UUID and hostid information.

If the MySQL Enterprise Agent has been ungracefully terminated and restarted (for example after being terminated using kill), then you may see a DuplicateAgentUuidException error until the original registration of the previous instance of the agent has expired.