This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation.

Skip to end of metadata
Go to start of metadata

On this page:

AppDynamics strongly recommends that you perform routine data backups of the Controller and Platform Administration Application.

One method of maintaining backups of the Controller is to implement high availability. With high availability, the database on the secondary Controller keeps a replicated copy of the data on the primary Controller. A secondary Controller also makes it practical to take cold copies of the Controller data, since you can shut down the secondary to copy its data without affecting Controller availability. For information on HA, see Controller High Availability (HA)

Other approaches include using a disk snapshot mechanism, such as Linux Volume Manager, or using database backup tools. The BackupTools section describes tools that support each approach. In addition to regular backups, back up the Controller and Platform Administration Application before upgrading or migrating them from one server to another.

This page provides an overview of the tasks and considerations related to backing up the Controller and Platform Administration Application.

Best Practices for Backups

Backing up the entire system each night may not be feasible when dealing with the large amount of data typically generated by a Controller deployment. To balance the risk of data loss against the costs of performing backups, a typical backup strategy calls for backing up the system at different scopes at different times. That is, you may choose to perform partial backups more frequently and full backups less frequently.

The scope of a Controller backup can be categorized into these levels:

  • Level 1: A light backup of the installation environment only
  • Level 2: A metadata backup involving all metadata associated with the installation except big data tables.
  • Level 3: Backs up all data, either by performing a cold backup of the /data directory or a hot backup using a third-party tool.

A possible backup strategy may be to perform a level 1 and level 2 backup very frequently, say nightly, and a level 1 and level 3 backup about once a week. In addition to performing a level 1 or 2 backup, you should also backup the data for the Platform Administration Application with mysqldump on a regular basis. You do not need to backup the Platform Administration Application when you perform a level 3 backup since it also backs up the Platform Administration Application data.

Light Backup (Level 1)

A light backup targets Controller configuration files like db.cnf and domain.xml. This type of backup lets you avoid having to reconfigure the Controller in case of machine failure.

To perform this type of backup, simply copy everything in the Controller installation directory EXCEPT the data directory.

While it is recommended that you copy the entire Controller home except the data directory when performing a light backup, particularly before performing a Controller upgrade, there are scenarios in which you may wish to copy only site-specific configuration files. This may be the case if you are migrating an existing Controller configuration to a new Controller installation, for example. For a list of those files, see Migrate the Controller.   

Metadata Backup (Level 2)

A metadata backup exports the data that encapsulates the environment monitored by the Controller. Metadata defines the applications monitored by the Controller, business transactions, policies, and so on. It does not include what can be thought of as "runtime data", the big data tables that contain the metrics, snapshots, events, and top summary stats (top SQL, top URLs, and so on) generated in the monitored environment. By backing up metadata, you can avoid having to reconfigure monitored applications in the Controller in the event of a failure.

To perform this type of backup, run the script described in Using mysqldump to back up the Controller.

Complete Backup (Level 3)

A complete backup saves all runtime data associated with the Controller installation. It captures the actual metrics data, snapshots, and so on.

The AppDynamics Controller uses the default storage engine for MySQL, InnoDB. Since InnoDB supports transactions (in contrast to MyISAM), you cannot simply copy data files directly while the Controller is running. You need to stop the Controller before copying data files. However, some third-party backup tools, such as Percona XtraBackup, do not rely on transactions so you can perform a hot backup of your system (that is, back up the Controller database while it is running).

You can perform a complete backup as either:

  • A cold backup of the /data directory. A cold backup means that, with the Controller app server and database shut down, you create an extra copy of the Controller database using, for example, the "cp -r" command, the tar utility, rsync, or others.  
  • A hot backup, which means the Controller is running. For a hot backup, use a third-party tool such as Xtrabackup or LVM snapshotting.

    Disk snapshot tools for Controllers on AWS, such as AWS snapshot, ZFS snapshot, and Linux VM snapshot, may fail to create a useful backup of the live MySQL database and data directory. It is recommended that you instead use other tools mentioned on this page to capture MySQL hot backups for Controllers on AWS.

This type of backup allows you to skip the Level 2 backup and the Platform Administration Application backup. You still need to perform the Level 1 backup to back up the Controller home directory.

Backup Tools

This section lists a few third-party tools that you can use to back up Controller data. The list is not exhaustive; you can use any tool capable of backing up MySQL data with the Controller. However, the tool should back up the data as binary data. 

For Linux systems:

For Windows systems:

An alternative to using a database backup tool is to use a disk snapshot tool to replicate the disk or partition on which the Controller data resides. Options include:

Details for performing this type of backup are beyond the scope of this documentation. For more information, refer to administration documentation applicable to your specific operating system.

Back Up the Controller with mysqldump 

The mysqldump utility is a MySQL backup tool that is included with the Controller instance of MySQL.

While mysqldump is not recommended for use on large data tables, such as the Controller metric data tables, it is useful for backing up Controller metadata. Metadata defines the monitored domain for the Controller, including applications, business transactions, alert configurations, and so on.

The following instructions assume that the binary path for the Controller's MySQL instance is in the PATH variable. The path to the Controller's instance of MySQL must precede any other MySQL path on your system. This prevents conflicts with other database management systems on your machine, such as a MySQL instance included by default with Linux.

The database binary files for the Controller database are in <controller_home>/db/bin.

To use mysqldump, run the mysqldump executable, passing the root username, password, and output file. The executable is located in the following directory:


The command should be in the form:

mysqldump -u root -p<password> <ignore-table_statements> > /tmp/metadata_dump.sql

For a full example that shows which tables to exclude for a metadata backup, see the contents of the metadata backup script described in the next section.

Sample mysqldump Script

The following script illustrates how to use mysqldump to export Controller metadata while excluding runtime data tables by script. 

To use the script:

  1. Download the version appropriate for your operating system.
  2. Rename the file to remove the .txt extension.
  3. Modify the contents of the file as described in the script comments. 

Import Controller Data with mysql

When you restore or migrate the Controller, you can import the data you exported with mysqldump.

Use the following command to import the data into a database:

$install/db/bin/mysql -u controller -p<ControllerDBpassword> controller < metadata_dump.sql

Sample Data Backup Script

The following script uses Percona XtraBackup to back up Controller data. To use it, you need the percona-xtrabackup or xtrabackup and qpress packages. For information on installing XtraBackup, see the Percona installation documentation

To use the script, download the following file: 

Rename the script (by removing the .txt extension). In the script:

  • Verify or edit the values of the CONTROLLER_HOME and DESTINATION variables at the beginning of the script for your environment.
  • Edit the if/then/else clause at the end of the script if you want to implement backup file rotation, call your enterprise backup system to pick up the compressed Controller database image, or send an alert if the backup fails for any reason.

The following commands demonstrate how to restore a compressed backup image:

mkdir /path/to/big/staging/folder

# unpack the compressed backup archive
cd /path/to/big/staging/folder && xbstream -xv < /path/to/backups/dir/controller-yyyymmdd.xbstream
# decompress the backup image and apply the log taken during backup
CONTROLLER_HOME=/path/to/AppDynamics/Controller && cd /path/to/big/staging/folder \
&& innobackupex --decompress --parallel=16 . && innobackupex \
--defaults-file=$CONTROLLER_HOME/db/db.cnf --use-memory=1GB --apply-log --parallel=16 .

# Move a prepared backup into an empty controller data directory
CONTROLLER_HOME=/path/to/AppDynamics/Controller && cd /path/to/big/staging/folder \
&& innobackupex --defaults-file=$CONTROLLER_HOME/db/db.cnf --move-back .

For more information on these options, see the Percona innobackupex option reference.

Backup the Platform Administration Application with mysqldump

You back up the data for the Platform Administration Application separately from the Controller data. 

Run the following command to backup data for the Platform Administration Application:

mysqldump -u root -p<password> platform_admin > /tmp/platform_admin_dump.sql

The command creates an export file for the Platform Administration Application in the /tmp directory.  

You can import the data into a database with the following command:

$install/db/bin/mysql -u controller -p<ControllerDBPassword> platform_admin < platform_admin_dump.sql

Using a Backup to Migrate to a New Physical Server

You can use either a hot or cold backup procedure to migrate Controller data to a new server. However, we recommend performing cold backups. While a hot backup does not bring down the Controller for an extended amount of time, it does introduce the possibility of data loss, since hot backups capture the state of the data only when the hot backup starts.

To perform a cold backup, simply shut down the Controller and back up the data directory located in <controller_home>/db.

  • No labels