Migration tool details

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 the Upgrade and Migration Guide for upgrade or migration to 2017 May and later. For older versions refer of the Upgrade and Migration Guide of the old documentation. 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 6 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.


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

Upgrade or migrate Servers and Collectors

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"

Upgrade and migrate without automatic .ini-file migration

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

Create a minimal migration archive for support purposes

Caution: This command excludes agent binaries and should not be used for normal upgrades or migrations!
java -jar dynatrace-migration.jar -migration -sourceDTHome "C:\Program Files\dynaTrace\dynaTrace 6.2" -targetArchiveDir "<SOME_DIRECTORY>" -noclasscache -agentres no
Note: This does not contain any logfiles - these need to be collected separately.

Undo last migration step

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