Dynatrace 6.2Upgrade and Migration Guide

Upgrade and Migration Guide

2        Dynatrace 6.2

Please direct questions about your Dynatrace product or comments on this document to:

Dynatrace Customer Supporthttps://community.dynatrace.com/community/display/SUPPORT

Copyright © 2015 Dynatrace LLC. All rights reserved. Unpublished rights reserved under the Copyright Laws of the United States.

U.S. GOVERNMENT RIGHTS-Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in Dynatrace LLC license agreement and as provided in DFARS 227.7202-1(a) and 227.7202-3(a) (1995), DFARS 252.227-7013(c)(1)(ii) (OCT 1988), FAR 12.212(a) (1995), FAR 52.227-19, or FAR 52.227-14 (ALT III), as applicable.

This product contains confidential information and trade secrets of Dynatrace LLC. Disclosure is prohibited without the prior express written permission of Dynatrace LLC. Use of this product is subject to the terms and conditions of the user's License Agreement with Dynatrace LLC.

Documentation may only be reproduced by Licensee for internal use. The content of this document may not be altered, modified or changed without the express written consent of Dynatrace LLC. Dynatrace LLC may change the content specified herein at any time, with or without notice. All current Dynatrace LLC product documentation can be found at

.https://community.dynatrace.com/community/display/APMDOC

Adobe® Reader® is a registered trademark of Adobe Systems Incorporated in the United States and/or other countries.

All other company and product names are trademarks or registered trademarks of their respective owners.

Document exported by on UTC.PDF Creator 14-Nov-2015 20:15

Dynatrace is the innovator behind the new generation of Application Performance Management. Our passion: helping customers, large and small, see their applications and digital channels through the lens of end users. Over 5,700 organizations use these insights to master complexity, gain operational agility, and grow revenue by delivering amazing user experiences.

Upgrade and Migration Guide

Dynatrace 6.2        3

Table of Contents

1 Prepare to Upgrade 6

1.1 Agent Compatibility Matrix 91.1.1 De-supported Versions 10

2 Upgrade Server, Collectors, and Clients 11

2.1 Install the New Server, Collectors, and Clients 11

2.2 Shut Down the Old Version 11

2.3 Create Backups 12

2.4 Services Migration (Server, Collector and Memory Analysis Server) 122.4.1 File Migration 132.4.2 Edit Configuration Files 142.4.3 Migrating Additional Server Instances 142.4.4 Register and Auto-start Additional Collector Instances 14

2.5 Auto-Start New Services 15

2.6 Client Migration 15

2.7 Copy Session Storage 15

2.8 Start the New Server components 16

2.9 Start the New Client 16

2.10 Activate Licenses for the New Server 16

2.11 Select Server Sizing 17

2.12 Apply Update to New Dynatrace 17

2.13 Connect the Performance Warehouse 17

Upgrade and Migration Guide

4        Dynatrace 6.2

2.14 Configure Session Storage 17

2.15 Start New Collectors 18

2.16 dtmigration Tool Details 182.16.1 Overview 192.16.2 dtmigration Usage 192.16.3 dtmigration Examples 21

2.17 Manual File Migration 22

3 Upgrade Agents 25

3.1 Upgrade Agents 253.1.1 Bootstrapped Agents (Java, .NET, Host, Native ADK, Web Server, PHP, CICS, and IMS) 253.1.2 Non-bootstrapped Agents Needing Manual Update (Browser and Mobile App ADK) 263.1.3 z/OS Agents 26

3.2 Restart Agents 26

3.3 Upgrading Bootstrap Agents 273.3.1 Preparation 273.3.2 Bootstrap agent upgrade process 273.3.3 Uninstall the outdated agents 28

3.4 Upgrading zOS Agents 283.4.1 Prerequisites 283.4.2 Upgrade Procedure 29

4 Final Checks 31

4.1 Confirm Operation of the New Dynatrace Server 31

4.2 Check Configuration 314.2.1 Check Mobile Error Detection Rules 314.2.2 Apply Customizations Not Covered By Automation 31

5 Troubleshooting 33

5.1 Frequently Asked Questions/Issues 33

5.2 DynaTrace Support 34

6 Index 35

Upgrade and Migration Guide

Dynatrace 6.2        5

Follow the instructions in this guide to:

Upgrade your existing Dynatrace environment to 6.2, or

Migrate an existing Dynatrace 6.2 Server to another host machine

1. Prepare for your migration (see page 6)

Before you start, review your current installation (Servers, Collectors, Agents) to determine what release you are currently using, and to see if those components can be directly upgraded to the new release. Also, review the to make sure you are using supported System Requirementshardware and platforms.

2. Install the new components and transfer data to it (see page 11)

Install the new components and to move your current use the latest Tool 6.3.0.1073dTMigration

data and configurations to the new installation. Please check the version displayed when you run the tool from the command line!You'll need to do a few manual moves and edits to complete the migration.

3. Upgrade your Agents, if needed (see page 25)

Most Agents automatically upgrade with the new release. In some cases, you may need to manually upgrade your Agents.

4. Final checks and verification (see page 31)

Start up Dynatrace and see if your Agents are sending data and your PurePaths and dashboards are displaying properly.

Upgrade and Migration Guide

6        Dynatrace 6.2

1 Prepare to Upgrade

Review this checklist to ensure you are ready to migrate.

Complete? Step

Determine the Dynatrace version and installation type you are currently using:

For versions < 4.2, you migrate to 5.6 first. See the for instructions. must 5.6 migration documentation

For Proof of Concept (POC) and evaluation installations, a .new installation is required

For Independent Software Vendor editions (PTC Windchill), use the documentation supplied by the vendor.

Create an inventory of your installed Dynatrace Collectors, Dynatrace Agents, and Dynatrace Clients to understand the scope of the upgrade.

Upgrade and Migration Guide

Dynatrace 6.2        7

Complete? Step

Verify that the for Dynatrace Server, Frontend Server, Collector, and Client are met. Some system requirementskey points are:

The use of the Server instance feature ( parameter) will be deprecated in the future. We -instance

recommend you use this guide to migrate the default Server instance, but perform a fresh installation of the other Server instances before performing this migration.

However, Collector instances are still supported.

The Servers are with Collectors with matching and same or lower minor only compatible major versionversion. For instance a 6.1 Server will work with a 6.0 Collector, but with a 5.6 or 6.2 Collector.not

In 6.0, a new Frontend Server component was added and must be started to connect Clients.

A is now available and is instead of the 32-bit version. 64-bit Client recommended See Client Configuration and Webstart Client for more details.

For the Server on Linux, (number of file handles) >= 2048 has been enforced since 5.6. For ulimit -n

details, see .Server Configuration

This migration does support a Server -embedded Collector. for your not Install a stand-alone service current version you upgrade. This is especially the case for Dynatrace Development Team beforeeditions.

An embedded Performance Warehouse is supported for migration. Switch to an external one first, not as described .here

If LDAP authentication is enabled, users need to be members of at least one Dynatrace LDAP group to log in. See for details.LDAP

If you are integrating with DC RUM, then DC RUM must be >= 12.0.2.

As of 6.2 host monitoring changed significantly. Monitored hosts are no longer mapped to System Profiles, but are managed globally in a section called . Because of these changes, historical host Infrastructuremonitoring data that was collected before the migration and is bound to System Profiles will no longer be accessible when using Dynatrace 6.2.The procedure to make the historic host monitoring data accessible again after a migration is documented in the KB - please refer to After Upgrade to 6.2, Host Metrics From Times Before the Upgrade Are No Longer Shown

Review your Server sizing by beforehand, if upgrading from:contacting support

≤ 5.6 and in the value is >14GBdtserver.ini -Xmx

≥ 6.0 and in or the value of is dtserver.ini dfrontendserver.ini memory unsupported

Upgrade and Migration Guide

8        Dynatrace 6.2

Complete? Step

Review the to determine if your existing Agents are compatible with Agent Compatibility Matrix (see page 9)new Servers and Collectors, and to help you plan the restarting of your application tiers. Check your current version to see if your Agents are bootstrapped, and will upgrade automatically when they connect to the new Collector. If not, upgrade them after you upgrade the other components.

Tip

As a best practice, plan your upgrade around scheduled maintenance windows, especially when upgrading from 4.2:

When upgrading from 4.2, you must be able to restart in the all interdependent applications closest time frame as possible to avoid broken PurePaths.

When upgrading from > 4.2, you must be able to restart Agent Groups / tiers should incompatibilities arise.

Are you using an Agent Development Kit (ADK) < 5.0?

These are not compatible with the current version of Dynatrace. Prepare a new version of your pre-5 application using the new ADK found and have it ready to deploy during the Agent upgrade phase. Details are found hereon the .ADK page

Document whether you are using . Check in the Dynatrace Client:continuous transaction storage Settings > .> StorageDynatrace Server

Document which additional plugins were installed: Dynatrace Client : Settings > Dynatrace Server

Performance Warehouse database and :Session Store

Document the current configuration: From the Client menu: , and choose Settings > Dynatrace Server in the left pane:

Performance Warehouse all details including password, because as of 6.1 the password storage changed and you will need to re-enter your password after migration.

Storage for Session Store location.

Be prepared to create backups as part of this guide

Check in the whether your SQL DB server is supported:System Requirements

If not, create a and to a supported DB you upgrade.backup switch before

Verify that the configured user has the permissions to create and drop tables Performance Warehouse for the DBMS.

Upgrade and Migration Guide

Dynatrace 6.2        9

Complete? Step

Deactivate the license on your existing . For an upgrade to the newest version upgrade the Dynatrace Serverlicense in . See .eServices License Upgrade Documentation

The number of Web Server Agents licensed has been enforced since 5.0, so check how many are covered after the upgrade of your license(s) or talk to sales if you are unsure.

If you use z/OS Agents, in addition to the Dynatrace Server license, you must also have a Dynatrace PurePath z/OS license for CICS, IMS, and/or Java Agents via your licensing admin or sales. For details, see .Upgrading zOS Agents (see page 28)

Download the software required for the migration:

Installers (version 6.2.0.1239 – full or Server- / Collector- / Client- / Memory Analysis Server- or Agent-only) for your application platforms and operating systems.

dTMigration Tool 6.3.0.1073

The latest Update, if available, is found at the top of the 6.2 list. Compare the Update downloadsrevision and build number and the GA revision and build number (here 0.1239 ) and download the Update if needed to have it ready later. Updates are installed on a Server from the menu.running Tools

If you don't have internet connectivity from the Server, download the upgraded licenses from .eServices

You can run parallel versions of Dynatrace to test your upgrade, but be aware of the requirements for this configuration.

Please exactly and in this guide to enable a smooth follow the steps in the order foundmigration.

Next: Upgrade Server, Collectors, and Clients (see page 11)

1.1 Agent Compatibility MatrixAgents are upgraded depending on their type:

Bootstrapped Agents update automatically when the instrumented application is restarted.

When are used they need to be upgraded manually. (installed to non-bootstrapped Agentsa new directory structure) When the application tiers are restarted, the Agent connection string must point to the new path.

Agent Dynatrace Client' To determine versions and whether they are bootstrapped, use the s . Cockpits > Agent Overview Dashboard

Upgrade and Migration Guide

10        Dynatrace 6.2

Although connections between older Agents and newer Collectors are supported, Agents should be upgraded to the Collector version as soon as possible – by installing the new Agents and restarting the apps.

Agent/CollectorCompatibility

Collector (across)/ Agent (down)

6.0 6.1 6.2

5.6 OK OK OK

6.0 OK OK OK

6.1 n/a 1) OK OK

6.2 n/a 1 ) n/a 1 ) OK

1) Upgrade the Server and Collectors before non-bootstrapped Agents.

1.1.1 De-supported Versions4.2, 5.0 and 5.5 Agents connect and can be bootstrapped with 6.2. We highly recommend to upgrade any Agent< 5.6 as soon as possible!

Upgrade and Migration Guide

Dynatrace 6.2        11

1.

2 Upgrade Server, Collectors, and Clients

If you are migrating the Server to a new host without upgrading to a new version, you only need to perform the applicable steps, for example, not stopping or installing new Collector s.

2.1 Install the New Server, Collectors, and ClientsInstall a new Dynatrace Server and as many new Dynatrace Collectors and Clients as needed on all involved machines. Remember that the 6.0 Server only supports 6.0 Collectors.

The new Server and Collectors should be installed to a , which is referred to new directoryas in these instructions.<DT_HOME_NEW>

Windows: Use the full-product installer option or use the separate installers for the CustomServer, Collector, and Client.

Important: Windows full-product installer: At the end of the installation, you're prompted to start the Server, Collector, and Client. Do not start these components at this time.

:*NIX Do unzip the In the directory runnot .jar. /opt

java -jar <pathToInstallerJar>/dynatrace- -linux-<bit>.jar6.2.0.<build>

We recommend the default installation directory.

See for automation.Unattended (Silent) Installation

2.2 Shut Down the Old VersionDisconnect the Performance Warehouse from the old Server in the Client: Settings >

.Dynatrace Servers > Performance Warehouse

Upgrade and Migration Guide

12        Dynatrace 6.2

2.

3.

1.

2.

3.

Close the old Client and stop the old Server, Frontend Server, Collector and Memory Analysis Server services.

Note: Instructions on how to start and stop any dynaTrace services can be found . here

Deactivate automatic startup of the old Server, Frontend Server , Collector and Memory Analysis Server:

• : Go to the . In each service's Windows Control Panel > Administrative Tools > Servicesproperties, set the to .Startup type Manual• : Use or to disable all Dynatrace services.*NIX chkconfig update-rc.d

2.3 Create BackupsUsing the configuration information collected during preparation:

Back up your Performance Warehouse DB.

.Back up your Session Store

On *NIX, back up all Dynatrace scripts in /etc/init.d.

2.4 Services Migration (Server, Collector and Memory Analysis Server)To migrate the Dynatrace services and data, use the latest version of the dtmigration command line tool , which copies customizations, custom Sensor packs, most ( Tool 6.3.0.1073dTMigration )user plugins and dashboards from the old installation to the new one. Use on all dtmigration

Server and Collector machines.

We recommend a two-step approach to migration using : create an archive from the dtmigration

old release that also serves as a backup, and then transfer the file to the new release (and new host if needed).

See or run for command dtmigration Tool Details (see page 18) java -jar dtmigration.jar

syntax and other migration options.

Read how to manually migrate without .dtmigration here (see page 22)

Upgrade and Migration Guide

Dynatrace 6.2        13

1.

2.

Tip: We strongly recommend to using the option to migrate the Collector class cachessave yourself two app restarts (before and after class discovery), and to avoid <unknown>

PurePath nodes or missing PurePaths.

By default, migrates the Collector class cache (< 1 GB), which allows running dtmigration

Agents to work with new Collector s without an immediate restart.

Consider using the option to migrate Servers and Collectors separately -migrateInstances

– with and without option.-noclasscache

If not migrating the class cache.

If you are using the option, the files in the class cache folders will not be copied.-noclasscache

2.4.1 File MigrationUse to create a migration archive (the example here migrates the class cache).dtmigration

java -jar dtmigration.jar -migration -sourceDTHome " " -targetArchiveDir "<<DT_HOME_OLD>

_DIR>"ARCHIVE

Where refers to your oldDynatraceinstallation path. A < DT_HOME_OLD> <MIGRATION_ARCHIVE>

file named will be created in .<Server_name>_<creation_dateTime>.dtma <ARCHIVE_DIR>

Back up the migration file, and use the following default parameters to migrate all Serverand Collector instances. You can also migrate to a new host. For other options, see dtmigration

.Tool Details (see page 18)java -jar dtmigration.jar -migration -sourceArchive "<ARCHIVE_DIR>

/<MIGRATION_ARCHIVE>" -targetDTHome "<DT_HOME_NEW>"

The necessary changes will be made to the target directory. Backups (of changed files in ) and a migration log are created in a new directory in <DT_HOME_NEW> <DT_HOME_NEW>

./migration/backup/ Do not delete this backup directorybefore you verifythat the migration was successful.

If you encounter problems during these steps, notify support and consider the alternative Manual .File Migration (see page 22)

Upgrade and Migration Guide

14        Dynatrace 6.2

2.4.2 Edit Configuration FilesLastly, lists configuration settings you may want to migrate manually to the new dtmigration

release. If we simply copied/overwrote all files, you could lose options we have introduced over recent releases. Therefore, the applicable old files are copied with the suffix . These .toBeMigrated

files are found in .<DT_HOME_NEW>

Here is a sample output:

There are some files left, which have to be migrated manually:

In c:\Program Files\dynaTrace\dynaTrace 6.2:

\dtserver.ini has to be migrated manually by applying custom setting from \dtserver.ini.toBeMigrated

\server\conf\ipmappings.xml has to be migrated manually by applying custom settings from

\server\conf\ipmappings.xml.toBeMigrated

\dtcollector.ini has to be migrated manually by appling custom settings from \dtcollector.ini.toBeMigrated

\dtanalysisserver.ini has to be migrated manually by appling custom settings from \dtanalysisserver.ini.

toBeMigrated

From each file, to preserve the correct file permissions and .toBeMigrated edit the original filecarry over all the startup options missing or configured differently in the / ..ini .xml

dtserver.ini: If you are upgrading and using continuous transaction storage (see ), do migrate Prerequisites (see page 6) not -D com.dynatrace.diagnostics.memory.

if present.maxPurePathBufferSize=<X>

Note: If you used a custom keystore in the old installation, manually copy the keystore-files from to <DT_HOME_OLD> <DT_HOME_NEW>

See more at and .Server Configuration Collector Configuration

2.4.3 Migrating Additional Server InstancesMultiple Dynatrace Server instances on one host will be deprecated in the future. If present, we recommend to perform a fresh installation for each instance, except the default instance, which can be migrated using this guide.

2.4.4 Register and Auto-start Additional Collector InstancesExpand for information on instances.

If you used Collector instances in the old installation:

Windows: In the directory , for each Collectorinstance, using the same <DT_HOME_NEW>

s as in the old version, execute:<CollectorInstanceName>

dtcollector -service install -instance <CollectorInstanceName>

Upgrade and Migration Guide

Dynatrace 6.2        15

*NIX: In , for each Collectorinstance, there will be an old startup script named /etc/init.d

, where < is a number. For each such file:dynaTraceCollector<NN> NN>

Take note of the values for the variables and DT_OPTARGS .DT_INSTANCE

Replace it with the new version: cp <DT_HOME_NEW>/init.d/dynaTraceCollector /etc/init.d/dynaTraceCollector<NN>.

Edit / etc/init.d/dynaTraceCollector and fill in the noted values for and <NN> DT_OPTARGS

.DT_INSTANCE

2.5 Auto-Start New ServicesOnly *NIX: With or , make sure that the new Server , Collector s, Memory chkconfig update-rc.d

Analysis Server, and Frontend Server are started automatically with shell scripts and /etc/init.d

that the permissions are correct.

2.6 Client MigrationIf you have any special settings in the Dynatrace Client s, such as proxy settings, compare the

in and as well as:dtclient.ini <DT_HOME_OLD> <DT_HOME_NEW>,

Windows: C:\Users\<username>\.dynaTrace\dynaTrace 6.2 \

*NIX: ~/.dynaTrace/dynaTrace 6.2 /

Carry over the properties that still apply.

2.7 Copy Session StorageIf you want to migrate your session storage and (by default, used a folder inside <DT_HOME_OLD>

sessions are stored in ), copy the files to the same <DT_HOME_OLD>/server/sessions/stored

relative path in .<DT_HOME_NEW>

In larger installations you will have a separate spindle for a possibly huge (TBs) session store. If you are not able to copy it, you can later on ( ) point the new Configure Session Storage (see page 17)installation to the old location. (It's backward compatible.)If you need / want to roll back you will need a backup or at least delete newly written session folders as the old version cannot be forward compatible.

Upgrade and Migration Guide

16        Dynatrace 6.2

1.

2.

3.

2.8 Start the New Server componentsIf you configured a environment variable, update it to , and then start the DT_HOME <DT_HOME_NEW>

Dynatrace Server and Frontend Server .

2.9 Start the New ClientStart the Client to access your Server settings. For the standalone Client :

On Windows go to .Start menu > Dynatrace > Dynatrace 6.2 > Dynatrace Client

On *NIX execute from < .dtclient DT_HOME_NEW>

Webstart Client

For convenience (locally or remotely), you can use the Webstart Client (features automatic installation) through the Server's browser interface: . For http://localhost:8020

Webstart Client requirements see the . Replace with your Server's release notes localhost

name. Initial user name/password are admin/admin.

On non-local installations, with the standalone Client, be sure to connect to the right Dynatrace Server through the pane. You may need to configure Settings > Dynatrace Server > Connectivitya proxy. With the Webstart Client you are bound to the one Server you named in the URL.

If you want to connect to your old Server, then keep the existing Client or go through the Webstart Client.

2.10 Activate Licenses for the New ServerIf you require a proxy server to access the Internet, manually configure the Client proxy settings to

.access the online licensing eServices site

To import the Server and UEM licenses:

In the pane, click . Settings > Dynatrace Server > License Import

Enter login credentials or select the license file.

Select the license to install and review how many Agents from each technology are included in the license.

Upgrade and Migration Guide

Dynatrace 6.2        17

2.11 Select Server SizingAfter the license import, you will be presented with different sizing options (see for Sizing Settingsmore details). Select the Sizing that you identified during the Preparations. It is important to perform this step , to avoid Out-of-Memory problems.before starting the new Collectors

2.12 Apply Update to New DynatraceCheck the if there is an update (formerly FixPack) available for Dynatrace 6.2 , downpage pageapply it to the Server now while you are in the migration process to avoid unnecessary restarts of Dynatrace components and your applications. See for more information.Updates

The Server will automatically pass on the update to Collectors and Agents.

2.13 Connect the Performance WarehouseIn , verify the connection details and Settings > Dynatrace Server > Performance Warehouse enter your database credentials to connect to the old database.

MS SQL Server: If you use Windows authentication you must add two settings to and, as of 6.2, also to . <DT_HOME>\dtserver.ini <DT_HOME>\dtfrontendserver.ini See

.this KB for how-to

Click and, if the DB connection is OK, click .Test Connect

The Server updates schema and data automatically to the new version. This may take up to five minutes.

2.14 Configure Session StorageIf you want to migrate your stored sessions, in verify that Settings > Dynatrace Server > Storagethe directory points to your session storage data.

Upgrade and Migration Guide

18        Dynatrace 6.2

2.15 Start New CollectorsStart the new Collectors, then go to the pane and verify Settings > dynaTrace Server > Collectorsthat all Collector s are connected to the Server . If you applied an update (to the new Server), you should immediately restart the Collector s from this dialog box for the update to be applied.

The Dynatrace Server and Collector will now accept Agent connections.

Next: Upgrade Agents (see page 25)

2.16 dtmigration Tool DetailsOverview (see page 19)

dtmigration Usage (see page 19)

dtmigration Examples (see page 21)

Upgrade / Migrate in One Step (see page 21)

Create Upgrade / Migration / Backup Archive Only (see page 21)

Choose What Default and / or Additional Server and Collector Instances to Upgrade / Migrate (from Archive) (see page 21)

Upgrade / Migrate All (Default Behavior without Option) (see page 21)

Upgrade / Migrate Default Server and Collector Instance Only (see page 21)

Upgrade / Migrate Default Server Instance (see page 22)

Upgrade / Migrate Default Collector Instance (see page 22)

Upgrade / Migrate Additional Instances Only (Not Default Server and Collector) (see page 22)

Upgrade / Migrate Additional Server Instances (Not Default Server) (see page 22)

Upgrade / Migrate Additional Collector Instances (Not Default Collector) (see page 22)

Upgrade / Migrate and Define Alternative Migration Backup Directory: (see page 22)

Undo Last Migration Step (see page 22)

Upgrade and Migration Guide

Dynatrace 6.2        19

2.16.1 Overviewdtmigration is a command line tool to

backup (configuration) data or to

migrate those data from the currently used to a new Dynatrace version.

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)

To take care of changes in newer releases, you should always download the latest version of the , which is released out-of-band / when the need arises! Tool 6.3.0.1073dTMigration

See to 6.2 for the typical application example.Upgrade and Migration (see page 5)

2.16.2 dtmigration UsageIf is called without command line parameters its usage is displayed:dtmigration

Upgrade and Migration Guide

20        Dynatrace 6.2

> java -jar dtmigration.jar-------------------------------------------------------------------------------

Dynatrace Migration Tool

Copyright (C) 2004-2015 Dynatrace

-------------------------------------------------------------------------------

Version 6.2.0.1184 built Tue Sep 01 16:03:08 CEST 2015

JRE: Oracle Corporation 1.8.0_45 64bit on Windows 8.1 v6.3 amd64

USAGE:

dtmigration -migration [{<option>}]

Where <option> includes:

-sourceDTHome <directory> [noclasscache]

Dynatrace installation directory to migrate from

Mutually exclusive with sourceArchive! Either use installation

or zip as source.

noclasscache

If present the class cache folder will not be zipped up. (normally

only megabytes, but could be gigabytes)

-sourceArchive <archivepath>

archive containing items to be migrated

Mutually exclusive with sourceDTHome! Either use installation or

zip as source.

[-targetArchiveDir <directory>]

Optional: target directory for archive containing items to be

migrated. If not present the archive will be created in migration

folder of targetDTHome.

If option targetDTHome isn't present too, the archive will be

created in the current directory.

[-targetDTHome <directory> [-migrateInstances <instanceoption>]]

Dynatrace installation to migrate to.

Without the targetDTHome option just an archive will be created.

No migration will be done.

-migrateInstances <instanceoption>

Without -migrateInstances:

All default and additional Dynatrace Server and Collector

instances will be migrated.

With <instanceoption> ... will be migrated:

default: only the default Dynatrace Server and Collector instance

defaultServer: only the default Dynatrace Server instance

defaultCollector: only the default Dynatrace Collector instance

instances: only Dynatrace Server and Collector instances

ServerInstances: only Dynatrace Server instances

CollectorInstances: only Dynatrace Collector instances

-makeServerInstanceDefault <instancename>

EXPERIMENTAL Convert server instance to default instance

-makeCollectorInstanceDefault <instancename>

EXPERIMENTAL Convert collector instance to default instance

[-backupDir <directory>]

Optional: backup directory for files replaced during migration and

to log migration steps and status

If not present the backup directory is

targetDTHome/migration/backup.

-silent execute command without prompt.

-skipDTHomeCheck if you want to migrate files from or/and to a

directory that's not a Dynatrace installation

directory.

-config <customconfig> overwrite default migration config by providing a

custom contig file.

Mutually exclusive with

[-migrateInstances <instanceoption>]]!

dtmigration -undomigration [{<option>}]

Where <option> includes:

-targetDTHome <directory>

Dynatrace home directory for which you want to

revert the last migration step

-silent execute command without prompt.

-ignoreSpace ignores required free space calculations

-dropInvalidFilenames drops files with invalid filesnames

-ignoreNoReadAccess ignore missing read access on sourceDTHome

Upgrade and Migration Guide

Dynatrace 6.2        21

2.16.3 dtmigration ExamplesHere are some usage examples beyond the basic one- or two-step procedures in Upgrade and

:Migration (Using Tool)dtmigration (see page 5)

Upgrade / Migrate in One StepYou can migrate using a single command if you can access the file systems of both old and new installations at the same time. Supply and for this process, default 64-sourceDTHome targetDTHome

bit Dynatrace installation on Windows example:

java -jar dtmigration.jar -migration -sourceDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -targetDTHome "C:\Program Files\dynaTrace\dynaTrace

6.2"

Create Upgrade / Migration / Backup Archive OnlyUse the command below to back up your configuration data into a zip archive (extension )..dtma

Use the archive in a second step to restore those (configuration) data to a new Dynatrace installation.If Collectors are distributed you may want to run this with their sourceDTHome (in addition to the Server's) as well.

java -jar dtmigration.jar -migration -sourceDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -targetArchiveDir "c:\migration"

Choose What Default and / or Additional Server and Collector Instances to Upgrade / Migrate (from Archive)Upgrade / Migrate All (Default Behavior without Option)

Upgrade / migrate all default and additional dynaTrace Server and Collector instances from archive:

java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2"

Upgrade / Migrate Default Server and Collector Instance Only

java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -migrateInstances default

Upgrade and Migration Guide

22        Dynatrace 6.2

Upgrade / Migrate Default Server Instance

java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -migrateInstances defaultServer

Upgrade / Migrate Default Collector Instance

java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -migrateInstances defaultCollector

Upgrade / Migrate Additional Instances Only (Not Default Server and Collector)

java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -migrateInstances instances

Upgrade / Migrate Additional Server Instances (Not Default Server)

java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -migrateInstances ServerInstances

Upgrade / Migrate Additional Collector Instances (Not Default Collector)

java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -migrateInstances CollectorInstances

Upgrade / Migrate and Define Alternative Migration Backup Directory:java -jar dtmigration.jar -migration -sourceArchive "C:

\migration\mymachine_<date>_<time>.dtma" -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2" -backupDir "D:\migrationBackup"

Undo Last Migration Stepjava -jar dtmigration.jar -undomigration -targetDTHome "C:\Program

Files\dynaTrace\dynaTrace 6.2"

2.17 Manual File MigrationThis is an informational overview of the files or directories that are migrated by You dtmigration.

should not require this information unless you cannot use dtmigration.

Files that didn't yet exist in the following directories:

Upgrade and Migration Guide

Dynatrace 6.2        23

System Profiles and Dashboards in and server\conf\profiles\*.profile.xml

, respectively, and server\conf\dashboards\*.dashboard.xml collector\conf\profiles\*.

profile.xml.

Files for user-defined items:

Sensor packs in and .server\conf\sensors\plugins collector\conf\sensors\plugins

Typically, directories starting with are generic Sensors and are already com.Dynatrace

present in your new Dynatrace installation directory.

User plugins in (custom Monitors, Metrics, or Action plugins) and server\conf\plugins

.collector\conf\plugins

All out-of-the-box plugins already present after installation, so there is no need to copy them.Only downloaded additional plugins or customized plugin implementations needed to be copied.

Files for WebUI User dashboards: andserver\conf\dashboards\web\custom\*\*.xml

server\conf\dashboards\web\custom\*\*.json

in server\conf\:The following files (if present)

server.config.xml

frontendServer.config.xml

userproperties.xml

user.permissions.xml

ipmappings.xml

cmdb.config.xml

sensororders.xml

mqmappings.xml

availabiltycenter.xml

realtimemappingcenter.xml

cas.uem.normalizer.cfg.xml

licensereservations.xml

from collector\conf:

collector.config.xml

Upgrade and Migration Guide

24        Dynatrace 6.2

and from collector\lib, those files starting with "agentres-" that are not yet present at the target installation.

All files of the following directories (if using the switch, thus migrating the class -classcache

:cache)

Inheritance Maps ( ) and Class Cache in and/or , *.imap server\cache\ collector\cache

depending on the dtmigration switch.-migrateInstances

In 5.5, the Collector class cache format changed. If you copy the class caches, the Collector start will take a bit longer due to the format conversion. If the conversion takes much longer than one minute per GB, please contact and keep the old cache and log.supportOtherwise (empty, new version class cache), an Agent restart is necessary.

Upgrade and Migration Guide

Dynatrace 6.2        25

3 Upgrade Agents

3.1 Upgrade Agents

Note: When you restart your applications, they will be instrumented with the new Agents. Until then, the old Agents will try to connect to the running Collector / Server. Review the

especially if you restart considerations detailed in the Compatibility Matrix, (see page 9)upgrade from < 5.0.

3.1.1 Bootstrapped Agents (Java, .NET, Host, Native ADK, Web Server, PHP, CICS, and IMS)In general, bootstrapped Agents upgrade automatically when restarted, unless you upgrade from:

< 5.0: Manually upgrade Agents that use the Native ADK. For details, see the ADK .documentation

5.0: Manually upgrade (reinstall) the Host Agent if you want to be able to restart Host Agents from the Client.

If you are upgrading from < 6.0 and want to use the , you have to Controlled Update Rolloutreinstall the Agents to .upgrade their bootstrap component (see page 27)

If you have bootstrapped Agent s running on the same host that you are upgrading, they will upgrade, but will directory for retrieving their configuration. continue to use the <DT_HOME_OLD>

Therefore, migrate their configuration manually to (installation of new version) or <DT_HOME_NEW>

continue to use for their configuration. See the individual for <DT_HOME_OLD> Agent Configurationsdetails.

Upgrade and Migration Guide

26        Dynatrace 6.2

Bootstrapped Web Server AgentsIt is necessary that you restart the Web Server Agent Service and the Web Server Agent in the correct order. First restart the Web Server Agent Service and wait until it has reconnected. Then restart the Web Server Agent. This order is necessary to get both Agents updated to the correct version. For old Unix installations where the Apache Web Server automatically starts the Web Server Agent Service a second restart of the Apache Web Server might be needed.

If you want to be able to restart the Webserver Service from the Client then you also have to Agent .upgrade the bootstrap (see page 27)

NGINX Web Server Agent

As of 6.2, the JSON offset file contains more data than in 6.1. If the NGINX binary contains debug symbols, it is enough to rename the JSON file and it will be regenerated automatically by the Agent at startup. If a stripped NGINX binary is used, however, the offset file needs to be regenerated manually before the NGINX is restarted, otherwise the upgraded will not start.Agent Agent

Rename the offset file and run the following command:

<dynatrace_root>/agent/conf/ngx_offset_gen.sh <nginx binary> <nginx debug symbols file> <JSON offset file>

3.1.2 Non-bootstrapped Agents Needing Manual Update (Browser and Mobile App ADK)Find the new Browser- Agent installer and the new ADK release .here

Download and apply the new Agent -only installer to upgrade to the new Browser- Agent.

In your Mobile App development environment, switch to the new ADK and deploy the new version to upgrade.

3.1.3 z/OS Agents.They can be bootstrapped or non-bootstrapped. Refer to Upgrading zOS Agents (see page 28)

3.2 Restart AgentsUnless you already upgraded and restarted them manually, perform a restart of all your

to upgrade their Agent s.instrumented applications now

Next: Final Checks (see page 31)

Upgrade and Migration Guide

Dynatrace 6.2        27

1.

2.

3.

1.

2.

3.

1.

2.

3.

1.

2.

1.

3.3 Upgrading Bootstrap AgentsDynatrace is de-supporting bootstrap agents < 6.0 with version 7.0. Use this guide to upgrade your pre-6.0 bootstrap agents to the newest version.

3.3.1 PreparationDownload a new agent installer for your platform from downloads.dynatrace.com

Consider a backup of your current agent configuration directory

Deploy and install it on your target platforms next your agents installation which is currently in use.

3.3.2 Bootstrap agent upgrade processHost Agent

Stop the old host agent

migrate the content in /conf/dthostagent.ini (mainly the name and the server) from your old to your new installation directoy.

Start the new host agent.

Webserver Agent

Stop the old web server agent

migrate your webserver agent settings in conf/dtwsagent.ini from your old to your new installation directory

Start the new web server agent

Java Agent

Reconfigure the path to the agent in you local application configuration (e.g. from -agentpath:/opt/dynatrace-5.6.0/agent/lib64/libdtagent.so=name=Application_Monitoring to -agentpath:/opt/dynatrace-6.2/agent/lib64/libdtagent.so=name=Application_Monitoring)

Restart your application

.NET Agent

Restart your application after installing the new agents.

Upgrade and Migration Guide

28        Dynatrace 6.2

1.

zOS zLocal / zRemote agent

Upgrading the zLocal / zRemote agents will automatically upgrade the bootstrap agents. Please follow the instructions here

3.3.3 Uninstall the outdated agentsLinux: simply delete the installation directory of the outdated agents

Windows. Uninstall outdated agents using Add / Remove programs.

.

3.4 Upgrading zOS Agents

3.4.1 Prerequisites

Upgrade of Dynatrace Servers, Collectors, Agents and Performance WarehouseBefore starting any migration action for your z/OS Agents, read the general Upgrade (see page 5)to 6.2 guide and create a detailed plan for the upgrade of your Dynatrace Servers, Collectors, other Agents, and the Performance Warehouse and other components. For less maintenance overhead coordinate these upgrades to coincide with application restarts.

Important

As of Dynatrace 6.2, the z/OS Agent can no longer directly connect to a Dynatrace Collector without first going through a zRemote Agent. Using the zRemote Agent reduces CPU consumption on z/OS. If your current pre-6.2 z/OS Agent deployment omitted the zRemote Agent, you will need to install it as a part of your upgrade. For more information, see

.zRemote Agent

LicenseYou need valid licenses for the Dynatrace Server the z/OS Agents. See for and License Upgrademore information. The license for the z/OS Agent is MIPS-based. See Prepare to Upgrade (see page

and for more information.6) License Upgrade

The z/OS license is valid for any Dynatrace Edition (Pre-Production / Test Center or Production). If the hardware ("fingerprint") changes (for example, if a CPU is added), the envelope normally becomes invalid and must be renewed within a 14-day grace period.

Upgrade and Migration Guide

Dynatrace 6.2        29

1.

2.

3.

a.

b.

3.4.2 Upgrade ProcedureUpgrade the Dynatrace Server and Collector as described in to Upgrade (see page 5)version 6.2 prior to upgrading the mainframe components. While newer zOS Agents are generally not compatible with older Dynatrace Collectors or Servers, newer Dynatrace Collectors or Servers usually work with older zOS Agents.

Follow the standard Agent installation process. This consists of running the JCL to download the agent distribution file and running SMP/E to populate the target datasets for the new release. For more information, see .Downloading the Mainframe z/OS Agent Components

From step 2, you can do either (a) or (b):

Stop your current zDC and update the zDC authorized libraries to the version 6.2. Before you restart the z/DC, you should ensure that the zDC parm has DTMSG_SMOSIZE

been uncommented and that parm has been deleted. These parameters DTMSG_QSIZE

control whether messages are queued in the zDC dataspace or in the zDC 64-bit shared memory object (SMO) pending their writing to the Dynatrace Agent.As of release 5.6, use of dataspaces has been deprecated. If you customize the ZDCSYSIN sample contained in the 5.6 version, you can skip this step because the sample already incorporates this change. After the zDC has been started, the CICS and IMS agents should register within 5 minutes. - OR -

Create a parallel 6.2 environment for the zDC and zLocal (formerly USS) Agent. Follow the directions as described in . With a parallel 6.2 environment, you Installing the zDCcan continue running the old z/DC while you migrate individual CICS regions and IMS control regions over to the new zDC, or you can test with a few regions prior to upgrading the default zDC. If multiple zDCs are running, the one that specifies DEFAULT(YES) will be chosen unless an INITPARM parameter in the CICS or IMS system initialization parameters specifies that it must connect to a zDC with a particular name: INITPARM=(ZDTPLT6x='xxxx').

Note

There can be only one zDC per LPAR with the DEFAULT(YES) option.

The SUBSYSTEM_ID must be unique to each zDC.

The library used in the zDC STEPLIB must be authorized.

Upgrade and Migration Guide

30        Dynatrace 6.2

4.

5.

a.

b.

The bootstrap Agent automatically upgrades the zLocal Agent when it first connects to an upgraded Dynatrace Collector / Server. If you use the non-bootstrap version of the z/OS UNIX Agent, you must run COPYAGNT to copy the new version to the location in the z/OS UNIX filesystem where it executes. See the COPYAGNT step in .Installing the zDC

Because the Dynatrace new version zDC is compatible with older CICS and IMS Agents, you do not need to upgrade all CICS regions and IMS control regions at once. However, if you monitor transactions cross CICS regions or IMS control regions, those related regions should be at the same Agent version otherwise incomplete PurePaths will result. Consequently, upgrading CICS regions and IMS control regions should be done with consideration to application groupings. Plan on upgrading all of your CICS regions and IMS control regions as soon as possible to take advantage of the features that come with the new Dynatrace version.

To upgrade your CICS regions, replace the DFHRPL concatenation of the old PDS (or its contents) with the new PDS (or its contents).

// DD DISP=SHR,DSN=<hlq>.LZDT6 20.SZDTLOAD

To upgrade your IMS control regions, replace the STEPLIB PDS (or its contents) in the JCL that executes the IMS Agent injection program, ZDTIINST, with the new PDS (or its contents).

// DD DISP=SHR,DSN=<hlq>.LZDT6 20.SZDTAUTH

Note

The library used in the STEPLIB must be authorized.

Please refer to for the Dynatrace component compatibility table.Migration Troubleshooting

Upgrade and Migration Guide

Dynatrace 6.2        31

4 Final Checks

4.1 Confirm Operation of the New Dynatrace ServerTo ensure your new Server operates correctly, verify the following:

All Agent s displayed in :Cockpits > Status Overview > Agent Overview

Are connected

Have data coming in: scroll over horizontally to verify that or Event Count Class Load (or both) changeCount

Have the correct Agent version (6.2) and Update version if one was installed.

PurePaths come in.

Dashboards are properly displayed.

Historical data is present if you migrated the Session Storage.

If the Client cannot connect, verify that the new Frontend Server is started, especially on Windows, where it is started separately from the Dynatrace Server.

4.2 Check Configuration

4.2.1 Check Mobile Error Detection RulesGo to and verify the condition strings. In System Profile > Error Detection > Mobile Error Rulesversions before 5.6, special characters (such as spaces) were automatically replaced with underscores Starting with 5.6, they are handled correctly and allow special characters..

4.2.2 Apply Customizations Not Covered By AutomationIncident Rules and Downtimes

You need to redefine all and the of the Self-Monitoring System Profile.Downtimes incident rules

Upgrade and Migration Guide

32        Dynatrace 6.2

Reapply Modifications to Built-In Items: Sensor Packs

dtmigration does not migrate items that are delivered and installed with the product, such as built-in Sensor Packs. Because these may change between releases, you should not simply export or import them, but reapply edits.

Check user plugins

In the Dynatrace Client: , check whether all plugins were migrated, if Settings > Dynatrace Servernecessary re-install them.

Reimport custom certificates

If an additional certificate (e.g. CA or self-signed certificate for LDAP) was imported to the Dynatrace keystore:

server/conf/jssecacerts

re-import the certificate to the new keystore. Avoid copying the old keystores, to avoid security holes through potentially compromised public certificates.

In the case of an LDAP certificate, you can also re-import the previous certificate by logging on with a Dynatrace local user and click in the Dynatrace Client : Settings > Dynatrace Server > Users > LDAP > Test Connection.

Congratulations!

Migration successful!

Upgrade and Migration Guide

Dynatrace 6.2        33

5 Troubleshooting

5.1 Frequently Asked Questions/IssuesWhat Agent version will run?

After the Server/Collector upgrade, the Agent bootstrap part upgrades the actual Agent, but the old version Agents will run until you restart your applications.

Please have a restart plan/coordination for the tiers of an app.

You can find the Agent version (bootstrap and active part) information in Cockpits > Agent .Overview

What version is my Performance Warehouse DB schema at?

When you connect the new Dynatrace Server to the old Performance Warehouse DB, the Dynatrace DB schema is updated. As a result, if you are not sure about the version, it's a good idea to check before connecting to it.

For SQL Server, for example:

SELECT * FROM dynatrace6 2.dbo.version;

Is the Performance Warehouse DB schema backward compatible?

No. Please use your DB backup to go back.

PurePaths are missing after upgrade.

If you upgraded without migrating the class cache and are missing PurePaths or have PurePaths that contains nodes, try to restart the instrumented applications. restarts of the <unknown> Twoinstrumented applications are required to avoid this problem

Why are the memory settings in dtserver.ini and dtfrontendserver.ini ignored and even removed?

Starting with Dynatrace 6.0, ' ' and ' ' VM arguments are ignored. Please select an -Xmx -Xms

appropriate sizing in . For more details, see Settings > Dynatrace Server > Settings pane > Sizing.Sizing Settings

Upgrade and Migration Guide

34        Dynatrace 6.2

5.2 DynaTrace SupportIf you need further assistance, go to our support page.

Upgrade and Migration Guide

Dynatrace 6.2        35

Index

BBootstrapped Agent 25

DDtmigration 11

NNon Oem , , , , , , , , , 5 6 9 11 18 22 25 28 31 33

UUpgrade 6

Upgrade Agents 25

Upgrade License 11

Upgrade Prerequisites 6

Upgrade Servers 11

Upgrade Verify 31