Migration tool details

Overview

The AppMon Migration Tool (dynatrace-migration) is a command line tool that can backup and migrate configuration data from an existing version to a new AppMon version.

You can download the latest version here. The download is an executable, so there is no need to extract the jar file.

See the AppMon 2017 May Upgrade and Migration Guide for full instructions on upgrade or migration. Click here for previous versions of the Upgrade and Migration Guide. These pages also contain details on Performance Warehouse and Session Store handling.

By their very nature the Performance Warehouse DB and the session store in the file system need a different strategy for backup / migration (database / file-based backup).

Migration Tool requirements

  • Java 7 or later is recommended, but Java 6x is also supported. AppMon includes a Java version in <DT_HOME>/jre that can be used if Java is not otherwise available.

  • All source or target installation components such as the Server and Client must be shut down before running the Migration Tool. This is necessary because files like the Collector class cache are constantly changing, and files may also change while the tool runs. This can result in corrupt files.

Use the Migration Tool

Call the Migration Tool without command line parameters for a list and descriptions of the parameters you can use.

Examples

Here are some usage examples beyond the basic one or two-step services migration as described in the first two service migration steps in Upgrade server, collectors, and clients section.

Upgrade and migrate in one command

You can migrate using a single command if you can access the file systems of both old and new installations at the same time. Specify target locations for sourceDTHome and targetDTHome. This example migrates an AppMon full package installation on Windows:

java -jar dynatrace-migration.jar -migration -sourceDTHome "C:\Program Files\dynaTrace\Dynatrace 6.5" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0"

Creating a backup archive

See AppMon Backup for how to use the migration tool to backup and restore critical files.

Upgrading with old Agent versions

If you have a need to keep old agent versions, it is possible during upgrade to keep the same agent version across application restarts. This command requires a target version of AppMon 6.3 or later, as well as bootstrap Agents 6.3 and later. The new bootstrap Agents must be connected to the old version Collectors before starting the Server upgrade.
java -jar dynatrace-migration.jar -migration sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 6.3" -upgradeAgents no

Agentres modification

Upgrading from AppMon 6.2 and earlier to AppMon 6.3 and later modifies the current version's agentres.jar to include the JavaScript Agent. This lets existing Webserver Agents inject the exact matching version. If the exact version match isn't found, the next higher version is injected. This is only relevant if there are Agents that have not been upgraded to AppMon 6.3 or later.

Use the -noAgentResModification flag to disable this modification, for instance:

java -jar dynatrace-migration.jar -migration -sourceDTHome "C:\Program Files\dynaTrace\dynaTrace 6.2" -noAgentResModification -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0

Upgrade and migrate without class cache

Data in the Collector class cache can be more than 10GB, which can take a significant amount of time and can pose a problem when transferring the file to the target location.

You can use the -noclasscache parameter to skip the class cache migration. However classes need to be newly discovered, therefore until the next Agent restart:

  • HotSensor placement do not work.
  • Class Browser do not show classes.
  • Unknown PurePath nodes can happen with Agents earlier than 6.0.

Therefore the usage of this flag is not recommended and by default the Collector class caches are migrated.

This command migrates the configuration data from the archive, but not the class cache. java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -noclasscache -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0

Select default and additional server and collector instances to migrate and upgrade migrate from archive

Upgrade and migrate all

This command example migrates and upgrades all default and additional AppMon Server and Collector instances from a specified archive. The command demonstrates the default behavior with for all parameters.

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0"

Upgrade and migrate default server and collector instances only

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -migrateInstances default

Upgrade and migrate default server instances

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -migrateInstances defaultServer

Upgrade and migrate default collector instance

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -migrateInstances defaultCollector

Upgrade and migrate additional instances only (not default server and collector)

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -migrateInstances instances

Upgrade and migrate additional server instances (not default server)

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -migrateInstances ServerInstances

Upgrade and migrate additional collector instances (not default collector)

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -migrateInstances CollectorInstances

Upgrade and migrate a single collector instances (not default collector)

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -migrateCollectorInstance INSTANCENAME

Upgrade and migrate, and specify alternative migration backup directory

java -jar dynatrace-migration.jar -migration -sourceArchive "C:\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0" -backupDir "D:\migrationBackup"

Undo last migration step

java -jar dynatrace-migration.jar -undomigration -targetDTHome "C:\Program Files\dynaTrace\Dynatrace 7.0"