[+/-]
mysql-monitor-agent.ini
)
Configurationagent-instance.ini
) Configuration
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”.
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
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.
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.
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
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
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.
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:
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”.
Copy an existing configuration directory and configuration files to the new directory:
shell> cp -R etc/instances/agent etc/instances/mysql2
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.
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:
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”.
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.
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
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.
Copy an existing configuration directory and configuration files to the new directory:
shell> cp -R etc/instances etc/instances-second
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.
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
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.
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”.
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:
Under Windows see, Section 15.3.3.5.1, “Starting/Stopping the Agent on Windows”.
Under Unix see, Section 15.3.3.5.3, “Starting/Stopping the Agent on Unix”.
Under Mac OS X see, Section 15.3.3.5.2, “Starting/Stopping the Agent on Mac OS X”.
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.
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.
User Comments
Add your own comment.