7.3 Guide for Upgrading to MySQL Enterprise Monitor 3.0

The purpose of the guide is to help you safely upgrade your production MySQL Enterprise Monitor from 2.3 to 3.0 with minimal loss of active monitoring during the upgrade process. if you are performing a complete or first-time installation, see Chapter 4, Service Manager Installation instead.


The MEM 3.0 update installers upgrade from the recent versions of 2.3 or 3.0 to the latest 3.0 release. You can also use an update installer to reconfigure the same version, i.e. run the 3.0.0 update installer on 3.0.0 itself to specify a different port for the UI or change an SSL setting. If your existing Monitor setup is older than 2.3, you must either upgrade to 2.3 and then upgrade to 3.0 or perform a clean installation of 3.0.

Quick summary

  1. It is recommended to start by installing a "test" of a 3.0 Service Manager and 3.0 Agents side-by-side with your 2.3 environment.

  2. When comfortable with 3.0, you can then either:

    • Phase-out your 2.3 installation, (perhaps retaining it for historical information), and phase-in your "test" 3.0 installation as the primary Monitoring tool.

    • After testing the 3.0 installation, uninstall it and migrate your 2.3 MySQL Enterprise Service Manager to 3.0.

Running a test installation of the 3.0 Service Manager enables you to learn, configure and test the new system without disturbing your production 2.3 Monitor.


MySQL Enterprise Monitor 3.0 has significant differences to version 2.3, with an entirely different inventory, instrument data, Query Analysis, Advisor configuration, and notification models. For this reason, when upgrading from 2.3 to 3.0, history data for events, graphs, Query Analysis, and configuration data of Advisor schedules are not migrated.

With this in mind, the following are suggested upgrade paths, which allow you to maintain your monitoring coverage with minimal loss of history.

Using a Bundled or Remote repository

When you install the 3.0 test Service Manager, you are prompted on whether or not to use the bundled MySQL server to manage the Monitor's repository. If your existing 2.3 Monitor does use the bundled MySQL server, then you should choose the same option for your 3.0 test system.

However, if your 2.3 setup uses a separate MySQL instance that you manage, you should set up the 3.0 test install the same way by configuring another MySQL database server to use as the 3.0 test repository. Do not use the same repository as the 2.3 instance, as when the Service Manager starts, it migrates this data, and removes the tables within the MySQL Enterprise Service Manager schema. You should do this now before proceeding.


Multiple MySQL Enterprise Service Manager installations cannot share the same repository, so do not attempt to share a single non-bundled repository for both a 2.3 and 3.0 installation.


Moving the Monitor's repository onto its own host enables the system to scale to monitor significantly more Instances.

Installing the 3.0 Service Manager in a test environment

Once it is installed, launch the Service Manager and complete the first-time setup. After a brief warm-up period, MySQL Enterprise Monitor 3.0 beginse monitoring the host and repository. Next you should follow the steps in the Chapter 6, Post-installation Considerations section, set up SMTP, user accounts and privileges, email notification groups and, depending on the size of your environment, groups of MySQL Instances.


Warm-up Period: If a 2.3 to 3.0 Service Manager upgrade is performed while 2.3 Agents are still active, Agents and/or Instances appear to be unavailable. This triggers Events and email notifications. The Events auto-close once the warm-up period is over.

Install one Agent per monitored Host

Now that the Service Manager is fully configured, the final installation task is to install a single 3.0 Agent on each physical host that you want to include in your 3.0 test. New in 3.0, for each Agent you install, you can configure it to monitor its host (only) or optionally also configure it to monitor a MySQL Instance at install time. Whichever you choose, the Agent continuously detects and reports to the UI any unmonitored Instances it discovers whether they were present when you installed or start up in future. If you have multiple MySQL Instances running on a single host, use a single 3.0 Agent to monitor them.

Deploying 3.0 in production

When you are finished testing and are ready to deploy 3.0 as your production monitoring system, you have a couple of choices depending on how large your installation is, and whether you intend to keep running the 2.3 Monitor once 3.0 is deployed.

Method #1: Switch 3.0 Test" to 3.0 Production

If you have already installed, customized and tuned your 3.0 test installation, you may want to simply convert it into your production monitoring system by upgrading any remaining 2.3 Agents to 3.0 and re-directing them to the 3.0 Service Manager. See the "Upgrading Agents to 3.0" section below for how to do so safely. You can then leave the 2.3 Monitor running indefinitely to view historical graph and Events data, or you can uninstall it and reclaim the disk space. Make sure to disable notifications if you intend to continue using it to view past monitoring data.

Method #2: Shutdown 3.0 test, and upgrade 2.3 to 3.0

At this point, the 3.0 test was successful and you want to shut it down and then convert your existing 2.3 Monitor to version 3.0.


The 3.0 update installer migrates application data like SMTP settings, user and notification information, Group names, Instance names and notes, etc; however, the new Event and Graph functionality are so different (and improved) from 2.3 that 3.0 cannot display 2.3 historical Graph and Event data in the UI. If you want to retain access to that historical data until it is completely purged, follow the instructions above to 'Switch to "3.0 test" to "3.0 production"' and leave the 2.3 Monitor running.

AUpgrading from 2.3.x to 3.0.0 overwrites MySQL Enterprise Monitor's my.cnf/my.ini configuration file. The only MySQL options that are migrated from the 2.3.x MySQL configuration file are port, datadir, socket, ssl-ca, ssl-cert, ssl-key, and innodb_log_file_size.

If your 2.3 Monitor is communicating with a significant number of Agents and Instances, we advise suspending monitoring temporarily by: (1) shutting down 2.3 Agents (2) updating the Service Manager to 3.0 (3) updating each 2.3 Agent to 3.0 and watching them go live one-by-one. See the Section 7.3, “Guide for Upgrading to MySQL Enterprise Monitor 3.0” section for important information about this procedure.

After the Service Manager and Agents are upgraded to 3.0, you can uninstall the 3.0 test installation. Make sure any Instances or Hosts you were monitoring as part of the test are now pointing to your upgraded Service Manager, or uninstall those 3.0 test Agents.

Upgrading Agents to 3.0

The 3.0 Monitor runs most efficiently and effectively if all the Agents communicating with it are shutdown normally, upgraded to 3.0 and then restarted. It is strongly recommended to upgrade all Agents to the latest version. If you have a very large number of monitored Hosts or Instances, it is always best to restart them one at a time or in small batches after they are upgraded to 3.0.


* The 3.0 Service Manager is designed to communicate with 2.3 Agents in a limited manner to facilitate minimal downtime during the upgrade process. There are a few issues to be aware of if one or more 2.3 agents are live and talking to a 3.0 Service Manager

Multiple Agent Accounts: Connections from the Agent to a monitored MySQL Instance are done using whatever account has the minimum permissions level required. For more information, see Section 5.2, “Creating MySQL User Accounts for the Monitor Agent”.

SSL is now required as follows:

  • HTTP requests to the 3.0 UI now redirect to a secure port, and may generate an "untrusted site" warning in your browser. See SSL Considerations.

  • 3.0 Agents always use a secure connection when communicating with the Service Manager. For backwards compatibility, SSL is still optional (but recommended) for 2.3 Agents connecting to the 3.0 Service Manager.

  • Although SSL is optional with 2.3, for security purposes we recommend that you enable SSL for your 2.3 Agents.

The upgrade installer checks for the MEM 2.3 Agent configuration file (mysql-monitor-agent.ini) to verify that the directory you point to for the upgrade is an Agent installation directory.

Clone the 2.3 Monitor and upgrade it as part of your test, the steps are:

On a new system:

  1. Install with a full installer for 3.0

  2. Don't start it up after the installation (just say "no" when it asks to launch the app at the end)

  3. Copy the mysql data directory from 2.3, and overwrite the data directory you just installed

  4. Start up the Service Manager

It migrates all user data and you start off with SMTP, SNMP, and so on, configured.

Upgrading Agents doing multi-instance monitoring

If you are using a 2.3 Agent to monitor multiple MySQL instances, then special considerations are required when upgrading these Agents to 3.0.


After you have tested your 3.0 installation, you may want to switch production monitoring to this system instead of going back and physically upgrading your original 2.3 system. If this is at all likely, we suggest you provision this new 3.0 Monitor host with resources (CPU, RAM, and so on) at least equivalent to the one that is currently running your 2.3 system.

When multiple 2.3 Agents are installed on a single host, first migrate one of the 2.3 Agents to 3.0 (as described in the previous documentation), and then migrate the connection details from each of the other 2.3 Agents using the following command:

shell> ./bin/agent.sh --migrate-agent=/path/to/some/agent/install/etc/instances      

Now, each of the monitored MySQL instances uses the upgraded 3.0 Agent. Alternatively, you may rely on the auto-discovery method of the 3.0 Agent to discover the additional MySQL instances.

Migrating custom rules/graphs

These are automatically migrated after MySQL Enterprise Monitor 3.0 is started.

Proxy and Aggregator Notes

As of MySQL Enterprise Monitor 3.0.14, the MySQL Enterprise Monitor Proxy and Aggregator are delivered separately from the MySQL Enterprise Monitor Agent. To upgrade from a previous version, you must uninstall your existing MySQL Enterprise Monitor Agent and MySQL Enterprise Monitor Proxy and Aggregator installation and install the new version. For more information on the MySQL Enterprise Monitor Proxy and Aggregator, see Chapter 11, Proxy and Aggregator Installation