7.2 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.

Note

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 will either need to first upgrade to 2.3 and then upgrade to 3.0. Depending on the size of your existing installation, it may be faster to perform a full install of 3.0 and configure it from scratch.

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 will enable you to learn, configure and test the new system without disturbing your production 2.3 Monitor.

Important

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 will 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 will be 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 will migrate this data, and remove the tables within the MySQL Enterprise Service Manager schema. You should do this now before proceeding.

Note

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

Note

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

Installing the 3.0 Service Manager in a test environment

You will use the bundled MySQL server or you have created a standalone server that your 3.0 test install will use, now it is time to run the full installer for the 3.0 Service Manager. See Chapter 4, Service Manager Installation for help with completing this part of the test installation. When it is installed, launch the Service Manager and complete the first-time setup. After a brief warm-up period, MySQL Enterprise Monitor 3.0 will be monitoring the host it is running on plus its own MySQL repository. Next you should follow the steps in the Chapter 6, Post-installation Considerations section, i.e. you will set up SMTP, user accounts and privileges, email notification groups and, depending on the size of your environment, Groups of MySQL Instances.

Note

Warm-up Period: If a 2.3 to 3.0 Service Manager upgrade is performed while 2.3 Agents are still active, you will likely see a "warm-up period" where Agents and/or Instances appear to be unavailable. This will likely fire off both Events and email notifications. These Events should 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 will continuously detect and report 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, you will use a single 3.0 Agent to monitor them all. See "Multi-Instance Monitoring in 3.0" for more information.

Deploying 3.0 in production

When you are done 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 to "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 will continue using it to view past monitoring data. Assuming you have purge enabled, at some point all the data will fade away and you can run the 2.3 uninstaller.

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

This is probably what you expected to see in a section describing how to do an upgrade from 2.3. However, as you have seen, doing so is a multi-phrase process. 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.

Important

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

Also, upgrading from 2.3.x to 3.0.0 will overwrite 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. This is because MySQL Enterprise Monitor 3.x contains a significant amount of changes, so we recommend using our default MySQL configuration file.

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.2, “Guide for Upgrading to MySQL Enterprise Monitor 3.0” section for important information about this procedure.

When your Service Manager is upgraded to 3.0 and all Agents have been upgraded as well, 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 now-upgraded Service Manager, or uninstall those 3.0 test Agents as well.

Upgrading Agents to 3.0

The 3.0 Monitor will run most efficiently and effectively if all the Agents communicating with it are shutdown normally, upgraded to 3.0 and then restarted. There are several reasons to continue running a 2.3 Agent, but generally we strongly encourage upgrading 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.

Note

* 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 will be done using whatever account has the minimum permissions level required. For more information, see Section 5.1, “Creating MySQL User Accounts for the Monitor Agent”.

Note that SSL is now required as follows:

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 will migrate all user data and you will start off with SMTP, SNMP, etc. already configured and ready to go.

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.

Note

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 will use 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 over, after MySQL Enterprise Monitor 3.0 is started.

Proxy and Aggregator Notes

Proxy - In general, it is possible but not recommended to keep a 2.3 Agent running and communicating with a 3.0 Service Manager more long term. However, if you have a 2.3 Agent that has an active MySQL Proxy plugin in use for collecting Query Analyzer performance data that you wish to continue using with the Proxy, you will need to keep using it as a plugin to the 2.3 Agent as this is not supported in 3.0. Note that MEM 3.0 features several other sources of data for the Query Analyzer, including being based on Performance Schema from MySQL 5.6.14 (or later) and the Connector plugins for Java, .NET and PHP. When possible, we advise switching from the Proxy to one of these sources in order to enable the Query Analyzer.

Attempting to upgrade a system that relies on the Proxy or Aggregator will emit the following warning:

WARNING: The previous installation of your Enterprise Monitor Agent enabled either the Proxy, the Aggregator, or both. Please note that the Proxy and Aggregator are now completely separate from the Agent and should be installed and maintained separately. If you continue with this installation, the Agent will upgraded, but the Proxy and Aggregator will be removed and will no longer function. If your application depends on the Proxy or the Aggregator, you should abort this upgrade and refer to the Enterprise Monitor documentation for information on how to proceed.