DynaTrace Diagnostics User Guide

dynaTrace Diagnostics User Guide

dynaTrace software GmbH Freistädterstr. 313 A-4040 Linz Tel.: +43 (0) 732 246870.14 Email: [email protected]

Table of Contents 1. Introduction ............................................................................................................................. 4 2. Legal ....................................................................................................................................... 5 3. Release Notes ........................................................................................................................ 7 4. Installation ............................................................................................................................... 8

4.1. System Requirements.................................................................................................... 9 4.2. Firewall Configuration .................................................................................................. 10 4.3. Diagnostics Server Configuration................................................................................. 12 4.4. Diagnostics Client Configuration .................................................................................. 15 4.5. Test Configuration ........................................................................................................ 16 4.6. Diagnostics Agent Configuration.................................................................................. 19

4.6.1. Diagnostics Agent Configuration for Java ........................................................... 19 4.6.2. Diagnostics Agent Configuration for .NET........................................................... 23

4.7. Application Integration.................................................................................................. 25 4.7.1. JBoss ................................................................................................................... 26 4.7.2. WebLogic............................................................................................................. 32 4.7.3. WebSphere.......................................................................................................... 37 4.7.4. Oracle .................................................................................................................. 45 4.7.5. SAP NetWeaver .................................................................................................. 48 4.7.6. Other Application Servers.................................................................................... 49 4.7.7. Java Applications................................................................................................. 50 4.7.8. Windows Services ............................................................................................... 53 4.7.9. Java Applets ........................................................................................................ 55 4.7.10. ATG Dynamo....................................................................................................... 60 4.7.11. Apache Tomcat ................................................................................................... 65

5. Administration ....................................................................................................................... 72 5.1. Server Administration................................................................................................... 72 5.2. Client Administration .................................................................................................... 76 5.3. Configure Diagnostics Server ...................................................................................... 76

5.3.1. Diagnostics Repository........................................................................................ 77 6. Configure............................................................................................................................... 82

6.1. System Profile .............................................................................................................. 82 6.2. Add System .................................................................................................................. 84 6.3. System Profile Properties............................................................................................. 86

6.3.1. General ................................................................................................................ 87 6.3.2. Configuration ....................................................................................................... 88 6.3.3. All Agents............................................................................................................. 98 6.3.4. Add an Agent to a System Profile ..................................................................... 101

6.4. Overhead.................................................................................................................... 120 6.4.1. Discovery Run ................................................................................................... 121 6.4.2. Diagnostics Server Health Status...................................................................... 122

6.5. System View............................................................................................................... 122 6.6. Hot Update ................................................................................................................. 128 6.7. Immediate Configuration ............................................................................................ 128 6.8. Configuration Matrix ................................................................................................... 129

7. Monitoring, Business Transactions, Incidents .................................................................... 132 7.1. Measure Configuration............................................................................................... 132 7.2. Business Transaction Configuration .......................................................................... 160 7.3. Incidents ..................................................................................................................... 163 7.4. Integration of 3rd Party Monitoring Tools................................................................... 169

8. Charts.................................................................................................................................. 170 8.1. Create a new Chart .................................................................................................... 171 8.2. Add Series Configuration ........................................................................................... 172

9. Sessions.............................................................................................................................. 176

9.1. Session Management ................................................................................................ 178 10. Diagnose Performance................................................................................................... 183

10.1. Business Transactions........................................................................................... 186 10.2. API Breakdown ...................................................................................................... 188 10.3. PurePaths .............................................................................................................. 190 10.4. Web Request ......................................................................................................... 196 10.5. Database................................................................................................................ 199 10.6. Remoting................................................................................................................ 201 10.7. Web Services......................................................................................................... 203 10.8. Components........................................................................................................... 204 10.9. Naming Services.................................................................................................... 207 10.10. Messaging Services............................................................................................... 208 10.11. Methods ................................................................................................................. 210 10.12. Memory Allocations................................................................................................ 211 10.13. Synchronization ..................................................................................................... 212 10.14. Custom Entry Points .............................................................................................. 214 10.15. Tagged Web Requests .......................................................................................... 216

11. Diagnose Events ............................................................................................................ 218 11.1. Exception ............................................................................................................... 220 11.2. Logging .................................................................................................................. 222 11.3. Notification ............................................................................................................. 224

12. Diagnose Runtime .......................................................................................................... 227 12.1. Thread.................................................................................................................... 229 12.2. Total Memory ......................................................................................................... 231 12.3. Selective Memory .................................................................................................. 234

13. Reporting ........................................................................................................................ 236 14. Management and Integration.......................................................................................... 240

14.1. Load Testing and Monitoring Integration ............................................................... 240 14.2. SilkPerformer Integration ....................................................................................... 240 14.3. LoadRunner Integration ......................................................................................... 242 14.4. Integration of other Load Testing and Monitoring Tools ........................................ 244 14.5. JMX Management.................................................................................................. 245 14.6. Command Line Tool............................................................................................... 247

15. Shortcut Reference Table............................................................................................... 250 16. FAQ/Troubleshooting ..................................................................................................... 252

1. Introduction

Diagnosing performance issues and application failures within distributed, heterogeneous J2EE and .NET systems can be challenging. Frequently, performance problems only occur when applications are run under load. The lack of effective root-cause analysis tools can make diagnosis difficult. Ideal diagnosis includes metrics and correlations that enable the identification of not just non-performing applications, but also of specific components, objects, and methods in which performance bottlenecks occur.

Today, root-cause analysis depends substantially on the developer´s familiarity with their source code. Today´s tools, which primarily include profilers and system monitoring tools, are not integrated (and can not be integrated), and therefore leave the important process of identifying the root causes of performance issues up to trial and error. Profilers are not useful during load testing or production monitoring because the significant overhead they introduce (up to 100,000%) affects performance of the application enough to negate their value. Additionally, system monitoring tools do not provide the metric granularity for drilling down to the method level, which is required to improve root cause analysis enough to make the IT independent of developers.

dynaTrace Diagnostics is a tool which offers the possibility to clearly reconstruct critical business transactions, from the end-user perspective, down to the source-code level, and beyond (JVM, CLR). With the help of PurePath ™ technology, transactions are followed beyond system borders, process borders, and application domains, enabling diagnosis of the dynamic behavior of your applications. dynaTrace Diagnostics subsequently recognizes heterogeneous Java SE/EE and .NET applications automatically and instruments important application components from different manufacturers with pre-configured Sensor Packs. Even data exchange between a client and server, and between multiple servers and other technologies, is no problem.

Furthermore, dynaTrace Diagnostics collects method-level metrics that can easily be correlated to the PurePaths. Collected metrics are analyzed by dynaTrace Diagnostics using innovative analysis and correlation techniques to provide root cause analysis. Visually rendered metrics enable quality engineers, system operators, performance analysts, and developers to tune performance and detect failures from the end-user perspective.

2. Legal

Copyright Notice

All dynaTrace documentation and training materials are copyrighted, and all rights are reserved. Neither the software nor any accompanying documentation may be reproduced, translated, or reduced to any electronic or printed form without the prior consent of dynaTrace software, GmbH, except as authorized in the terms of a valid license agreement.

Copyright (C) 2004-2007 dynaTrace software GmbH.

All Rights Reserved. Printed in Austria, April 2005.

Trademarks

dynaTrace and dynaTrace Diagnostics are trademarks or registered trademarks of dynaTrace software, GmbH.

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

Warranties and Disclaimers

This publication is provided "as is" without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. dynaTrace assumes no responsibility for errors or omissions in this publication or other documents which are referenced in or linked to this publication. This publication could include technical or other inaccuracies or typographical errors. Changes are periodically added and will be incorporated in new editions of the publication. dynaTrace may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time.

Should you or any viewer of this publication respond with information, feedback, data, questions, comments, suggestions or the like regarding the content of any dynaTrace publication, any such response shall be deemed not to be confidential and dynaTrace shall be free to reproduce, use, disclose and distribute the response to others without limitation. You agree that dynaTrace shall be free to use any ideas, concepts or techniques contained in your response for any purpose whatsoever including, but not limited to, developing, manufacturing and marketing products incorporating such ideas, concepts or techniques. This publication is distributed internationally and may contain references to dynaTrace products, services, and programs that have not been announced in your country. These references do not imply that dynaTrace intends to announce such products, services or programs in your country.

Questions or Comments

If you have any questions for our technical support staff, please phone +43 (0) 732 246870.14 (International). When you get in touch, please have your customer ID number available. If you have any questions about the documentation, please contact us at [email protected] .

3. Release Notes

We always want to provide you with the latest available information. Therefore the Release Notes are no longer part of this document and have been moved to our website. http://www.dynatrace.com/downloads/ReleaseNotes.aspx

4. Installation

dynaTrace Diagnostics is an introspection tool that enables low overhead introspection of J2EE applications under load to facilitate root cause analysis of performance issues during testing and production monitoring.

dynaTrace Diagnostics options are primarily located at the Diagnostics Server, including options for Diagnostics Server and Diagnostics Agent. This reduces the effort of deploying Diagnostics Agents for injection. The following paragraphs provide a dynaTrace Diagnostics configuration reference.

Key Components

Implementations of dynaTrace Diagnostics consists of the Diagnostics Agent (1), the Diagnostics Client (2), the Diagnostics Server (3), and an optional Diagnostics Repository (4).

Software Requirements

Diagnostics Agent

• Windows 32/64, Linux 32/64, Solaris 32/64, AIX 32/64 Power 5 Architecture, zOS 32/64, zLinux 32/64

• Sun JVM, IBM JVM, JRockit JVM • 25MB disk space

Diagnostics Server and Diagnostics Repository

• Windows, Linux • J2SE 5.0 (private JRE shipped with product) • 1GB disk space, 1GB memory

Diagnostics Client

• Windows, Linux IA32 GTK • 100MB disk space • 512MB memory

Supported Java Virtual Machines

A list of tested and certified Java Virtual Machines can be found in the release notes located at: http://www.dynatrace.com/downloads/ReleaseNotes.aspx

Tested Application Servers

dynaTrace Diagnostics supports all types of J2EE application servers and J2SE applications. For a list of tested and certified application servers see http://www.dynatrace.com/downloads/ReleaseNotes.aspx

4.1. System Requirements

Diagnostics Client Requirements

Install the Diagnostics Client onto a Windows XP, 2000 or 2003 machine, or onto a Linux Machine (RedHat Enterprise, SuSe Enterprise) Memory requirements: 265MB minimum, 512MB recommended

Set the option -Xmx in the dtdclient.ini configuration file to a reasonable size.

-startup

bin/startup.jar

org.eclipse.core.launcher.Main

-vmargs

-Xmx512M

Diagnostics Server Requirements

Install the Diagnostics Server onto a Windows XP, 2000 or 2003 machine, or onto a Linux Machine (RedHat Enterprise, SuSe Enterprise) Memory requirements: 768 MB minimum, 1 GB recommended

Set the option -Xmx (the maximum heap size) and -XX:MaxPermSize (maximum size for the permanent generation heap) in the dtdserver.ini configuration file to a reasonable size.

For example, on a 2GB machine it´s recommended to set it to -Xmx1152M and -XX:MaxPermSize=256m

-startup

lib/dtdserver.jar

-console

-vmargs

-Xmx1152M

-Xms1152M

-XX:MaxPermSize=256m

-XX:PermSize=256m

-server

Set the −Xms and -Xmx options in the service.ini configuration file to a reasonable size.

For example, set -Xms768M and -Xmx768M . The initial heap size ( -Xms parameter) would be 768 MB and the maximum heap size ( -Xmx parameter) would be set to 768 MB of the Total Memory.

[Application]

Application Type=service

[Java Runtime Environment]

Maximum Version=any

Minimum Version=1.5

JVM Type=server

Main Class=com.dynatrace.diagnostics.server.Service

Virtual Machine Parameters=-Xms768M -Xmx768M -Duser .dir="C:\Program Files\dynaTrace

Diagnostics 2.0\" -XX:MaxPermSize=128m -XX:PermSize =128m

[Class Path]

Class Path=C:\Program Files\dynaTrace Diagnostics 2 .0\lib\dtdserver.jar;

4.2. Firewall Configuration

Many applications need to be deployed across firewalls. As a result, when analyzing the performance of these applications dynaTrace Diagnostics also needs to be deployed across the firewall. In these cases the firewall needs to be configured to facilitate the communication between the dynaTrace Diagnostics components. The following examples give an overview of

the 2 most common scenarios for configuring the dynaTrace Diagnostics software in environments using firewalls.

Case 1

In the first case (pictured below), the Diagnostics Agent and the Diagnostics Server are behind a firewall and the Diagnostics Client must communicate to the server across the firewall. The firewall has to be configured in a way that allows traffic to and from the Diagnostics Client to pass through. dynaTrace Diagnostics uses port 2020 (Port: 2020 is the default Diagnostics Client Listen Port) in both directions for communication between the Diagnostics Server and Diagnostics Clients. This enables dynaTrace Diagnostics to use TCP/IP or HTTP proxy tunneling.

Case 2

In the second case (pictured below), the Diagnostics Client and the Diagnostics Server are behind a firewall and the Diagnostics Agent communicates to the Diagnostics Server across the firewall using a TCP/IP connection. The firewall has to be configured in a way that allows traffic to and from the Diagnostics Agent to pass through. dynaTrace Diagnostics uses port 9998 (Port: 9998 is the default Diagnostics Agent Listen Port) in both directions for communication between the Diagnostics Server and Diagnostics Clients.

Change the Listening Ports

The default listening ports for communication between the Diagnostics Client and the Diagnostics Server can be changed via the Diagnostics Client. Set the listening port for the Diagnostics Client and the Diagnostics Server via right-click on the desired Diagnostics Server node in the cockpit tree and select "Preferences". To change the Diagnostics Client listening port choose the tab "Connectivity", and for Diagnostics Server the tab "Settings" and change the listen ports according to your environment. The default listening ports for communication between the Diagnostics Server and Diagnostics Agents are changed differently for each. The Diagnostics Server´s listening port can be changed as described above. For the Diagnostics Agent choose the tab "Settings" and change it´s listen port according to your environment. Alternatively the "Diagnostics Agent Listen Port" can be changed in the server.config.xml file. For the Diagnostics Agent the listening port is specified with the servername for the instrumentation. As shown below the server localhost:9999 specifies port 9999. Note: Changes in the port configuration force a restart of dynaTrace Diagnostics.

DTD_JAVAOPTIONS= -agentpath:dtdhome\lib\dtdagent.dll=name=HelloWorld ,server=localhost:9999

4.3. Diagnostics Server Configuration

Prerequisites

Install the Diagnostics Server onto a Windows XP, 2000 or 2003 machine, or onto a Linux Machine (RedHat Enterprise, SuSe Enterprise) Memory requirements: 512MB minimum, 1GB recommended

Set the options -Xmx , -Xms , -XX:MaxPermSize and -XX:PermSize in the dtdserver.ini

(see below) configuration file to a reasonable size. For example, on a 1GB machine it´s recommended to set it to -Xmx768M , -Xms768M , -XX:MaxPermSize=128m and -XX:PermSize=128m .

-startup

lib/dtdserver.jar

-console

-vmargs

-Xmx768M

-Xms768M

-XX:MaxPermSize=128m

-XX:PermSize=128m

-server

Set the option -Xmx in the service.ini configuration file to a reasonable size. For

example, set -Xms768M and -Xmx768M . The initial heap size ( -Xms parameter) would be 768 MB and the maximum heap size ( -Xmx parameter) would be set to 768 MB of the Total Memory.

[Application]

Application Type=service

[Java Runtime Environment]

Maximum Version=any

Minimum Version=1.5

JVM Type=server

Main Class=com.dynatrace.diagnostics.server.Service

Virtual Machine Parameters=-Xms768M -Xmx768M -Duser .dir="C:\Program Files\dynaTrace

Diagnostics 2.0\"

[Class Path]

Class Path=C:\Program Files\dynaTrace Diagnostics 2 .0\lib\dtdserver.jar;

Run the Diagnostics Server

Unix:

Invoke the Diagnostics Server on Unix with the command:

dynatrace-diagnostics-2.0# ./dtdserver

Windows:

Invoke the Diagnostics Server on Windows through the command line interface with the command:

dynaTrace Diagnostics 2.0> dtdserver.exe

Or start the Diagnostics Server through "Start" - "All Programs" - "dynaTrace Diagnostics 2.0" - "Diagnostics Server"

Manage the Diagnostics Server through Diagnostics Server Manager

The Diagnostics Server Manager includes features to start, restart and stop the Diagnostics Server. Additionally, the Diagnostics Server´s status is always visible through the Diagnostics Server Manager Task Bar icon. Moreover the Diagnostics Server statistics are apparent in the Diagnostics Server Manager GUI window. If you decide to control the Diagnostics Server

through Diagnostics Server Manager you do not need to start the server as described above. Start the Diagnostics Server as follows:

Unix:

Invoke the Diagnostics Server Manager on Unix with the command

dynatrace-diagnostics-2.0# ./dtdmanager

Invoke the Diagnostics Server through the GUI interface by clicking on the Server icon or right clicking on the icon and selecting the Start Server option

Windows:

Note: The Diagnostics Server Manager controls the dynaTrace Diagnostics Service, which will be installed with the Diagnostics Server Manager.

Invoke the Diagnostics Server Manager on Windows through the command line interface with the command:

dynaTrace Diagnostics 2.0> dtdmanager.exe

or start the Diagnostics Server Manager through "Start" - "All Programs" - "dynaTrace Diagnostics 2.0" - Diagnostics Server Manager. Invoke the Diagnostics Server through the GUI interface by clicking on the Server icon or right clicking on the icon and selecting the Start Server option.

Profiles and Version Control

Profiles

All the existing System Profile files (*.profile.xml) are stored in the profiles folder of the Diagnostics Server. For Unix OS it is the dynatrace-diagnostics-2.0/conf/profiles directory. For Windows OS it is the dynaTrace Diagnostics 2.0\conf\profiles directory.

The Diagnostics Server installation delivers following profile files:

• GoSpace.profile.xml • HelloWorld.profile.xml

If you create new profiles by using the Diagnostics Client, the resulting profile file will also be stored in the profiles -folder.

Version Control

The profiles are stored at the Diagnostics Server and can be added to and controlled by a version control system. All the advantages of a version control system can be applied to these end user edited files.

4.4. Diagnostics Client Configuration

Prerequisites

Install the Diagnostics Client onto a Windows XP, 2000 or 2003 machine, or onto a Linux Machine (RedHat Enterprise, SuSe Enterprise) Memory requirements: 256MB minimum, 512MB recommended

Set the option -Xmx in the dtdclient.ini (see below) configuration file to a reasonable

size.

-startup

bin/startup.jar

org.eclipse.core.launcher.Main

-vmargs

-Xmx512M

Run the Diagnostics Client

Unix:

Invoke the Diagnostics Client on Unix with the command:

dynatrace-diagnostics-2.0# ./dtdclient

Windows:

Invoke the Diagnostics Client on Windows through the command line interface with the command:

dynaTrace Diagnostics 2.0> dtdclient.exe

or start the Diagnostics Server through "Start" - "All Programs" - "dynaTrace Diagnostics 2.0" - "Diagnostics Client"

4.5. Test Configuration

Run the HelloWorld sample

Test the dynaTrace Diagnostics installation with the HelloWorld sample application: First start the Diagnostics Server directly or by using the Diagnostics Server Manager. Both executables can either be found in the installation folder or for Windows OS by clicking "Start" - "All Programs" - "dynaTrace Diagnostics 2.0" - "Diagnostics Server" or "Diagnostics Server Manager". If you prefer to use the Diagnostics Server Manager you can start the Diagnostics Server by clicking on the Diagnostics Server Manager icon or by right clicking on the Diagnostics Server Manager icon and select "Start Server". Afterwards start the Diagnostics Client, right-click on the "HelloWorld" System Profile and "activate" it. To apply this change to the Diagnostics Server right-click on the activated System Profile and select "Apply Changes". Start the HelloWorld Sample application as follows:

Unix:

runHelloWorld.sh

Windows:

runHelloWorld.cmd

The output of the HelloWorld sample application should look as follows. The output generated by the Diagnostics Agent is highlighted.

K:\dynaTrace Diagnostics>runHelloWorld.cmd

starting HelloWorld for J2SE 1.5

===============================

---executing HelloWorld sample application---

[native] ------------------------------------------ -------------------------------

[native] Diagnostics Agent Copyright (C) 2004-2007 dynaTrace software GmbH,

www.dynatrace.com

[native] ------------------------------------------ -------------------------------

[native] version 1.6.0.385, build date Jan 9 2006 1 2:29:59

[native] name=HelloWorld

[native] server=localhost:9998

[native] loglevel=info (mapped to ´info ´)

[native] logstdout=info (mapped to ´info ´)

[native] Agent´s .so/.dll file: C:/Program Files/dy naTrace Diagnostics

2.0/lib/dtdagent.dll

[native] Agent´s log file: C:/Program Files/dynaTra ce Diagnostics

2.0/lib/../log/dtd_HelloWorld.log

[native] Agent´s log file maximum chunk size: 20480 0 Byte (200 KibiByte)

[native] Connection retry delay: 60 seconds

[native] Network send/recv timeout: 30 seconds

[native] Java Hi-Res timer capabilities: maxvalue=6 148914691236517205, skipforward=no,

skipbackward=no

[native] High-resolution Java nanosecond timer dete cted.

[native] Trying to connect with server for up to 60 seconds

[native] Native agent registered with server.

[native] Agent class caching completed. Client - Se rver connection established

SUCCESSFULLY

[native] JVMTI based class load interception *ENABL ED*

[native] JVMTI VMStart event *REGISTERED*

[native] ------------------------------------------ -------------------------

[native] Agent classes loaded SUCCESSFULLY

[native] Properties set in bootstrap agent

[java] VM-RUNTIME: greater JDK14 and hotPlug, NO dt dagent.jar needed ...

[java] Attaching to library= ´C:/Program Files/dyna Trace Diagnostics

2.0/lib/dtdagent.dll´

This static string was passed to the HelloWorld con structor.

[java] version ....................... 1.6.0.385

[java] built ......................... Mon Jan 09 1 2:34:43 CET 2006

[java] tracemode ..................... Start paths for remote invocations (Remote)

[java] agentid ....................... 3

[java] processid...................... 2892

[java] advanced communication ........ enabled

[java] buffer saturation threshold ... 100%

[java] max. blocking time............. 5s

[java] capture ....................... enabled

[java] agent name .............,,,,,,, HelloWorld

[java] agent host .................... allen

[java] socket timeout ................ 30s

[java] reconnect delay ............... 60s

[java] hot update .................... enabled

[java] startup time .................. Mon Jan 09 1 3:46:50 CET 2006

[java] logging enabled................ true

[java] logging message size .......... 250

[java] Java agent control channel is ready.

[java] rmiiiop = true

[java] control channel connected to localhost:9998

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

HelloWorld sample application

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


was passed to the HelloWorld constructor.


was passed to the HelloWorld constructor.

Hello world!

This value was passed to the contstructor: 1234

Recursive calculations in subclasses result in: 5, 4

09.01.2006 13:46:53 com.dynatrace.diagnostics.sampl es.helloworld.HelloWorld run

WARNUNG: A sample hello world exception has been th rown.

The result of the calculation: 1

09.01.2006 13:46:55 com.dynatrace.diagnostics.sampl es.helloworld.HelloWorld doIt

INFO: The recursive calculation has completed.

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

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

-------------------Exception Handling-------------- ---------------

caught Exceptions class constructor

Caught Exception Msg: For input string: "test"

Caught exception cause: Iám a test Exception

Press ´R´ followed by énter´ to run again

Press ´Q´ followed by énter´ to quit HelloWorld

q

HelloWorld ended.

flushing agent event buffer...

[native] Shutdown successful

Run the "GoSpace Demo Application"

Have you ever thought about a nice trip to the stars? Do it with the GoSpace Demo Application and moreover test the dynaTrace Diagnostics with an Application, which runs on the JBoss 3.2.5 Application Server. To run the goSpace application, follow the steps below.

Windows:

• All the programs needed to run and test the GoSpace application can be started via "Start" - "Programs" - "dynaTrace Diagnostics" feature of Windows

• First of all start the Diagnostics Server. • You can check the Status of the Diagnostics Server by starting the "Diagnostics Server

Manager" • Run the "GoSpace Demo Application":

o Wait until both the front-end and back-end instances of the GoSpace Application are started.

o Press any key in the "GoSpace Demo Application" DOS - Prompt. The GoSpace frontend will come up in a browser window.

• Start the Diagnostics Client. • Switch back to the goSpace frontend and login. (user: demouser; password: demopass) • Check the tracing-results in the Diagnostics Client.

4.5.1.1. Diagnostics Agent Configuration

This chapter guides you through the Diagnostics Agent Configuration process. It explains following sections:

• Java Agent Configuration : Configure the Diagnostics Agent for Java on various operating systems and Java Virtual Machines

• .NET Agent Configuration : Configure the Diagnostics Agent .NET with the Agent Configuration Tool for .NET

4.5.2. Diagnostics Agent Configuration for Java

Diagnostics Agent Parameters

The Diagnostics Agent takes one or more comma-separated parameters. Parameters are either mandatory (name and server) or optional and configured as follows: J2SE 5.0: -agentpath:<agentlib>=<parameter>[,<option>]* J2SE 1.4: -Xrundtdagent:<option>[,<parameter>]* Where <parameter> or <option> is one of the following:

name=<agentname> This mandatory parameter assigns a descriptive name to

the Diagnostics Agent. The name should reflect the tier or application which is observed by this Diagnostics Agent. The agentname must be unique among deployed Diagnostics Agents. The agentname must not contain spaces, tabs, commas or other special characters.

server=<host>[:port] This mandatory parameter sets the host and optionally also the port to connect to the . The host may be a fully qualified host name or an IP Address. The port may be omitted and defaults to 9998.

loglevel=<level> Option: Specifies the overall log level. The level can be one of the following: finest | finer | fine | config | info | warning | severe | none. When the loglevel option is omitted, the level defaults to info.

logstdout=<level> Option: Specifies the log level for writing to the console. Setting this option to NONE suppresses all log output to console while still writing to the logfile. The level can be one of the following: finest | finer | fine | config | info | warning | severe | none. When the

logstdout option is omitted, the level defaults to info.

logfile=<filename> Option: Specifies the filename of the logfile. If omitted, the filename defaults to <dtd_agentname>.

logpath=<path> Option: Specifies the target path for writing the log files. The logfile name is of the form <dtd_agentname>.

hirestimer=<timertype> Option: This option sets the high-resolution timer which should be used for this Diagnostics Agent. The timertype can be one of the following values: cpu | os | java | runtime | auto. When the hirestimer option is omitted or set to auto the timertype defaults to the best option for your platform.

wait=<seconds> Option: Specifies the maximum time to wait for a connection to a in seconds. If the connection cannot be established within this timeframe, the application continues uninstrumented. Default is 60 seconds.

sotimeout=<seconds> Option: Specifies the native Diagnostics Agent´s socket timeout for sending/receiving data in seconds. Default is 30 seconds.

retrydelay=<seconds> Option: specifies the time the native Diagnostics Agent waits before trying to reconnect to the . Default is 60 seconds.

ctimeout=<seconds> Diagnostics Agent Option: specifies maximum time the native Diagnostics Agent waits until a connection to the is established. Default is 10 seconds.

tmtimeout=<seconds> Option: if specified, a warning log message is issued if the transformation of a single class exceeds the specified time.

excludeclasses=<yes|no> Option: enables to manually exclude classes of the Diagnostics Agent and reflection classes from the transformation process. If set to no, the classes listed below are transformed, otherwise they are excluded from transformation. Default is yes. Classes affected from parameter excludeclasses:

• All classes in package com/dynatrace/diagnostics/agent/

• Classes in package sun/reflect, if the name starts with "GeneratedMethodAccessor" and the super class is "sun/reflect/MethodAccessorImpl".

• Classes in package sun/reflect, if the name starts with "GeneratedSerializationConstructorAccessor" and the super class is "sun/reflect/SerializationConstructorAccessorImpl".

• Classes in package sun/reflect, if the name starts with "GeneratedConstructorAccessor" and the super class is "sun/reflect/ConstructorAccessorImpl".

Using Environment Variables

Linux

use export for bash or setenv for csh

J2SE 1.4

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$/lib

java -Xrundtdagent:name=<AgentName>,server=<dtdserv er>

J2SE 5.0

java -agentpath:"$/lib/libdtdagent.so"=name=<AgentN ame>,server=<dtdserver>

Solaris


J2SE 1.4

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$/lib


J2SE 5.0

java -agentpath:"$/lib/libdtdagent.so"=name=<AgentN ame>,server=<dtdserver>

AIX


J2SE 1.4

export LIBPATH=$LIBPATH:$/lib


Windows

Use the installer to setup the Diagnostics Agent on the machine.

J2SE 1.4

set PATH=%PATH%;%%\lib


J2SE 5.0

java -agentpath:"%%\lib\dtdagent.dll"=name=<AgentNa me>,server=<dtdserver>

Alternate Diagnostics Agent Injection for J2SE 5.0

4.5.2.1. The Diagnostics Agent -agentlib option for J2SE 5.0

-agentlib:<agent-lib-name>=<options>

J2SE 5.0 offers two different options for injecting the dtdagent. Additionally to using -agentpath as described above there is a more platform neutral way by using the -agentlib. This can be used as follows:

4.5.2.2. J2SE 5.0 alternate injection using -agentl ib under UNIX (Linux/Solaris)

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$/lib<br>ja va-

agentlib:dtdagent=name=<AgentName>,server=<dtdserve r>

4.5.2.3. J2SE 5.0 alternate injection using -agentl ib under Windows

set PATH=%PATH%;%%\lib<br>java-agentlib:dtdagent=na me=<AgentName>,server=<dtdserver>

4.5.3. Diagnostics Agent Configuration for .NET

The Diagnostics Agent for .NET is installed with both the full installation of the dynaTrace Diagnostics and the Diagnostics Agent package. Note: After installing the Diagnostics Agent on a machine, you have to run your application once to notify the Diagnostics Agent about the new .NET application.

After the first run the Agent Configuration Tool for .NET is used for configuration. The Agent Configuration Tool for .NET can be started via "start" → "All Programs" → "dynaTrace Diagnostics" → "Agent Configuration Tool for .NET"

Figure: dynaTrace Diagnostics .NET Agent Configuration Tool

The injection state indicates wheter profiling is enabled or not. It relates to all agents within the dynaTrace Diagnostics .NET Agent Configuration Tool. Select the desired process and open the dynaTrace Diagnostics .NET Agent Settings Dialog by clicking edit.

Figure: The dynaTrace Diagnostics .NET Agent Settings

Configure the following settings as indicated below. The Agent Name setting is mandatory. The other settings are optional.

Executeable This uneditable setting shows the name of the executable for the .NET process.

Agent Name This mandatory setting assigns a descriptive name to the Diagnostics Agent. The name should reflect the tier or application that is observed by this Diagnostics Agent. The agentname must be unique among deployed Diagnostics Agents. The agentname must not contain spaces, tabs, commas or other special characters.

Path The path specifies the location of the executable. Via the drop down box either the path to a specific executable or all executables files with the executable name can be selected.

Diagnostics Server

This setting is used to configure the host and the port for connection to the Diagnostics Server. The host may be a fully qualified host name or an IP Address. The default host and port values are set to localhost:9998 .

Logfile Specifies the path and the filename for writing the logfiles. If omitted, the filename defaults to <dtd_agentname>.log and the path default is

located in a folder a level higher than the agent library. For example, the dtdnetagent.dll file is located in the \lib folder so the log output can be found in the \log folder on the same level as the \lib folder. Note: The executeable process must have the privilege to write into the

specified logfolder. That might be problematic for e.g. the ASP.NET worker process , because it is started by default with restricted

privileges. If the process is not allowed to access the specified log folder no logs will be generated.

Loglevel Specifies the overall log level. The level can be one of the following: finest | finer | fine | config | info | warning | severe | off . When the loglevel option is omitted, the level

defaults to off.

Console Loglevel

Specifies the log level for writing to the console. Setting this option to NONE suppresses all log output to console while still writing to the logfile. The level can be one of the following: finest | finer | fine | config | info | warning | severe | off . When the

console loglevel option is omitted, the level defaults to off.

Note: The Agent Configuration Tool for .NET can only be run by a user with administrator privileges.

Enable local profiling

In situations where you are not permitted to set the environment variables system-wide, enable profiling in local files, for example batch scripts, by setting the following environment variables. For example:

@echo off

REM set environment variables necessary for loading Diagnostics Agent

set COR_ENABLE_PROFILING=0x1

set COR_PROFILER={204599FF-741F-4984-9EB6-CC68B6F96 C55}

4.6. Application Integration

This chapter explains how to integrate the Diagnostics Agent into the following applications. Integration with these applications enables the Diagnostics Server to collect PurePath and performance statistics about transactions as they pass through. Integration of the Diagnostics Agent with applications only associates the Diagnostics Agent with the application. The Diagnostics Agent does not do anything until it is invoked by the Diagnostics Server as a part of specific Diagnostic Sessions. This documentation covers how to instrument the following applications to run the Diagnostics Agent when the application runs. This section is organized to provide specific platform instructions for supported application servers, then platform instructions for instrumenting Java applications and running the Diagnostics Agent to diagnose applications implemented as Windows services.

• Application Servers

o JBoss o WebLogic o WebSphere o Oracle o Other Application Servers

• Java Applications

• Windows Services

4.6.1. JBoss

Unpack the Diagnostics Agent package depending on your OS using the appropriate untar

command to the machine running the System under Diagnosis (SUD). If you are using the Diagnostics Agent Windows Installer package select the installation type "typical" to install only the Java agent. If you are using the full Windows Installer package choose installation type "custom" and ensure that the installation of the Java agent is enabled. Make sure that the Diagnostics Server is running before deploying the Diagnostics Agents.

JBoss 4

Linux

This version of dynaTrace Diagnostics supports JBoss 4 running on Linux using J2SE 5.0 and J2SE 1.4.

J2SE 5.0

• extend the environment variable JAVA_OPTS : -agentpath:<dtdhome>/lib/libdtdagent.so=name=<dtdage ntname>,server=<dtdServer> , where <dtdhome> represents the dynaTrace

Diagnostics installation directory.

Modify the JBoss run.sh file. On Linux, <JBossHome> may be located at /opt/jboss-4.0.2/. Open the <JBossHome>/bin/run.sh and modify the script according to the bold parts below. A good place for extending JAVA_OPTS - the parameters that are handed over to the virtual machine -

is just above the run-script displays its environment.

JAVA_OPTS="-agentpath:/opt/dynatrace-diagnostics-

2.0/lib/libdtdagent.so=name=Jboss402,server=aziza $ JAVA_OPTS"

# Display our environment

echo "============================================= ============================"

echo ""

echo " JBoss Bootstrap Environment"

echo ""

echo " JBOSS_HOME: $JBOSS_HOME"

echo ""

echo " JAVA: $JAVA"

echo ""

echo " JAVA_OPTS: $JAVA_OPTS"

echo ""

echo " CLASSPATH: $JBOSS_CLASSPATH"

echo ""

echo "============================================= ============================"

echo ""

.

.

.

STATUS=10

while [ $STATUS -eq 10 ]

do

# Execute the JVM

"$JAVA" $JAVA_OPTS \

-Djava.endorsed.dirs="$JBOSS_ENDORSED_DIRS" \

-classpath "$JBOSS_CLASSPATH" \

org.jboss.Main "$@"

STATUS=$?

.

.

done

J2SE 1.4

• Append the dynaTrace Diagnostics lib folder to the LD_LIBRARY_PATH environment variable. LD_LIBRARY_PATH=<dtdhome>/lib:$LD_LIBRARY_PATH

where <dtdhome> represents the dynaTrace Diagnostics installation directory (e.g. LD_LIBRARY_PATH=/opt/dynatrace-diagnostics-2.0/lib:$LD_LIBRARY_PATH )

• extend the environment variable JAVA_OPTS : -Xrundtdagent:name=<dtdagentname>,server=<dtdServerH ostName>

Modify the JBoss run.sh file. On Linux, <JBossHome> may be located at /opt/jboss-4.0.2/. Open the <JBossHome>/bin/run.sh and modify the script as indicated by the bold parts below. A good place for extending the library path and JAVA_OPTS - the parameters that are handed over to

the virtual machine - is just above the run-script displays its environment.

LD_LIBRARY_PATH="/opt/dynatrace-diagnostics-2.0/lib :$LD_LIBRARY_PATH"

export LD_LIBRARY_PATH

JAVA_OPTS= "-Xrundtdagent:name=Jboss402,server=aziz a $JAVA_OPTS"

# Display our environment

echo "============================================= ============================"

echo ""

echo " JBoss Bootstrap Environment"

echo ""

echo " JBOSS_HOME: $JBOSS_HOME"

echo ""

echo " JAVA: $JAVA"

echo ""

echo " JAVA_OPTS: $JAVA_OPTS"

echo ""

echo " CLASSPATH: $JBOSS_CLASSPATH"

echo ""

echo "============================================= ============================"

echo ""

.

.

.

STATUS=10

while [ $STATUS -eq 10 ]

do

# Execute the JVM

"$JAVA" $JAVA_OPTS \

-Djava.endorsed.dirs="$JBOSS_ENDORSED_DIRS" \

-classpath "$JBOSS_CLASSPATH" \

org.jboss.Main "$@"

STATUS=$?

.

.

done

Windows

This version of dynaTrace Diagnostics supports JBoss 4 running on Windows using J2SE 5.0 and J2SE 1.4.

J2SE 1.4

• set the JAVA_HOME environment variable if not set • append the JAVA_HOME and <dtdhome>\lib folder to the PATH environment

variable; (note: when the Java application runs under the System account as a Windows service, the PATH must be appended to the System environment variables; the system must be rebooted after the change). PATH=%JAVA_HOME%\bin;<dtdhome>\lib;

• append following to the environment variable JAVA_OPTS -Xrundtdagent:name=<dtdagentname>,server=<dtdServer >

Modify the JBoss run.bat startup script. On Windows, <JBossHome> may be located at c:\jboss-4\. Open the <JBossHome>\bin\run.bat and modify the script as indicated by the bold parts below.

echo ============================================== =================================

echo .

echo JBoss Bootstrap Environment

echo .

echo JBOSS_HOME: %JBOSS_HOME%

echo .

echo JAVA: %JAVA%

echo .

echo JAVA_OPTS: %JAVA_OPTS%

echo .

echo CLASSPATH: %JBOSS_CLASSPATH%

echo .

echo ============================================== =================================

echo .

set JAVA_HOME=t:\j2sdk1.4.2_05

set PATH=%JAVA_HOME%\bin; C:\Program Files\dynaTrace Diagnostics 2.0\lib;

set JAVA_OPTS= -Xrundtdagent:name=JBoss4,server=all en:9998 %JAVA_OPTS%

:RESTART

"%JAVA%" %JAVA_OPTS% "-Djava.endorsed.dirs=%JBOSS_E NDORSED_DIRS%" -classpath

"%JBOSS_CLASSPATH%" org.jboss.Main %*

.

J2SE 5.0

• set the JAVA_HOME environment variable if not set • extend the environment variable JAVA_OPTS :

-agentpath:<dtdhome>\lib\dtdagent.dll=name=<dtdagent name>,server=<dtdServer> where <dtdhome> represents the dynaTrace


Modify the JBoss run.bat startup script. On Windows, <JBossHome> may be located at c:\jboss-4\. Open the <JBossHome>\bin\run.bat and modify the script as indicated by the bold parts below.

rem Setup the java endorsed dirs

set JBOSS_ENDORSED_DIRS=%JBOSS_HOME%\lib\endorsed

set JAVA_OPTS= -agentpath:"C:\Program Files\dynaTra ce Diagnostics

2.0\lib\dtdagent.dll"=name=JBoss,server=localhost % JAVA_OPTS%

echo ============================================== =================================

echo .

echo JBoss Bootstrap Environment

echo .

echo JBOSS_HOME: %JBOSS_HOME%

echo .

echo JAVA: %JAVA%

echo .

echo JAVA_OPTS: %JAVA_OPTS%

echo .

echo CLASSPATH: %JBOSS_CLASSPATH%

echo .

echo ============================================== =================================

echo .

:RESTART

"%JAVA%" %JAVA_OPTS% "-Djava.endorsed.dirs=%JBOSS_E NDORSED_DIRS%" -classpath

"%JBOSS_CLASSPATH%" org.jboss.Main %*

IF ERRORLEVEL 10 GOTO RESTART

:END

if "%NOPAUSE%" == "" pause

:END_NO_PAUSE

JBoss 3

Windows

This version of dynaTrace Diagnostics supports JBoss 3 running on Windows using J2SE 5.0 and J2SE 1.4.

J2SE 5.0

• append following to the environment variable JAVA_OPTS : -agentpath:<dtdhome>\lib\dtdagent.dll=name=<dtdagent name>,server=<dtdServer>

Modify the JBoss run.bat startup script. On Windows, <JBossHome> may be located at c:\jboss-3.2.5\. Open the <JBossHome>\bin\run.bat and modify the script as indicated by the bold parts below.

@echo off

rem ----------------------------------------------- --------------------------

rem JBoss Bootstrap Script for Win32

rem ----------------------------------------------- --------------------------

rem ---set Java Environment options---

set JAVA_HOME=t:\jdk1.5.0_04

set PATH=%JAVA_HOME%\bin

set JAVA_OPTS= -agentpath:"C:\Program Files\dynaTra ce Diagnostics

2.0\lib\dtdagent.dll"=name=Jboss325,server=aziza %J AVA_OPTS%

.

.

"%JAVA%" %JAVA_OPTS% -classpath "%JBOSS_CLASSPATH%" org.jboss.Main %*

.

J2SE 1.4

• append the dynaTrace Diagnostics lib folder to the PATH environment variable; (note: when the Java application runs under the System account as a Windows service, the PATH must be appended to the System environment variables; the system must be rebooted after the change). PATH=%PATH%;<dtdhome>\lib where <dtdhome> represents the dynaTrace Diagnostics installation directory (e.g. PATH=%PATH%;"c:\Program Files\dynaTrace Diagnostics 2.0\lib" )

• set the environment variable JAVA_OPTS to: -Xrundtdagent:name=<dtdagentname>,server=<dtdServer >

If you are using J2SE 1.4 modify the script as indicated by the bold parts below.

@echo off

rem ----------------------------------------------- --------------------------

rem JBoss Bootstrap Script for Win32

rem ----------------------------------------------- --------------------------


set JAVA_HOME=t:\j2sdk1.4.2_05

set PATH=%JAVA_HOME%\bin;" C:\Program Files\dynaTrace Diagnostics 2.0\lib\"; % PATH%

set JAVA_OPTS= -Xrundtdagent:name=Jboss325,server=a ziza %JAVA_OPTS%

.

.

.

:RESTART "%JAVA%" %JAVA_OPTS% -classpath "%JBOSS_CLASSPATH%" org.jboss.Main %*

.

Troubleshooting

Configuration file:

For Windows: <JBossHome>\server\backend\conf

For Linux: <JBossHome>/server/backend/conf

Log files:

For Windows: <JBossHome>\server\backend\log

For Linux: <JBossHome>/server/backend/log

4.6.2. WebLogic



WebLogic 9

Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on Weblogic 9 running on Windows using J2SE 5.0.

J2SE 5.0

• extend the environment variable JAVA_OPTIONS : -agentpath:<dtdhome>\lib\dtdagent.dll=name=<dtdagent name>,server=<dtdServer> where <dtdhome> represents the dynaTrace


Modify the WebLogic startup script. Open the script and modify it as indicated by the bold parts below.

@REM START WEBLOGIC

set JAVA_OPTIONS= -agentpath:"C:\Program Files\dyna Trace Diagnostics

2.0\lib\dtdagent.dll"=name=WebLogic,server=localhos t %JAVA_OPTIONS%

echo starting weblogic with Java version:

%JAVA_HOME%\bin\java %JAVA_VM% -version

if "%WLS_REDIRECT_LOG%"=="" (

echo Starting WLS with line:

echo %JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% -

Dweblogic.Name=%SERVER_NAME% -Djava.security.policy =%WL_HOME%\server\lib\weblogic.policy

%PROXY_SETTINGS% %SERVER_CLASS%

%JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% -Dweblogic.Name=%SERVER_NAME% -

Djava.security.policy=%WL_HOME%\server\lib\weblogic .policy %PROXY_SETTINGS%

%SERVER_CLASS%

) else (

echo Redirecting output from WLS window to %WLS_RED IRECT_LOG%

%JAVA_HOME%\bin\java %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% -Dweblogic.Name=%SERVER_NAME% -

Djava.security.policy=%WL_HOME%\server\lib\weblogic .policy %PROXY_SETTINGS%

%SERVER_CLASS% >"%WLS_REDIRECT_LOG%" 2>&1

)

Linux

The following describes how to configure dynaTrace Diagnostics to diagnose applications on Weblogic 9 running on Linux using J2SE 5.0.

J2SE 5.0

• extend the environment variable JAVA_OPTIONS : JAVA_OPTIONS= "-agentpath:<dtdhome>/lib/libdtdagent.so=name=Medrec, server=gilles ${JAVA_OPTIONS}"


# START WEBLOGIC

JAVA_OPTIONS= "-agentpath:/home/labuser/dynatrace-d iagnostics-

2.0/lib/libdtdagent.so=name=Medrec,server=gilles ${ JAVA_OPTIONS}"

echo "starting weblogic with Java version:"

${JAVA_HOME}/bin/java ${JAVA_VM} -version

if [ "${WLS_REDIRECT_LOG}" = "" ] ; then

echo "Starting WLS with line:"

echo "${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_AR GS} ${JAVA_OPTIONS} -

Dweblogic.Name=${SERVER_NAME} -

Djava.security.policy=${WL_HOME}/server/lib/weblogi c.policy ${PROXY_SETTINGS}

${SERVER_CLASS}"

${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${ JAVA_OPTIONS} -



${SERVER_CLASS}

else

echo "Redirecting output from WLS window to ${W LS_REDIRECT_LOG}"

${JAVA_HOME}/bin/java ${JAVA_VM} ${MEM_ARGS} ${ JAVA_OPTIONS} -



${SERVER_CLASS} 2>&1 >"${WLS_REDIRECT_LOG}"

fi

WebLogic 7, WebLogic 8

Linux

The following describes how to configure dynaTrace Diagnostics to diagnose applications on Weblogic 7 or 8 running on Linux using J2SE 1.4 and J2SE 5.0.

J2SE 1.4

• Append the <dtdhome>/lib folder to the LD_LIBRARY_PATH environment variable. LD_LIBRARY_PATH=<dtdhome>/lib:$LD_LIBRARY_PATH where <dtdhome> represents the dynaTrace Diagnostics installation directory (e.g. LD_LIBRARY_PATH=/opt/dynatrace-diagnostics-2.0/lib:$LD_LIBRARY_PATH )

• Extend the environment variable JAVA_OPTIONS : JAVA_OPTIONS= "-Xrundtdagent:name=<dtdagentname>,server=<dtdServer> ${JAVA_OPTIONS}"


echo

echo "POINTBASE DATABASE HAS BEEN STARTED, IT´S PID IS ${POINTBASE_PID}!"

echo

#************************************************** **************************

export LD_LIBRARY_PATH=/opt/dynatrace-diagnostics-2 .0/lib:$LD_LIBRARY_PATH

JAVA_OPTIONS= "-Xrundtdagent:name=WebLogic,server=l ocalhost ${JAVA_OPTIONS}"

# Start WebLogic server

CLASSPATH="petstorepatch.jar${CLASSPATHSEP}${WEBLOG IC_CLASSPATH}${CLASSPATHSEP}${JAVA_HOM

E}/jre/lib/rt.jar${CLASSPATHSEP}${CLASSPATH}"

export CLASSPATH

"$JAVA_HOME/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA _OPTIONS} -

Dweblogic.Name=${SERVER_NAME} -Dweblogic.management .username=${WLS_USER} -

Dweblogic.management.password=${WLS_PW} -

Dweblogic.ProductionModeEnabled=${PRODUCTION_MODE} -

Djava.security.policy="${WL_HOME}/server/lib/weblog ic.policy" weblogic.Server

J2SE 5.0

• Extend the environment variable JAVA_OPTIONS : JAVA_OPTIONS= "-agentpath:<dtdhome>/lib/libdtdagent.so=name=<dtdage ntname>,server=<dtdServer> ${JAVA_OPTIONS}" where <dtdhome> represents the dynaTrace Diagnostics installation directory.


echo

echo "POINTBASE DATABASE HAS BEEN STARTED, IT´S PID IS ${POINTBASE_PID}!"

echo

#************************************************** **************************

JAVA_OPTIONS= "-agentpath:/opt/dynatrace-diagnostic s-

2.0/lib/libdtdagent.so:name=WebLogic,server=localho st ${JAVA_OPTIONS}"

# Start WebLogic server

CLASSPATH="petstorepatch.jar${CLASSPATHSEP}${WEBLOG IC_CLASSPATH}${CLASSPATHSEP}${JAVA_HOM

E}/jre/lib/rt.jar${CLASSPATHSEP}${CLASSPATH}"

export CLASSPATH

"$JAVA_HOME/bin/java" ${JAVA_VM} ${MEM_ARGS} ${JAVA _OPTIONS} -

Dweblogic.Name=${SERVER_NAME} -Dweblogic.management .username=${WLS_USER} -

Dweblogic.management.password=${WLS_PW} -

Dweblogic.ProductionModeEnabled=${PRODUCTION_MODE} -

Djava.security.policy="${WL_HOME}/server/lib/weblog ic.policy" weblogic.Server

Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on Weblogic 7 or 8 running on Windows using J2SE 1.4 and J2SE 5.0.

J2SE 1.4

• Append the <dtdhome>\lib folder to the PATH environment variable. PATH=%PATH%;<dtdhome>\lib where <dtdhome> represents the

dynaTrace Diagnostics installation directory (e.g. PATH=%PATH%;c:\dynaTrace Diagnostics 2.0\lib )

• extend the environment variable JAVA_OPTIONS : -Xrundtdagent:name=<dtdagentname>,server=<dtdServer >


@rem Start PointBase 4.4.

start "PointBase" cmd /c ""%JAVA_HOME%\bin\java" co m.pointbase.net.netServer/port:9092

/d:3 /pointbase.ini="pointbase.ini"" > "pointbase.l og" 2>1

@rem ********************************************** ***************************

set PATH=C:\Program Files\dynaTrace Diagnostics 2.0 \lib;%PATH%

set JAVA_OPTIONS= -Xrundtdagent:name=WebLogic,serve r=localhost %JAVA_OPTIONS%

@rem Call WebLogic Server

set

CLASSPATH=petstorepatch.jar;%WEBLOGIC_CLASSPATH%;%J AVA_HOME%\jre\lib\rt.jar;%WL_HOME%\ser

ver\lib\webservices.jar;%CLASSPATH%

"%JAVA_HOME%\bin\java" %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% -Dweblogic.Name=%SERVER_NAME%

-Dweblogic.management.username=%WLS_USER% -Dweblogi c.management.password=%WLS_PW% -

Dweblogic.ProductionModeEnabled=%PRODUCTION_MODE% -

Djava.security.policy="%WL_HOME%\server\lib\weblogi c.policy" weblogic.Server

J2SE 5.0

• extend the environment variable JAVA_OPTIONS : -agentpath:<dtdhome>\lib\dtdagent.dll=name=<dtdagent name>,server=<dtdServer> where <dtdhome> represents the dynaTrace



@rem Start PointBase 4.4.

start "PointBase" cmd /c ""%JAVA_HOME%\bin\java" co m.pointbase.net.netServer/port:9092

/d:3 /pointbase.ini="pointbase.ini"" > "pointbase.l og" 2>1

@rem ********************************************** ***************************

set JAVA_OPTIONS= -agentpath:"C:\Program Files\dyna Trace Diagnostics

2.0\lib\dtdagent.dll"=name=WebLogic,server=localhos t %JAVA_OPTIONS%

@rem Call WebLogic Server

set

CLASSPATH=petstorepatch.jar;%WEBLOGIC_CLASSPATH%;%J AVA_HOME%\jre\lib\rt.jar;%WL_HOME%\ser

ver\lib\webservices.jar;%CLASSPATH%

"%JAVA_HOME%\bin\java" %JAVA_VM% %MEM_ARGS% %JAVA_OPTIONS% -Dweblogic.Name=%SERVER_NAME%

-Dweblogic.management.username=%WLS_USER% -Dweblogi c.management.password=%WLS_PW% -

Dweblogic.ProductionModeEnabled=%PRODUCTION_MODE% -

Djava.security.policy="%WL_HOME%\server\lib\weblogi c.policy" weblogic.Server

4.6.3. WebSphere


command to the machine running the System under Diagnosis (SUD). If you are using the Diagnostics Agent Windows Installer package select the installation type "typical" to install only the Java agent. If you are using the full Windows Installer package choose installation type "custom" and ensure that the installation of the Java agent is enabled. Make sure that the Diagnostics Server is running before deploying the Diagnostics Agents. Note: For this section, the directory of your WebSphere installation will be denoted as <WebSphereHome> .

WebSphere 6.1

AIX

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6.1 running on AIX using J2SE 5.0.

J2SE 5.0

• Start the WebSphere server using the graphical user interface or using the command line. For example /opt/ibm/WebSphere61/AppServer/bin/sh startServer.sh server1

• Open the Administrative Console through the graphical user interface or use the URL http://localhost:9060/ibm/console (when accessing the server remotely, specify the machine´s hostname rather than localhost).

• Enter your user ID and password. Then log in. • Navigate to: Server → Application servers → server1 → Java and Process Management

→ Process Definition → Java Virtual Machine • In the text field Generic JVM arguments enter: -

agentpath:<dtdhome>/lib/libdtdagent.so=name=<AgentN ame>,server=<ServerAddress>

• Apply the changes, save the configuration, and restart the server.

zOS

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6.1 running on zOS using J2SE 5.0.

J2SE 5.0

• Start the WebSphere server using the graphical user interface or using the command line: For example /opt/ibm/WebSphere61/AppServer/bin/sh startServer.sh server1



→ Process Definition → Java Virtual Machine • In the text field Generic JVM arguments enter:

-agentpath:<dtdhome>/lib/libdtdagent.so=name=<AgentN ame>,server=<ServerAddress> -Dcom.ibm.CORBA.NoLocalInterceptors=true

• Apply changes, save the configuration, and restart the server.

Note: The -Dcom.ibm.CORBA.NoLocalInterceptors=true option is

recommended because WebSphere for z/OS does not support portable interceptors.

Additionally it is recommended to set or append <dtdhome>/lib to the LIBPATH variable

of your WebSphere server:


• Enter your user ID and password. Then log in. • Navigate to: Environment → WebSphere-Variables

o Choose your server (for example server1) � Add or append <dtdhome>/lib to the LIBPATH variable.


Linux, zLinux

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6.1 running on Linux using J2SE 5.0.

J2SE 5.0


• Open the Administrative Console through the graphical user interface or use the URL http://localhost:9060/ibm/console (when accessing the server remotely, specify the machine´s hostname instead of localhost).



agentpath:<dtdhome>/lib/libdtdagent.so=name=<AgentN ame>,server=<ServerAddress>


Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6.1 running on Windows using J2SE 5.0.

J2SE 5.0

• Start the WebSphere server using the Windows start menu or using the command line: For example c:\WebSphere61\AppServer\bin\startserver server1 .

• Open the Administrative Console through the graphical user interface or use the URL http://localhost:9060/ibm/console (when accessing the server remotely, specify the machine´s hostname rather than of localhost).

• Enter your user ID and Password. Then log in • Navigate to: Server → Application servers → server1 → Java and Process Management


agentpath:<dtdhome>/lib/dtdagent.dll=name=<AgentNam e>,server=<ServerAddress>


WebSphere 6

AIX

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6 running on AIX using J2SE 1.4

J2SE 1.4

• Copy libdtdagent.so (libdtdagent.so resides in the "<dtdhome>/lib/" - directory) to <WebSphereHome>/bin/



• Enter any value as user ID and log in • Navigate to: Servers Node → Application servers → server1 → Java and Process

Management → Process Definition → Java Virtual Machine • In the text field Generic JVM arguments enter: -

Xrundtdagent:name=<AgentName>,server=<ServerAddress >


Alternate Deployment Without Agent File Copy

In situations where you are not permitted to copy the agent file into the application directory, follow the steps outlined below.

• Append <dtdhome>/lib to the system environment variable LIBPATH

• Set the Generic JVM arguments to: -Xrundtdagent:name=<AgentName>,server=<ServerAddress >

• Reboot the server or start the WebSphere application server in a new shell window (only the new shell window will have the modified PATH environment set)

zOS

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6 running on zOS using J2SE 1.4

J2SE 1.4






Xrundtdagent:name=<AgentName>,server=<ServerAddress > -Dcom.ibm.CORBA.NoLocalInterceptors=true


Note: The -Dcom.ibm.CORBA.NoLocalInterceptors=true option is

recommended because WebSphere for z/OS does not support portable interceptors.

Alternate Deployment Without Agent File Copy


• Append <dtdhome>/lib to the system environment variable LIBPATH • Set the Generic JVM arguments to: -



Alternately you can set or append <dtdhome>/lib to the LIBPATH variable of your

WebSphere server:

• Open the Administrative Console through the graphical user interface or use the URL http://localhost:9060/ibm/console (when accessing the server remotely, specify the machine´s hostname instead of localhost).

• Enter any value as user ID and log in • Navigate to: Environment → WebSphere-Variables

o Choose your server e.g. server1 � Add or append <dtdhome>/lib to the LIBPATH variable.


Linux, zLinux

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6 running on Linux using J2SE 1.4.

J2SE 1.4


• Start the WebSphere server using the graphical user interface or using the command line: For example /opt/ibm/WebSphere6/AppServer/bin/sh startServer.sh server1 .






Alternate Deployment without Agent File Copy


• Append <dtdhome>/lib to the system environment variable LD_LIBRARY_PATH

• Set the Generic JVM arguments to: -Xrundtdagent:name=<AgentName>,server=<ServerAddress >


Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 6 running on Windows using J2SE 1.4.

J2SE 1.4

• Copy dtdagent.dll (dtdagent.dll resides in the "<dtdhome>\lib\" - directory) to <WebSphereHome>\bin\







WebSphere 5.1.1

Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on WebSphere 5.11 running on Windows using J2SE 1.4.

J2SE 1.4

• Copy dtdagent.dll (dtdagent.dll resides in the "<dtdhome>\lib\" - directory) to <WebSphereHome>\bin\


• Open the Administrative Console through the Windows start menu or use the URL http://localhost:9090/admin (when accessing the server remotely, specify the machine´s hostname rather than localhost).

• Navigate to: Node → Servers → Application Servers → server1 → Process Definition → Java Virtual Machine. (where server1 may be different for your installation).

• In the text field Generic JVM arguments enter: -Xrundtdagent:name=<AgentName>,server=<ServerAddress >


Troubleshooting

Configuration file:

For Windows: <WebSphereHome>/config/cells/Node/nodes/servers/ser ver1/server.xml

For Linux, zLinux, AIX, zOS: <WebSphereHome>/profiles/default/config/cells/yourN odeCell/nodes/yourNode/servers/yourServer/server.xml

Log files:

For Windows: <WebSphereHome>/logs/server1/search for native_*.lo g

For Linux, zLinux, AIX: <WebSphereHome>/profiles/default/logs/server1/*.log

For zOS: The logs can be found in the appropriate IBM 3270 terminal job log.

4.6.4. Oracle



Oracle 10g

<OraHome> is the directory of your Oracle Installation e.g. c:\OraHome on windows

platforms. <UniqueAgentName> is a unique and descriptive name for the Agent. This name is further

displayed in dynaTrace Diagnostics reports.

Unix

The following describes how to configure dynaTrace Diagnostics to diagnose applications on Oracle 10g running on Unix using J2SE 1.4.

J2SE 1.4

• Copy libdtdagent.so ( libdtdagent.so resides in the "<dtdhome>/lib/" - directory) to <OraHome>/lib/

• Open the Oracle Enterprise Manager (e.g. http://localhost:1810/ ), select the instance subject to introspection, follow the links Administration and "Server Properties".

• In the section Command Line Option of the Server Properties page add the following to the Java Options field:

-Xrundtdagent:name=<UniqueAgentName>,server=<Diagno stics Server>

• Restart the Oracle instance.

Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on Oracle 10g running on Unix using J2SE 1.4.

J2SE 1.4

• Copy dtdagent.dll (dtdagent.dll resides in the "<dtdhome>\lib\" - directory) to <OraHome>\lib\

• Open the Oracle Enterprise Manager (e.g. http://localhost:1810/ ), select the instance that is subject to introspection. Follow the links Administration and "Server Properties".

• In the section Command Line Option of the Server Properties page add the following to the Java Options field: -Xrundtdagent:name=<UniqueAgentName>,server=<Diagnostics Server>

• In the section "Environment Variables" add a variable which points to the file dtdagent.dll (e.g. <OraHome>\lib\ )

• Restart the instance that is subject to introspection.

Configuring the Diagnostics Agent in the Oracle 10g Server Properties page.

Sample:

-Xrundtdagent:name=Agent1,server=lab1

Troubleshooting

Configuration file:

For Windows: <OraHome>/opmn/conf/opmn.xml

Log files:

For Windows: You find the files in the Log section of the OAS Administration Console.

4.6.5. SAP NetWeaver

If you are using the Diagnostics Agent Windows Installer package select the installation type "typical" to install only the Java agent. If you are using the full Windows Installer package choose installation type "custom" and ensure that the installation of the Java agent is enabled. Make sure that the Diagnostics Server is running before deploying the Diagnostics Agents.

SAP NetWeaver

Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on SAP NetWeaver running on Windows using J2SE 1.4.

J2SE 1.4

• Append the dynaTrace Diagnostics lib folder to the PATH environment variable. PATH=%PATH%;<dtdhome>\lib where <dtdhome> represents the

dynaTrace Diagnostics installation directory (e.g. PATH=%PATH%;c:\dynaTrace Diagnostics 2.0\lib )

• Start the SAP NetWeaver configtool (located in the usr folder - e.g. C:\usr\sap\J2E\JC00\j2ee\configtool)

Append -Xrundtdagent:name=Netweaver,server=localhost to the Servers

General Java parameters as shown in the figure below:

Figure: SAP Netweaver Instrumentation

Troubleshooting

Log files:

For Windows: The logfile can be found in the Application Server working directory (For example C:\usr\sap\J2E\JC00\work\std_server0 ).

4.6.6. Other Application Servers

dynaTrace Diagnostics supports further application servers. A generic application server integration can be found in the chapter Java Applications .

4.6.7. Java Applications



J2SE 1.4 Application

UNIX

Diagnostics Agent Deployment Steps:

1. Locate the startup script or configuration file for the Java application 2. Add the folder <dtdhome>/lib to the SUD´s system PATH (For Linux OS:

LD_LIBRARY_PATH), where <dtdhome> represents the dynaTrace Diagnostics

installation directory. 3. Add the option:

-Xrundtdagent:name=<dtdagentname>,server=<hostname> to

the SUD´s Java options.

#!/bin/sh

echo "starting HelloWorld"

echo "==========================="

echo ""

#specify JAVA_HOME of JDK14 installation

JAVA_HOME=/usr/java/j2sdk1.4.2_08

export JAVA_HOME

PATH=$JAVA_HOME/jre/bin:$PATH

export PATH

LD_LIBRARY_PATH=/opt/dynatrace-diagnostics-2.0/lib: $LD_LIBRARY_PATH


JAVA_OPTIONS= "-Xrundtdagent:name=HelloWorld,server =localhost" $JAVA_OPTIONS

echo ---executing HelloWorld.class---

${JAVA_HOME}/jre/bin/java ${JAVA_OPTIONS}

com.dynatrace.diagnostics.samples.helloworld.HelloW orld ThisIsASampleAppParam

Code Example: HelloWorld startup script

Windows


1. Add the folder <dtdhome>\lib\ to the SUD´s (System under Diagnosis) system

PATH. 2. Add the following Java options to the start script or application launcher:

-Xrundtdagent:name=<dtdagentname>,server=<hostname> to

the SUD´s Java options.


set JAVA_HOME=c:\j2sdk1.4.2

rem ---set HelloWorld application options---

set PATH=%JAVA_HOME%\jre\lib

rem ---set dynaTrace Diagnostics options---

set PATH=%PATH%;C:\Program Files\dynaTrace Diagnost ics 2.0\lib

set JAVA_OPTIONS= -Xrundtdagent:name=HelloWorld,ser ver=localhost %JAVA_OPTIONS%


java %JAVA_OPTIONS% com.dynatrace.diagnostics.samples.helloworld.HelloW orld

Code Example: Excerpt of the HelloWorld startup script


UNIX


1. Locate the startup script or configuration file for the Java application 2. Add the options:

-agentpath:<dtdhome>/lib/libdtdagent.so=name=<descri ptiveName>,server=<hostname>

#!/bin/csh

echo "starting HelloWorld"

echo "==========================="

echo ""

JAVA_HOME=/usr/java/j2sdk1.4.2_08

export JAVA_HOME

PATH=$JAVA_HOME/jre/bin:$PATH

export PATH

JAVA_OPTIONS= "-agentpath:/opt/dynatrace-diagnostic s-

2.0/lib/libdtdagent.so=name=HelloWorld,server=local host $JAVA_OPTIONS"


java ${JAVA_OPTIONS} com.dynatrace.diagnostics.samples.helloworld.HelloW orld

ThisIsASampleAppParam

Code Example: HelloWorld startup script

Windows

Deployment Steps:

1. Add the following Java options to the start script or application launcher: -agentpath:<dtdhome>\lib\dtdagent.dll=name=<descript iveName>,server=<hostname>


set JAVA_HOME=c:\j2sdk1.4.2

rem ---set HelloWorld application options---

set PATH=%JAVA_HOME%\jre\lib

rem ---set dynaTrace Diagnostics options---

set JAVA_OPTIONS= -agentpath: "C:\Program Files\dyn aTrace Diagnostics

2.0\lib\dtdagent.dll"=name=HelloWorld,server=localh ost %JAVA_OPTIONS%


java %JAVA_OPTIONS% com.dynatrace.diagnostics.samples.helloworld.Hello World

Code Example: Excerpt of the HelloWorld startup script

Alternate Agent Deployment

Diagnostics Agent JAVA_TOOL_OPTIONS

Since the command-line cannot always be accessed or modified, for example in embedded VMs or simply VMs launched deep within scripts. A JAVA_TOOL_OPTIONS variable is provided so that Diagnostics Agents may be launched in these cases. Platforms which support environment variables or other named strings, may support the JAVA_TOOL_OPTIONS variable. This variable will be broken into options at white-space boundaries. White-space characters include space, tab, carriage-return, new-line, vertical-tab, and form-feed. Sequences of white-space

characters are considered equivalent to a single white-space character. No white-space is included in the options unless quoted. Quoting is as follows:

• All characters enclosed between a pair of single quotation marks (´ ´), except a single quotation, are quoted.

• Double quotation characters have no special meaning inside a pair of single quotation marks.

• All characters enclosed between a pair of double quotation marks (" "), except a double quotation, are quoted.

• Single quotation characters have no special meaning inside a pair of double quotation marks.

• A quoted part can start or end anywhere in the variable. • White-space characters have no special meaning when quoted -- they are included in the

option like any other character and do not mark white-space boundaries. • The pair of quotation marks is not included in the option.

set JAVA_TOOL_OPTIONS= -agentpath:"c:\program files \dynaTrace

Diagnostics\lib\dtdagent.dll"=name=MyTierName,serve r=localhost

4.6.8. Windows Services

If you are using the Diagnostics Agent Windows Installer package select the installation type "typical" to install only the Java agent. If you are using the full Windows Installer package choose installation type "custom" and ensure that the installation of the Java agent is enabled. Make sure that the Diagnostics Server is running before deploying the Diagnostics Agents.

If the System under Diagnosis is started as a service and you don´t have the opportunity to inject the Diagnostics Agent via a configuration file you have to follow the steps described below for J2SE 1.4 and J2SE 5.0:


• Edit the System Environment variable "Path". Prepend "<dtdhome>\lib" to the path of the Environment variable. <dtdhome>

represents the dynaTrace Diagnostics installation directory. (e.g.: C:\Program Files\dynaTrace Diagnostics 2.0\lib)

Figure: Set the Windows System Environment variable

• Edit the "ImagePath" for the application you want to test in the System registry (e.g.:HKEY_LOCAL_MACHINE\System\ControlSet001\Services\<ApplicationEntry>\ImagePath). Add the following Java Options into the "ImagePath":

-Xrundtdagent:name=<AgentName>,server=<dtdserver>

• Reboot the computer, so that the change of the system environment variable takes place.


• Edit the System Environment variable "Path". Prepend "<dtdhome>\lib" to the path of the Environment variable. <dtdhome>

represents the dynaTrace Diagnostics installation directory. (e.g.: C:\Program Files\dynaTrace Diagnostics 2.0\lib) (see picture in J2SE 5.0 section)

• Edit the "ImagePath" for the application you want to test in the System registry (e.g.:HKEY_LOCAL_MACHINE\System\ControlSet001\Services\<ApplicationEntry>\Im

agePath). Add the following Java Options into the "ImagePath":

-agentpath:<dtdhome>/lib/libdtdagent.so=name=<Agent Name>,server=<dtdserver>

• Reboot the computer, so that the change of the system environment variable takes place.

4.6.9. Java Applets



There are two possibilities for viewing and diagnosing a Java Applet:

a. Applet Viewer b. WebBrowser

Applet Viewer

UNIX

Diagnostics Agent Deployment Steps for J2SE 5.0:

1. Locate the AppletViewer within the JDK package installed on your machine For example /usr/java/jdk1.5.0_06/bin

2. Execute the Applet Viewer with the following parameters ./appletviewer URL -J-agentpath:dtdhome/lib/libdtdagent.so=name=<dtdagent name>,server=<hostname>

3. Example: [labuser@labmachine bin]$ ./appletviewer http://java.sun.com/applets/jdk/1.4/demo/applets/Ti cTacToe/example1.html -J-

agentpath:/home/labuser/dynatrace-diagnostics-2.0/lib/libdtdagent.so=name=Applet,server=localhost


1. Append <dtdhome>/lib to the system environment variable LD_LIBRARY_PATH

2. Locate the AppletViewer within the JDK package installed on your machine For example /usr/java/jdk1.4.2_05/bin

3. Execute the Applet Viewer with the following parameters ./appletviewer URL -J-Xrundtdagent:name=<dtdagentname>,server=<hostname>

4. Example: [labuser@labmachine bin]$ export LD_LIBRARY_PATH=/home/labuser/dynatrace-diagnostics -2.0:$LD_LIBRARY_PATH [labuser@labmachine bin]$ ./appletviewer http://java.sun.com/applets/jdk/1.4/demo/applets/Ti cTacToe/example1.html -J-Xrundtdagent:name=Applet,server=localhost

Windows


1. Locate the AppletViewer within the JDK package installed on your machine For example C:\devtools\jdk1.5.0_06\bin

2. Execute the Applet Viewer with the following parameters appletviewer.exe URL -J-agentpath:"dtdhome\lib\dtdagent.dll"=name=<dtdagent name>,server=<hostname>

3. Example: C:\devtools\jdk1.5.0_06\bin>appletviewer.exe http://java.sun.com/applets/jdk/1.4/demo/applets/Ti cTacToe/example1.html -J-agentpath:"C:\Program Files\dynaTrace Diagnostics 2.0\lib\dtdagent.dll"=name=Applet,server=localhost


1. Append <dtdhome>\lib to the system environment variable PATH

2. Locate the AppletViewer within the JDK package installed on your machine For example C:\devtools\jdk1.4.2_05\bin

3. Execute the Applet Viewer with the following parameters ./appletviewer URL -J-Xrundtdagent:name=<dtdagentname>,server=<hostname>

4. Example: C:\devtools\jdk1.4.2_05\bin>appletviewer.exe http://java.sun.com/applets/jdk/1.4/demo/applets/Ti cTacToe/example1.html -J-Xrundtdagent:name=Applet,server=localhost

Web Bowser: Java Control Panel

UNIX


1. Locate the Java Control Panel within the JDK package installed on your machine: For example /usr/java/jdk1.5.0_06/jre/bin

2. Start the Control Panel 3. Add the following option to Java → Java Applet Runtime Settings → Java Runtime

Parameters: -agentpath:<dtdhome>/lib/libdtdagent.so=name=<descri ptiveName>,server=<hostname>


1. Append <dtdhome>/lib to the system environment variable LD_LIBRARY_PATH

2. Locate the Java Control Panel within the JDK package installed on your machine: For example /usr/java/jdk1.4.2_05/jre/bin

Note: Make sure that the JAVA_HOME system environment variable is set to this JDK package.

3. Start the Control Panel 4. Add the following option to Advanced → Java Runtime Parameters:

-Xrundtdagent:name=<descriptiveName>,server=<hostnam e>

Windows

Deployment Steps for J2SE 5.0:

1. Open the Java Control Panel: Start → Control Panel 2. Start the Java Control Panel 3. Add the following option to Java → Java Applet Runtime Settings → Java Runtime

Parameters: -agentpath:<dtdhome>\lib\dtdagent.dll=name=<descript iveName>,server=<hostname>

Figure: Java Control Panel - Java Tab

Additionally, the following debug options should be set:

Figure: Java Control Panel - Debugging Tab


1. Append <dtdhome>/lib to the system environment variable PATH

2. Open the Java Control Panel: Start → Control Panel 3. Start the Java Control Panel

Note: Make sure that the JAVA_HOME system environment variable is set to this JDK package.

4. Add the following option to Advanced → Java Runtime Parameters: -Xrundtdagent:name=<descriptiveName>,server=<hostnam e>

Web Browser: Alternate Agent Deployment

Diagnostics Agent JAVA_TOOL_OPTIONS

Since the command-line cannot always be accessed or modified, for example in embedded VMs, or VMs launched deep within scripts, a JAVA_TOOL_OPTIONS variable is provided so that Diagnostics Agents can be launched in these cases. Platforms that support environment variables or other named strings may support the JAVA_TOOL_OPTIONS variable. This variable will be broken into options at white-space boundaries. White-space characters include space, tab, carriage-return, new-line, vertical-tab, and form-feed. Sequences of white-space characters are considered equivalent to a single white-space character. No white-space is included in the options unless quoted. Quoting is as follows:

• All characters enclosed within single quotation (´ ´), except quotation marks themselves, are quoted.

• Double quotation characters have no special meaning inside a pair of single quotation marks.

• All characters enclosed between a pair of double quotation marks (" "), except a double quotation, are quoted.

• Single quotation characters have no special meaning inside a pair of double quotation marks.

• A quoted part can start or end anywhere in the variable. • White-space characters have no special meaning when quoted -- they are included in the

option like any other character and do not mark white-space boundaries. • The pair of quotation marks is not included in the option.

set JAVA_TOOL_OPTIONS= -agentpath:"c:\program files \dynaTrace

Diagnostics\lib\dtdagent.dll"=name=MyApplet,server= localhost

Start your Web Browser from the command line. For e xample: C:\Program Files\Internet Explorer>IEXPLORE.EXE

4.6.10. ATG Dynamo


command to the machine running the System under Diagnosis (SUD). If you are using the Diagnostics Agent Windows Installer package select the installation type "typical" to install only the Java agent. If you are using the full Windows Installer package choose installation type

"custom" and ensure that the installation of the Java agent is enabled. Make sure that the Diagnostics Server is running before deploying the Diagnostics Agents.

Note: In this section, <DASHome> denotes the directory of your ATG Dynamo installation and <dtdhome> denotes the directory of your dynaTrace Diagnostics installation.

ATG Dynamo Application Server 6.3

UNIX

The following describes how to configure dynaTrace Diagnostics to diagnose applications on ATG Dynamo Application Server 6.3 running on UNIX using J2SE 1.4.

J2SE 1.4:

• Start the Dynamo Application Server using the command line: For example <DASHome>/home/bin/startDAS

• Open the Dynamo Admin Server using the URL http://localhost:8830 (when accessing the server remotely, specify the machine´s hostname rather than localhost).

• Enter your user name and password. Then log in. • Set the Native Library Path:

o Navigate to: Configuration Server → default configuration → System Paths → Set the Native Library environment variable → Extend Dynamo´s native libraries (append)

o In the text field New native library path value enter: <dtdhome>/lib

� For example /home/labuser/dynatrace-diagnostics-2.0/lib

o Append to Native Library Path

Figure: Set the Native Library Path

• Set the DYN_EXTRA_ARGS: o Navigate to: Configuration Server → default configuration → Environment

Variables → Add Environment Variables o In the Name: text field enter:

� DYN_EXTRA_ARGS o In the Value: text field enter:

� -Xrundtdagent:name=<dtdagentname>,server=<dtdServer> o Add the Environment Variable

• Restart the server

Figure: Set the Environment Variable DYN_EXTRA_ARGS

Alternate Deployment

• Append the <dtdhome>/lib folder to the LD_LIBRARY_PATH environment variable. LD_LIBRARY_PATH=<dtdhome>/lib:$LD_LIBRARY_PATH where

<dtdhome> represents the dynaTrace Diagnostics installation directory (e.g. LD_LIBRARY_PATH=/opt/dynatrace-diagnostics-2.0/lib:$LD_LIBRARY_PATH )

• Extend the environment variable JAVA_OPTIONS : JAVA_OPTIONS= "-Xrundtdagent:name=<dtdagentname>,server=<dtdServer> ${JAVA_OPTIONS}"

Modify the ATG Dynamo Application Server (<DAS_HOME>/home/bin/_atgJ2EEServer.sh) startup script. Open the script and modify it as indicated by the bold text below.

#

# Archiving logfiles

#

if [ "x$LOG" != "x0" ] ; then

LOGFILENAME=$DYNAMO_HOME/$SERVERNAME/logs/$DYNAMO_LOGFILE_NAME

if [ "x$LOG" = "x1" ] ; then

LOGARGUMENT="-logFile ${LOGFILENAME}"

elif [ "x$LOG" = "x2" ] ; then

LOGARGUMENT="-logFileOnly ${LOGFILENAME}"

fi

# If the logfile already exists and is writeable then archive it

if [ -w $LOGFILENAME ] ; then

if [ ! -d $DYNAMO_HOME/$SERVERNAME/logs/archive s ] ; then

mkdir $DYNAMO_HOME/$SERVERNAME/logs/archives

fi

mv $LOGFILENAME $DYNAMO_HOME/$SERVERNAME/logs/arc hives/$DYNAMO_LOGFILE_NAME.$DATE

fi

touch $LOGFILENAME

fi

export LD_LIBRARY_PATH=/home/labuser/dynatrace-diag nostics-2.0/lib:$LD_LIBRARY_PATH

export JAVA_OPTIONS="-Xrundtdagent:name=ATGDynamo,s erver=localhost" $JAVA_OPTIONS

STATUS=17

COMMAND="${JAVA_VM} ${JAVA_ARGS} ${SECURITY_ARGS} ${JAVA_OPTIONS} ${DYN_EXTRA_ARGS}

atg.applauncher.dynamo.DynamoServerLauncher $DYNAMO _MODULES $CONFIGPATH -prefix

$SERVERNAME -shellrestart ${LOGARGUMENT}"

DYNAMO_PIDFILE="$SERVERNAME/logs/$DYNAMO_PIDFILE_NAME"

STATUS_FILE="$SERVERNAME/logs/$STATUS_FILE_NAME"

Windows

The following describes how to configure dynaTrace Diagnostics to diagnose applications on ATG Dynamo Application Server running on Windows using J2SE 1.4.

J2SE 1.4:

• Start the Dynamo Application Server using the command line: For example <DASHome>\home\bin\startDAS.bat

• Open the Dynamo Admin Server using the URL http://localhost:8830 (when accessing the server remotely, specify the machine´s hostname rather than localhost).

• Enter user name and password. Then log in. • Set the Native Library Path:

o Navigate to: Configuration Server → default configuration → System Paths → Set the Native Library environment variable → Extend Dynamo´s native libraries (append)

o In the text field New native library path value enter: <dtdhome>\lib

� E.g. C:\Program Files\dynaTrace Diagnostics 2.0\lib

o Append to Native Library Path • Set the DYN_EXTRA_ARGS:

o Navigate to: Configuration Server → default configuration → Environment Variables → Add Environment Variables

o In the Name: text field enter:

� DYN_EXTRA_ARGS o In the Value: text field enter:

� -Xrundtdagent:name=<dtdagentname>,server=<dtdServer> o Add the Environment Variable

• Restart the server

Alternate Deployment

• Append the <dtdhome>\lib folder to the PATH environment variable. PATH=%PATH%;<dtdhome>\lib where <dtdhome> represents the

dynaTrace Diagnostics installation directory (for example PATH=%PATH%;c:\dynaTrace Diagnostics 2.0\lib )

• Extend the environment variable JAVA_OPTIONS : -Xrundtdagent:name=<dtdagentname>,server=<dtdServer >

Modify the ATG Dynamo Application Server (<DAS_HOME>\home\bin\_atgJ2EEServer.bat) startup script. Open the script and modify it as indicated by the bold text below.

:afterstart

REM

REM If dynamo is being started as a service, dcontr ol must be used to launch

REM the %JAVA_VM%

REM

if not "%DYNAMOSERVICE%"=="" goto :servicecommand

set PATH=%PATH%;c:\program files\dynatrace diagnost ics 1.6.2\lib

set JAVA_OPTIONS=-Xrundtdagent:name=ATGMeetingManag er,server=localhost %JAVA_OPTIONS%

%JAVA_VM% %JAVA_ARGS% %SECURITY_ARGS% %DYN_EXTRA_ARGS% %JAVA_OPTIONS%

atg.applauncher.dynamo.DynamoServerLauncher %DYNAMO _MODULES% %CONFIGPATH% -shellrestart

%LOGARGUMENT%

goto :endcommand

4.6.11. Apache Tomcat

Unpack the Diagnostics Agent package using the appropriate untar command (based on your

OS) to the machine running the System under Diagnosis (SUD). If you are using the Diagnostics Agent Windows Installer package, select the "typical" installation type to install only the Java agent. If you are using the full Windows Installer package, choose installation type "custom" and ensure that the installation of the Java agent is enabled. Ensure that the Diagnostics Server is running before deploying the Diagnostics Agents.

Tomcat using JVM 5.0

UNIX


1. Locate the catalina.sh script of your tomcat installation. By default this file should be located in the <TOMCAT_HOME>/bin folder.

2. Add the DTD_JAVAOPTIONS variable and set it to: -agentpath:<dtdhome>/lib/libdtdagent.so=name=<descri ptiveName>,server=<hostname>

Modify the catalina.sh script as indicated by the bold text below.

#!/bin/sh

# ------------------------------------------------- ----------------------------

# Start/Stop Script for the CATALINA Server

#

# Environment Variable Prequisites

#

# CATALINA_HOME May point at your Catalina "build" directory.

#

# CATALINA_BASE (Optional) Base directory for resol ving dynamic portions

# of a Catalina installation. If not present, resol ves to

# the same directory that CATALINA_HOME points to.

#

# CATALINA_OPTS (Optional) Java runtime options use d when the "start",

# "stop", or "run" command is executed.

#

# CATALINA_TMPDIR (Optional) Directory path locatio n of temporary directory

# the JVM should use (java.io.tmpdir). Defaults to

# $CATALINA_BASE/temp.

#

# JAVA_HOME Must point at your Java Development Kit installation.

#

# JAVA_OPTS (Optional) Java runtime options used wh en the "start",


#

# JPDA_TRANSPORT (Optional) JPDA transport used whe n the "jpda start"

# command is executed. The default is "dt_socket".

#

# JPDA_ADDRESS (Optional) Java runtime options used when the "jpda start"

# command is executed. The default is 8000.

#

# JSSE_HOME (Optional) May point at your Java Secur e Sockets Extension

# (JSSE) installation, whose JAR files will be adde d to the

# system class path used to start Tomcat.

#

# CATALINA_PID (Optional) Path of the file which sh ould contains the pid

# of catalina startup java process, when start (for k) is used

#

# $Id: catalina.sh,v 1.13.2.1 2004/08/21 15:49:49 y oavs Exp $

# ------------------------------------------------- ----------------------------

# Dynatrace specific attributes

JAVA_HOME=/export/home/user/java/jdk1.5.0_10

export JAVA_HOME

PATH=$JAVA_HOME/bin:$PATH

export PATH

DTD_JAVAOPTIONS="-agentpath:/export/home/user/dynat race-diagnostics-

2.0/lib/libdtdagent.so=name=Tomcat,server=localhost "

Search for the line elif [ "$1" = "start" ] within the script.

elif [ "$1" = "start" ] ; then

shift

touch "$CATALINA_BASE"/logs/catalina.out

if [ "$1" = "-security" ] ; then

echo "Using Security Manager"

shift

"$_RUNJAVA" $JAVA_OPTS $DTD_JAVAOPTIONS $CATALINA_OPTS \

-Djava.endorsed.dirs="$JAVA_ENDORSED_DIRS" -c lasspath "$CLASSPATH" \

-Djava.security.manager \

-Djava.security.policy=="$CATALINA_BASE"/conf /catalina.policy \

-Dcatalina.base="$CATALINA_BASE" \

-Dcatalina.home="$CATALINA_HOME" \

-Djava.io.tmpdir="$CATALINA_TMPDIR" \

org.apache.catalina.startup.Bootstrap "$@" st art \

>> "$CATALINA_BASE"/logs/catalina.out 2>&1 &

if [ ! -z "$CATALINA_PID" ]; then

echo $! > $CATALINA_PID

fi

else




Dcatalina.home="$CATALINA_HOME" \






fi

fi

Windows


1. Start "Monitor Tomcat" via "start" → "All Programs" → "Tomcat" → "Monitor Tomcat" 2. Select the "Java" tab and add the following to the "Java Options"

-agentpath:<dtdhome>\lib\dtdagent.dll=name=<descript iveName>,server=<hostname>

Figure: Monitor Tomcat Java Tab

Tomcat using JVM 1.4

UNIX


1. Locate the catalina.sh script of your tomcat installation. By default this file should be located in the <TOMCAT_HOME>/bin folder.

2. Add the DTD_JAVAOPTIONS variable and set it to: -agentpath:<dtdhome>/lib/libdtdagent.so=name=<descri ptiveName>,server=<hostname>

Modify the catalina.sh script as indicated by the bold text below.

#!/bin/sh

# ------------------------------------------------- ----------------------------

# Start/Stop Script for the CATALINA Server

#

# Environment Variable Prequisites

#

# CATALINA_HOME May point at your Catalina "build" directory.

#

# CATALINA_BASE (Optional) Base directory for resol ving dynamic portions

# of a Catalina installation. If not present, resol ves to

# the same directory that CATALINA_HOME points to.

#

# CATALINA_OPTS (Optional) Java runtime options use d when the "start",


#

# CATALINA_TMPDIR (Optional) Directory path locatio n of temporary directory

# the JVM should use (java.io.tmpdir). Defaults to

# $CATALINA_BASE/temp.

#

# JAVA_HOME Must point at your Java Development Kit installation.

#

# JAVA_OPTS (Optional) Java runtime options used wh en the "start",


#

# JPDA_TRANSPORT (Optional) JPDA transport used whe n the "jpda start"

# command is executed. The default is "dt_socket".

#

# JPDA_ADDRESS (Optional) Java runtime options used when the "jpda start"

# command is executed. The default is 8000.

#

# JSSE_HOME (Optional) May point at your Java Secur e Sockets Extension

# (JSSE) installation, whose JAR files will be adde d to the

# system class path used to start Tomcat.

#

# CATALINA_PID (Optional) Path of the file which sh ould contains the pid

# of catalina startup java process, when start (for k) is used

#

# $Id: catalina.sh,v 1.13.2.1 2004/08/21 15:49:49 y oavs Exp $

# ------------------------------------------------- ----------------------------

# Dynatrace specific attributes

JAVA_HOME=/export/home/user/java/jdk1.5.0_10

export JAVA_HOME

PATH=$JAVA_HOME/bin:$PATH

export PATH

LD_LIBRARY_PATH=/opt/dynatrace-diagnostics-2.0/lib: $LD_LIBRARY_PATH


DTD_JAVAOPTIONS="-Xrundtdagent:name=Tomcat,server=l ocalhost"

Search for the line elif [ "$1" = "start" ] within the script.

elif [ "$1" = "start" ] ; then

shift

touch "$CATALINA_BASE"/logs/catalina.out

if [ "$1" = "-security" ] ; then

echo "Using Security Manager"

shift



-Djava.security.manager \

-Djava.security.policy=="$CATALINA_BASE"/conf /catalina.policy \


-Dcatalina.home="$CATALINA_HOME" \






fi

else




Dcatalina.home="$CATALINA_HOME" \






fi

fi

Windows


1. Copy dtdagent.dll located in dtdhome\lib into the Tomcat installation folder. (for example C:\Tomcat41)

2. Start "Monitor Tomcat" via "start" → "All Programs" → "Tomcat" → "Monitor Tomcat" 3. Select the "Java" tab and add the following to the "Java Options"

-Xrundtagent:name=<dtdagentname>,server=<hostname>

Figure: Monitor Tomcat Java Tab

5. Administration

This chapter guides you through the dynaTrace Diagnostics administration process. It comprises following sections:

• Diagnostics Server Administration : Administration settings for a Diagnostics Server configuration

• Diagnostics Client Administration : Administration settings for the Diagnostics Client

5.1. Server Administration

Each configured Diagnostics Server can be administered within the Diagnostics Client. As a prerequisite, the user who wants to change Diagnostics Server preferences must have the role "Administrator". For further details concerning user roles and their permission please refer to the subchapter Users .

Diagnostics Server Configurations:

• Connectivity • Settings • Repository • Sensor Types • Users • Plug-Ins • Directories

Connectivity

Within this configuration dialog the host and port of the Diagnostics Server can be set. Furthermore the options for connecting automatically to this Diagnostics Server on Diagnostics Client startup and for using a HTTP proxy server are configurable.

Settings

This configuration dialog provides settings for the Diagnostics Client listen port, the Diagnostics Agent listen port and the maximum number of nodes per path.

Repository

dynaTrace Diagnostics provides longterm storage of the System Profile and configuration history, reports, incidents and measurements by the Diagnostics Repository. The Diagnostics

Repository resides in a database system. By configuring and connecting to a database, longterm storage is active.

Configuration

On the first startup of the Diagnostics Server an embedded database is automatically created and configured for storing the longterm data in the Diagnostics Repository. The embedded database is for quickstart only and is not recommended for use in production. The Diagnostics Repository can be changed via the Diagnostics Repository configuration dialog to a third party database. dynaTrace Diagnostics supports DB2, Oracle and MSSQL database system for the Diagnostics Repository.

Changing the Diagnostics Repository Database

Figure: Diagnostics Repository Configuration Dialog

Changing the database is only possible if no database is connected. First disconnect the current database by clicking the "Disconnect" button. Specify the new database by providing a database type, host, port, user name, and password. The password is stored encrypted by the Java Cryptographic Extension. Click the "Connect" button. Now the database is connected, but the

tables have not been created yet. To finish the setup click the "Create" button to create the tables in the database. Now the Diagnostics Repository is set up to the configured database.

Sensor Packs

This dialog contains all Knowledge Sensor Packs available on the corresponding Diagnostics Server. Knowledge Sensor Packs can be priorized (move up - higher priority, move down - lower priority) within this dialog. Custom Knowledge Sensor Packs can be exported, edited, deleted and priorized. The dialog provides the possibility of importing Knowledge Sensor Packs as well as Custom Knowledge Sensor Packs.

Users

The Users dialog provides the option of creating new users and assigning them a specific role. The following roles are predefined:

• Guest • User • Power User • Administrator

Guest

The "Guest" role owns the following permissions:

• Analyze PurePaths • Analyze PurePaths Entry Points • Analyze API Performance • Analyze Method Calls • Analyze Incidents • Analyze Remoting Performance • Analyze Database Performance • Analyze EJB Performance • Analyze WebRequest Performance • Analyze Webpage Performance • Analyze JNDI Performance • Analyze JMS Performance • Analyze WebService Performance • Analyze Exception Performance • Analyze Logging Performance • Analyze Synchronization Performance • Analyze Heap Performance • Analyze Business Transactions

User

The "User" role owns all the permissions of the "Guest" role and additionally the following permissions:

• Read/Connect to Stored Sessions • Delete Stored Session • Rename Stored Session • Make Stored Sessions Offline Available • Generate Reports • Change User Password • Access Repository Data

Power User

The "Power User" role owns all the permissions of the "Guest" and the "User" role and additionally the following permissions:

• Create System Profile Configuration • Change System Profile Configuration • Change Active Profile • Delete System Profile Configuration • Start and Stop Session Recording • Store recent PurePaths to Diagnostics Session • Clear System Session • Hot Sensor Placement • Shutdown Disconnected Agents • Create Thread Dumps • Create Total Memory Dumps • Create Selective Memory Dumps

Administrator

The Administrator role has full permissions.

Plug-Ins

The Plug-Ins dialog provides an overview of all installed plug-ins. dynaTrace Diagnostics provides its own SDK to create user defined plug-ins. Sample plug-ins (Notification Mail Plug-In and Tivoli Notification Integration) are available to notify the user about Incidents within the SUD (System under Diagnosis) by default. For further information please refer to chapter Incidents .

Directories

The Diagnostics Server offers the possibilty to set its Log, Plug-Ins and Stored Session directory. The paths are relative to the dynaTrace Diagnostics installation folder.

Note: Diagnostics Server The default directories for logging, plug-ins and Stored Sessions are created during installation of dynaTrace Diagnostics but no new directories are created if those settings are altered, so the directories used here must already exist. Otherwise the changed setting is rejected.

5.2. Client Administration

The Diagnostics Client administration includes settings for the UI update interval and the Diagnostics Client directories.

Settings

The Settings subcategory provides the setting for UI update interval.

Directories

Diagnostics Client offers the possibilty of setting its own Log, Reports and Offline Session directory.

Note: Diagnostics Server The default Directories for logging, Reports and Offline Sessions are created during installation of dynaTrace Diagnostics but no new directories are created if those settings are altered, so the directories used here must already exist. Otherwise the changed setting is rejected.

5.3. Configure Diagnostics Server

Configuring Multiple Diagnostics Server Connections

A single Dynatrace Client instance can be connected to multiple Diagnostics Server instances, enabling control of multiple Diagnostics Server with one application. A connection configuration is displayed in the cockpit view with , followed by the hostname and listening port of the Diagnostics Server.

Add new Diagnostics Server Connection

The "Add new Diagnostics Server" button opens a Diagnostics Server Preferences dialog to enter hostname and port of the Diagnostics Server. The new connection configuration is added to the cockpit view. Note: The Diagnostics Client is not yet connected to the Diagnostics Server. A connection is established on double-click to the new connection configuration icon or selecting "Connect to Server…" of the context menu of the new connection configuration.

Figure: Diagnostics Server Preferences

Delete Diagnostics Server Connection

An existing connection configuration can be deleted by selecting the connection configuration icon and pressing the delete key or by selecting "Delete" from the context menu of the Diagnostics Server connection. Note: A Diagnostics Server connection configuration can only deleted if it is not connected to a Diagnostics Server.

5.3.1. Diagnostics Repository

Overview

Measurement data collected from monitored systems is saved to the Diagnostics Repository to enable long-term analysis of system behavior. One Diagnostics Repository is maintained per each Diagnostics Server and contains data recorded from all systems monitored by that Diagnostics Server. This chapter contains information about the following topics:

• Diagnostics Repository Overview : Explains the Diagnostics Repository Overview view of dynaTrace Diagnostics

• Diagnostics Repository Charts : Explains the Diagnostics Repository Chart configuration of dynaTrace Diagnostics

5.3.1.1. Diagnostics Repository Overview

Overview

The Diagnostics Repository Overview provides a condensed view of all recorded system behavior from all monitored systems during a specific time interval. The observed time interval can be selected from the predefined interval sets (ranging from the current day through the preceding year), or the interval can be customized by specifying start and end times. System behavior is visualized using "incident bars" that prove an overview of incident distribution during observation time intervals. Incident bars divide observation time intervals into 45 time slots of equal length. Time slots are color-coded according to the most severe incident that occurs within each time slot. When a severe incident occurs within a time slot, the time slot is displayed in red, the color assigned to servere incidents. Time slots that contain only warning or informational incidents are displayed in yellow. Time slots that contain only informational incidents are displayed in blue. Time slots that do not include any incidents are displayed in grey.

Figure: All Systems Incident Bar

Each monitored system is represented by an incident bar that maps the observed time interval. The "All Systems Overview" incident bar is an aggregate of all incidents that occurred in all monitored systems during the observation time interval.

Figure: Diagnostics Repository Overview

The incident list in the bottom half of the overview, shows all incidents that occurred during the observation interval on the monitored system (which is indicated by the currently selected incident bar). A list of all the incidents that occurred during the observation interval can be displayed by selecting the "All Systems Overview" incident bar. The incident list provides severity, date, type and name for each incident. It also includes a description, optional session ID and the System Profile for the the system which caused the incident. When a session is recorded during the occurrence of an incident, the ID of the session is displayed in the "Session" field. The respective session can be opened by left-clicking the incident row and selecting "Connect to Session" from the context menue.

Figure: Incidents List

5.3.1.2. Diagnostics Repository Charts

Overview

The charting component of the Diagnostics Repository enables the charting of recorded measures across all monitored systems. The charting time interval can be selected from a predefined interval set (ranging from the current day through the preceding year) or it can be

customized by specifying start and end times, equal to the incident observation interval of the Diagnostics Repository Overview.

Figure: Chart Configuration Dialog

A measure can be added to the chart by left-clicking the list in the bottom half of the view and selecting "Add" from the context menu. The measure selection dialog enables you to select any measure that has been recorded at any time on any system that has been monitored by the Diagnostics Server. When you select a sytem from the System Profile drop list, all current active measures are available for charting. To enable visual correlation between measurement graphs and incident occurrences, an incident bar is displayed along the top of the Diagnostics Repository chart. The incident bar provides an aggregate view of the incidents that occurred during the charting time interval on the systems where the charted measures were monitored. Threshold values defined for individual measures are displayed when measures are selected. The area between the warning thresholds is displayed in white. The area between the severe thresholds and the warning thresholds is displayed in faint yellow. The areas above the severe thresholds are displayed in faint red.

Figure: Diagnostics Repository Chart

6. Configure

dynaTrace Diagnostics is a very powerful tool because it can diagnose performance problems of distributed heterogeneous J2EE and .NET systems while the system is running and under load. It is very flexible and allows Sensor Packs to be set up and dynamically activated to deeply analyze system performance. In order to do this, the system´s architecture needs to be represented in dynaTrace Diagnostics. dynaTrace Diagnostics then applies s based on the system´s technology and additional user defined Method Sensor Rules . The representation of the application to is configured through the .

This chapter guides you through the system under diagnostics configuration process. It explains following sections:

• System Profile : represents the architecture of an SUD, and various diagnosis and monitoring configurations defined for the SUD within dynaTrace Diagnostics.

• Add System : adds the arcitecture description of an application to dynaTrace Diagnostics. • System Profile Properties : configuration options available for system profiles. Includes

definition of different monitoring and diagnosis configurations for a SUD, definition of Business Transactions, Incidents and measure subscription.

• Overhead : dynaTrace Diagnostics´s best practice to reduce monitoring and diagnosis overhead.

• System View : provides an overview about the architecture of an SUD, condensed monitoring data and information about Diagnostics Agent states.

• Hot Sensor Placement : how to change sensor configuration without restarting the SUD. • Apply Configuration : how to change the configuration of an Diagnostics Agent. • Configuration Matrix : matrix showing dependencies between changes of Diagnostics

Agent configuration settings and actions required (e.g. perform Hot Sensor Placement, restart SUD) to apply the changes.

6.1. System Profile

A System Profile is an XML file that stores a representation of a configuration to diagnose a specific System Under Diagnosis (SUD). The dynaTrace Diagnostics user interface uses System Profile to visualize the system tiers, including servers, clusters, and clients and the granularity and location of sensor placements. System Profiles also contain sensor configuration information for SUDs. System Profiles are stored on the Diagnostics Server and can be found in the folder dtdhome\conf\profiles\<application_name>.profile.xm l .

Editing a System Profile requires a connection to the Diagnostics Server´s live session and the appropriate permissions (See Diagnostics Server Administration ). It is not required that an SUD is running to define and edit System Profiles.

Note: It is recommended that System Profile be administered within version control systems.

dynaTrace Diagnostics supports diagnosis of multiple systems simultaneously. Multiple System Profiles can be created. One Configuration per System Profile can be active at one time. dynaTrace Diagnostics associates captured metrics and correlates them with the appropriate system.

System Profiles enable users to:

a. Control and repeat diagnostics configurations. b. check that all Diagnostics Agents are running. c. Visualize the system tiers, including servers, clusters, and clients together with its running

Diagnostics Agent. d. Create Method Sensor Rules which include objects and methods to be instrumented

during the diagnosis. e. Define different Configurations for one system (for example, one for pre-production, one

for production). dynaTrace Diagnostics allows you to switch between the Configurations at runtime.

Multiple Configurations for the same SUD can be saved for a system within a System Profile. System Profiles are shown read-only in Offline- and Stored-Sessions . Configurations can be used to quickly switch diagnostic settings to modify measurement granularity during root cause analysis. They can also be used to recreate a production diagnostics Configuration which is identical to that used in a test environment. To switch to an alternate configuration, view the available Configurations within a System Profile from the Cockpit window in the Diagnostics Client. Right-click the desired Configuration under the System Profile and select "activate".

Note: There can only be one active Configuration within a System Profile at a time, and only inactive Configurations can be activated.

Configuration activation applies sensor configuration options immediately. However, no Sensor Placement or method sensor ruleset changes will be applied, until a Hot Sensor Placement (available in J2SE 5.0 or later) is performed or the SUD is restarted. For further details concerning configuration changes, please refer to Configuration Matrix .

The Hot Sensor Placement feature of dynaTrace Diagnostics provides the ability to re-instrument currently loaded classes without reloading them. Hot Sensor Placement is only available for Diagnostics Agents that are running under J2SE 5.0 or higher. Diagnostics Agent running under J2SE 1.4 are forced to restart the application to apply the changes and re-instrument currently loaded classes. However, Sensor Configuration changes are applied immediately for Diagnostics Agents that are running under either J2SE 1.4 or 5.0 without restarting the system.

All changes which are conducted on a System Profile are automatically transferred to the Diagnostics Server.

Figure: The Cockpit´s Live System tree

System Profile Management Options

• Open: Opens the architectural overview of the configured system. • Start Recording: Starts session recording for the selected system. • Stop Recording: Stops session recording for the selected system (Only available if

session recording is active). • Delete: Deletes the selected System Profile • Export Session…: Exports the session data which is currently in memory for this system

to a selectable destination folder. • Export System Profile… : The Diagnostics Client provides the ability to export System

Profiles via the context menu option "Export System Profile…". This option is available on every System Profile for Live Sessions.

• Properties: Opens the Configuration Settings Manager for the active Configuration.

6.2. Add System

First, in order to set up System Profiles, a System under Diagnosis (SUDs) needs to be added or defined to dynaTrace Diagnostics. dynaTrace Diagnostics also needs to understand how SUDs are configured in order to diagnose issues. dynaTrace Diagnostics handles this in levels or tiers just as the application is designed. Subsequent sections will explain how to define the

system architecture to dynaTrace. First the system needs to be added to and activated in dynaTrace Diagnostics through the Diagnostics Client.

Adding Systems

There are two ways to add a new system:

a. To add a new system you have to right-click on the desired Diagnostics Server node in the cockpit view and select "Create System Profile…"

b. Alternatively you can select the step "Start Here" → "Create a new System Profile" in the workflow bar

Describing System Profiles Fill in the information for:

• Name: a brief descriptive name for the System Profile. This name appears also in the graphical system view. The name must be unique among the System Profiles.

• Description: a description of the SUD. The description will be displayed in the graphical application view.

• Technology: choose the appropriate technology of your system.

Figure: System Profile Configuration

To close the "System Profile Properties" and save the according information simply click "OK" otherwise click "Cancel".

6.3. System Profile Properties

Overview

The following chapter guides you through the configuration of your system. Following topics are explained:

• General: a general description of the system. • Configuration: detailed configuration settings for your system, including measures,

incidents and Business Transactions. • Agent Defaults - Agent Configuration: specific configuration settings for a Diagnostics

Agent

6.3.1. General

Describing System Profiles Fill in the information for:

• Name: a brief descriptive name for the System Profile. This name appears also in the graphical application view. The name must be unique among the System Profiles.


• Technology: choose the appropriate technology of your system.

To close the "System Profile Properties" and save the according information simply click "OK" otherwise click "Cancel".

6.3.2. Configuration

dynaTrace Diagnostics allows to create multiple configurations for a system. This enables you to easily switch between configurations during runtime. For example you can switch between a high detail configuration for an in-depth diagnosis to a minimum detail configuration for production.

Describing a Configuration Fill in the information for:

• Name: a brief descriptive name for the Configuration - for example "production". This name appears also in the graphical application view. The name must be unique among the application profiles.


and choose the appropriate settings for:

• Mode: gives the users the ability to decide the importance of diagnostic information richness versus application responsiveness. In production and load testing scenarios, it is recommended to use the "non blocking communication" mode, which guarantees that the AUD is never stalled by the Diagnostics Agent, even if the Diagnostics Server becomes unavailable and the Diagnostics Agents internal buffers are saturated. When the Diagnostics Agents internal buffers are saturated, the agent automatically stops collecting performance measures in order to maintain full application responsiveness. For scenarios where behavior of the SUD is most important and where all requests need to be measured, the "blocking communication" mode should be used.

o non blocking communication: Adjust system optimization level using non blocking communication (max responsiveness)

� maximum blocking time is set to 0 seconds � buffer saturation threshold is set to 80%

o blocking communication: Adjust system optimization level using blocking communication (max information richness)

� maximum blocking time is set to 300 seconds � buffer saturation threshold is set to 100%

Figure: Configuration Specification

6.3.2.1. Measures

Overview

dynaTrace Diagnostics provides measures to monitor an SUD. Measures are tracked when they are associated with System Profile by subscribing to them within a configuration. Some measure subscriptions are automatically set up through configuration actions. Specifically, creating a new System Profile and defining its system architecture set up default configurations of measure subscriptions. To view measure subscriptions right-click on the desired system configuration from within the cockpit, choose "Properties" - "Measures". By default for example Java Virtual Machine Metrics, common APIs Execution and other Metrics are presubscribed.

Figure: Overview Subscribed Measures per Configuration

Measure Subscription

To subscribe measures right-click on the desired system configuration from within the cockpit, choose "Properties" - "Measures". Click the Add button and choose the appropriate metric.

Figure: Measure Configuration

After subscribing a measure, dynaTrace Diagnostics provides the possibility to auto-generate an incident rule out of the measure. For further information regarding notifications and incident rule please refer to chapter Incident Rule Configuration . Note: To auto-generate an incident rule a threshold for the according measure must be set.

For further information concerning measure subscription and the measures specific attributes please refer to chapter Measure Configuration .

6.3.2.2. Transactions

Overview

dynaTrace Diagnostics provides the possibility to configure Business Transactions to monitor special business procedures, like for example an insurance contract for a car. This enables you to monitor your system not only on source code level but also on business level.

Figure: Subscribed Business Transaction Overview

Transaction Subscription

To subscribe transactions right-click on the desired system configuration from within the cockpit, choose "Properties" - "Transactions". Click the "Add" button and fill in the appropriate information.

Figure: Business Transaction Editor

Fill in the general information for Business Transactions:

• Name: a brief descriptive name for the Business Transaction. • Description: a description of the Business Transaction.

Choose the correct settings for the transaction data:

• Function o filter: measures based on value-specific conditions - several filters concatenated

by AND o evaluate: evaluation of measures - definable once o group: measures based on categories o inactive: skipping this measure

• Verification: Choose the "Add" button to add a measure to the Business Transaction. • Aggregation: Choose the aggregation type for the measurements per PurePath (count,

avg, sum, max, min, last).

Set the appropriate threshold for the evaluate criteria of your Business Transaction.

After configuring a Business Transaction, dynaTrace Diagnostics provides the possibility to auto-generate an incident rule out of the Business Transaction. For further information regarding notifications and incident rule please refer to chapter Incident Rule Configuration . Note: To auto-generate an incident rule a threshold for the according transaction must be set.

For further information about creating and configuring Business Transactions please refer to chapter Business Transactions .

6.3.2.3. Incidents

dynaTrace Diagnostics provides the possibility to configure Incidents to notify a person in charge about critical or abnormal behavior of the System under Diagnosis.

Figure: Incidents Overview

Incidents Configuration

To configure an incident right-click on the desired system configuration from within the cockpit, choose "Properties" - "Incidents". Click the "Add" button and fill in the appropriate information.

Figure:Incident Rule Editor

Fill in the general information for Business Transactions:

• Rule Name: a brief descriptive name for the incident rule. • Description: a description of the incident rule.

Choose the settings for the sensitivity of the incident rule:

• Sensitivity o default: By default history count is set to 21, low threshold to 25% and high

threshold to 50%.

o user defined: To define custom lower, upper threshold and history count for the flapping detection click the "Edit" button.

� High flap threshold (%): If the percentage of the weighted changes in state (ok, warn, severe) regarding history count exceeds this threshold, the observed measure is deemed flapping.

� Low flap threshold (%): If the percentage of the weighted changes in state (ok, warn, severe) regarding history count falls below this threshold, the observed measure is deemed stable.

� History Count: Defines the number of measurements which are monitored for the flapping/non flapping decision.

o over short period: For short period flapping detection history count is set to 21, low threshold to 25% and high threshold to 50%.

o over long period: For long period flapping detection history count is set to 21, low threshold to 25% and high threshold to 50%.

o very frequently: For frequent flapping detection history count is set to 21, low threshold to 25% and high threshold to 50%.

Set the measures and conditions for the incident:

• Measure and Condition o Click the "Add" button to add a measure to this incident rule.

• Logic o Choose the appropriate logic (and, or) to concatenate multiple measures.

• Threshold and Severity

o Choose the threshold type (warning, severe) of the selected measure that is used to trigger an incident. A threshold type "noThreshold" is listed if no threshold is defined for the selected measure. Measures with no threshold definitions can be added to the conditions of Incidents, but they are ignored during evaluation of the Incident Rule. Define appropriate thresholds to include those measures to the evaluation process.

Set the actions for the incident:

• Action o Click the "Add" button to add the appropriate action which should be triggered by

the incident rule. Following actions are available: � Email Notification � Tivoli Notification � Logging Notification: The incident is logged to the incident view. � Session Storage: The session is stored after an incident occured. � PurePath Storage: The affected PurePath is stored if an incident occurs.

• Severity o Choose the severity level used for the notification action.

For further information concerning incident rule configuration and the incident rule specific attributes please refer to chapter Incident Rule Configuration .

6.3.3. All Agents

Overview

dynaTrace Diagnostics supports an "All Agents" configuration per Configuration. Any connected Diagnostics Agent will use the settings of the active Configuration. The default settings may be overwritten for individual agents by enabling the Diagnostics Agent specific settings within the active Configuration for those agents. This can be done by adding an additional Diagnostics Agent configuration to an existing System Profile. The Diagnostics Agent configuration name has to match the Diagnostics Agent´s name declared in the SUD startup script. The hostname may be specified to identify the Diagnostics Agent optionally. Especially in clustered environments , multiple Diagnostics Agents have the same name, but different hostnames.

The following chapter guides you through the configuration of your Diagnostics Agent. Following topics are explained:

• Cluster Support: How dynaTrace Diagnostics supports clusters. • Add Diagnostics Agent to System Profile: How dynaTrace Diagnostics provides the

possibility to use a specific configuration for each Diagnostics Agent per Configuration. • Sensor Placement: Overview and placement of the dynaTrace Diagnostics Sensor Pack.

• Sensor Configuration: How to manage the behavior of the Sensor Packs. • Method Sensor Rules: How dynaTrace Diagnostics uses method rules to diagnose and

manage the diagnosis of SUD. • Memory Sensor Rules: How dynaTrace Diagnostics uses memory rules to partially

diagnose the heap memory of SUD

6.3.3.1. Cluster Support

Overview

A typical cluster consists of multiple application server instances that are running on one or more server machines with load balancing in-place. dynaTrace Diagnostics supports such clusters out-of-the-box by using unique agent names and host names to correlate performance information.

Although the tier grouping has advantages, each server in the cluster should be able to be isolated for analysis purposes. The following scenarios show how to differentiate each agent by process or by server:

1. Multiple application server instances share a single JVM configuration, which includes the Diagnostics Agent name, (e.g. appserver config script) and run on a single computer/host: In this scenario Diagnostics Agents, mapping different application server instances, only differ in the process ID and are therefore grouped into a cluster.

For instance you can group following application server instances together:

Hostname Agent Name Process ID Tier Name Startup Script

Server 1 FrontendServer 6354 GoSpaceFrontend startup.sh

Server 1 FrontendServer 4567 GoSpaceFrontend startup.sh

2. Multiple application server instances share a single JVM configuration, which includes the Diagnostics Agent name, (e.g. appserver config script) and run on different computers/hosts: In this scenario Diagnostics Agents, mapping application server instances, reflect also the name of the host name of the application server, but share the same name. Those Diagnostics Agents are grouped into a cluster.

Hostname Agent Name Tier Name Startup Script

Server 1 FrontendServer GoSpaceFrontend startup.sh

Server 2 FrontendServer GoSpaceFrontend startup.sh

Within a cluster application server instances may be stopped and started.

Multi-Instance Cluster Support

In addition to the above mentioned cluster support, dynaTrace Diagnostics provides an advanced "Multi-Instance Cluster" feature for rare cases in which an application runs multiple-instances of identically configured application servers which are deployed to different hosts, whereas multiple application server instances share the same host. Such configurations, using a cluster of multiple hosts that run multiple application server instances, lead to a combination of the two scenarios described in the previous chapter.

Typically there is one startup script for a multi-instance cluster and therefore all the agents for that cluster can be injected from the same script (there is no need for using multiple startup

scripts). In that case, all agent share the same name. Agent instances are distinguished via hostname if the instances run on different hosts, or via process ID if instances run on the same host. Diagnostics Agent sharing the same name are grouped into a cluster. Multiple Diagnostics Agent instances running on one host share the same communication ports. Thus, no additional firewall ports are required for all forms of cluster support.

To define a multiple-instance cluster a Diagnostics Agent that builds a template for all Diagnostics Agents deployed to the cluster, must be added to a System Profile.

Figure: System Profile Properties

Automatical detection of Multi-Instance Cluster size extension:

The Diagnostics Client detects the required cluster size for n Diagnostics Agent configuration if new Diagnostics Agent instances connect. In case of exceeding the configured cluster size a message box will be open to confirm the automatical extension of the tiers cluster size. See System view section for more information.

6.3.4. Add an Agent to a System Profile

Overview

Most applications subdivide functionality into several tiers, which are run on distinct hosts by different instances of application servers, web servers or database servers. To support such layered applications, multiple Diagnostics Agents can be assigned to a System Profile. The monitoring topology employed by dynaTrace Diagnostics, which assigns different Diagnostics Agents to different application layers, also eases isolation the root case of performcance issues to one distinct application tier.

dynaTrace Diagnostics provides means to visually distinguish between Diagnostics Agents assigned to different application tiers.

Diagnostics Agent Configuration Steps

Step1

Open the System Profile Properties of a System Profile to add a new Diagnostics Agent by right clicking the Agents node of the System Profile´s Cockpit view and selecting the context menu entry "Add Agent…".

Figure: New Agent Dialogue

Step2

Fill in the information for:

• Settings

o Name: a short descriptive name of the Diagnostics Agent (must be unique within the System Profile)

o Type (choose): the type affects the visual representation of the agent; note that custom bitmaps can be chosen as well (click on the button to the right)

The following types are preconfigured to choose from:

� Custom � Application Server � Web Service Client � Web Browser � Rich Client � Database � Mainframe � Middleware

• Agent Mapping

Adding agents with correctly initialized type to a System Profile enables visualizing and documenting an application´s architecture, aiding communication between IT groups. Such types include clients, application servers, databases, and more. SUDs that are instrumented with dynaTrace Diagnostics can be further mapped to the Diagnostics Agent as herein described:

o Name: The name of the Diagnostics Agent, as specified in the SUD integration (−Xrun or −agentpath option)

o Host: The hostname of the machine on which the Diagnostics Agent runs. If the hostname is omitted, only the agent name is used for mapping the agent to this tier. If the hostname is provided, the agent maps to this tier only if name and hostname match.

Recommendation: use unique agent names as much as possible and omit the host name. This allows for easy sharing of System Profile between different IT groups, such as development and production.

• Multi-Instance Clustering

The multi-instance clustering feature as discussed above, allows multiple Diagnostics Agent with the same agent name, host name and startup script to be mapped into a Cluster group. For further details see chapter "Cluster Support - Multi-Instance Clustering" .

o Description: A short descriptive name of the cluster o Agent Instances: The maximum number of application instances that will run

within this cluster.

6.3.4.1. Sensor Placement

dynaTrace Diagnostics provides Sensor Packs tailored for diagnosis of important component interfaces.

Placement Options

Several attributes may be defined in a Configuration that make diagnosing issues more efficient. By choosing the appropriate settings for a specific system, the number of PurePaths can be minimized by omitting irrelevant data. Additionally, system performance improves with this efficiency and breakdown becomes more precise. Following are the attribute options:

Ignore getter and setter methods

Activating this filter omits any accessor method regardless of read-, write- or read-and-write access.

Capture Strings automatically

If capturing Strings is enabled, the first of the first three arguments, which is a String, will be recorded. Values that exceed a length of 250 characters will be truncated.

Enable synchronization diagnosis

If synchronization diagnosis is enabled, it is possible to capture synchronization time for defined Method Sensor Rules .

Available Sensor Packs

Each Sensor Pack is responsible for instrumenting a specific technology. The JMS Sensor Pack for example instruments any class that belongs to the Java Messaging API. The JDBC Sensor Pack covers database operation and so on. By toggling specific Sensor Packs, filters may be set on a component-based level. Changed Sensor Pack Placement configurations are propagated to the respective agents after a Hot Sensor Placement. If the runtime system of the SUD does not support Hot Sensor Placement, a restart of the SUD is required. Some Sensor Packs can not be deployed by a Hot Sensor Placement. Altering the "Place" flag of those s, issues a warining message. In this case, a restart of the SUD is required that the changed setting becomes effective.

Note: The set of available Sensor Packs also depends on the technology setting of the System Profile. Eg..NET sensors are only avalilable if .NET technology is enabled.

RMI tagging The RMI Tagging Sensor Pack enables tracing of PurePaths across thread, process or system boundaries for RMI/JRMP, RMI/IIOP, RMI/t3.

EJB Invocation The EJB Invocation Sensor Pack collects the type and execution time of Enterprise Java Beans (EJBs). This Sensor provides the opportunity to configure Sensor Properties. For additional information see Components Diagnosis .

JNDI The JNDI Sensor Pack collects the lookup name and time for JNDI Lookups.

Remote Method Invocation (RMI) The RMI Sensor Pack collects the time, bytes and objects involved in a Remote Method Invocation (RMI for RMI/JRMP, RMI/t3, RMI/IIOP).

Struts The Struts Sensor Pack collects the response, execution and CPU time of calls to the Struts Framework.

JDBC The JDBC Sensor Pack collects performance data and context information about preparing and

executing SQL statements. This Sensor provides the opportunity to configure Sensor Properties. For additional information see Database .

Servlets The Servlet Sensor Pack collects the response time and context information of Servlets and Java Server Pages (JSP). This Sensor provides the opportunity to configure Sensor Properties. For additional information see Web Requests Diagnosis .

Java Web Services The Web Service Sensor Pack collects destination information, sent/received bytes and the execution time for Java Webservice calls.

HTTP URLConnection Tagging The HTTP URLConnection tagging Sensor Pack enables tracing of PurePaths across thread, process or system boundaries for HTTP connections.

Hibernate The Hibernate Sensor Pack collects information concerning persistence operations done by the Hibernate OR-Mapping Framework.

JTA The JTA Sensor Pack collects information concerning the start, commit and rollback of JTA transactions.

XA The XA Sensor Pack collects state information about XA transactions.

Java JDK Logging and Log4J The Logging Sensor Pack collects Java and Log4J logging events. Collection can be filtered based on logging severity and message contents by configuring the corresponding Sensor Pack Properties. For additional information see Logging Diagnosis .

JMS Receive Entry Point The JMS Receive Entry Point Sensor Pack enables tracing from the sender to the receiver in cases the receiver uses receive() or receiveNoWait(). In these cases a JMS Receive Entry Point has to be set to the method, which is responsible for processing the message on receiver side. Method Sensor Rules

JMS Tagging The JMS Tagging Sensor Pack enables tracing of JMS Message transmissions along a PurePath.

Memory The Memory Sensor Pack enables tracing of object allocations. This Sensor Pack requires the configuration of Memory Sensor Rules.

JMS The JMS Sensor Pack collects destination information, sent/received bytes and the execution time for Java Messages.

Java Method Invocation The Java Method Invocation Sensor Pack collects the response, execution and CPU time of calls to methods that have been configured in the Method Sensor Rule editor.

Exceptions The Exception Sensor Pack collects system and application exceptions and related context information. Collection can be filtered based on exception classes and messages by configuring the corresponding Sensor Pack Properties. For additional information see Exception Diagnosis .

ADO.NET The ADO.NET Sensor Pack collects performance data and context information about preparing and executing ADO.NET statements.

.NET Method Invocation The .NET Method Invocation Sensor Pack collects the response, execution and CPU time of calls to methods that have been configured in the Method Sensor Rule editor.

ASP.NET The ASP.NET Sensor Pack collects the response time and context information of Active Server Pages .NET (ASP.NET).

.NET Web Services The .NET Web Services Sensor Pack collects destination information and the execution time for .NET Webservice calls.

.NET Web Service Tagging The .NET Web Service Tagging Sensor Pack enables tracing of PurePaths across thread, process or system boundaries for .NET Web Services.

.NET Remoting The .NET Remoting Sensor Pack collects the time, bytes and objects involved in a .NET Remoting Call.

AWT The AWT Sensor Pack enables tracing of AWT actions. This is especially important for diagnosing Java Applets .

.NET Remoting Tagging The .NET Tagging Sensor Pack enables tracing of PurePaths across thread, process or system boundaries.

JMX MBean Server The JMX MBean Server Sensor Pack enables collecting JMX data from supported Application Servers. Supported Application Servers are IBM WebSphere 6.0 and 6.1, BEA WebLogic 8.1 to 9.2, Tomcat 5.5 and higher and JBoss 3.2.5 and higher.

.NET Logging The .NET Logging Sensor Pack enables collecting of Log4net logging events.

Collection The Collection Sensor Pack enables tracing of objects that implement the java.util.Collection interface. As a prerequisite the Memory Sensor Pack must be enabled.

Thread Start tagging The Thread Start Tagging Sensor Pack enables tracing of PurePaths across thread boundaries for all Threads started by the start() method of the class java.lang.Thread (or a derived class). It is important to notice that this Sensor Pack enables tracing of all PurePaths created by starting a new thread within the current PurePath (except threads marked as daemon threads). This means that long running threads could be traced, either. That can result in situations where a thread is still running, after the main PurePath has already finished. In this case the PurePath will be incomplete until either the long running thread ends, or a timeout (5 minutes) occurs. Long running threads should be excluded from tracing by a global exclude of the class implementing the java.lang.Runnable that contains the long running run() method. Method Sensor Rules

Executor Tagging The Executor Tagging Sensor Pack enables tracing of PurePaths across thread boundaries for supported Thread Pools. Supported are Thread Pools using the JDK 1.5 Executor interface, Thread Pools using the EDU.oswego.cs.dl.util.concurrent.Executor interface, the Weblogic Thread Pool weblogic.kernel.ExecuteThreadManager and the Websphere Thread Pool com.ibm.ws.util.ThreadPool.

Maps The Map Sensor Pack enables tracing of objects that implement the java.util.Map interface. As a prerequisite the Memory Sensor Pack must be enabled.

6.3.4.2. Sensor Configuration

The Sensor Configuration view enables configuration of Sensor Packs. Note that only Sensor Pack which are placed appear in the Sensor Configuration view. Changed Sensor Configurations are propagated to the respective agents immediately, without the need of a Hot Sensor Placement or a SUD restart.

Configuration Options

The configuration options subsume configurations which are common for all deployed Sensor Packs.

Max. String capture length

Maximizes the length of captured strings (e.g. method parameters, URIs etc.). Strings exceeding the specified length are truncated to the specified length.

Synchronization threshold [ms]

If a thread already ownes a monitor, the time calculated for entering the monitor may mislead the user. The synchronization threshold is therefore used to differentiate between blocking and non blocking synchronization. If non blocking calls show up in the synchronization view, the threshold is set too low. Synchronization diagnosis must be enabled to change the threshold, see Sensor Plaecment .

PurePath-Percentage [0-100%]

The PurePath percentage denotes the ratio of traced PurePaths vs. skipped PurePaths. E.g. for Web applications, where the starting point of PurePaths are the Servlets/JSP, it is equivalent to the ratio of traced and skipped HTTP requests.

Sensor Configuration

The table "Sensor Configuration" enables adjusting the settings of individual Sensor Packs.

Capture

The capturing state of a Sensor Pack can be set to "inactive", "active" and "active and start PurePaths". The capturing state "inactive" deacitvates all data capturing activities of a Sensor Pack. An "active" Sensor Pack performs data capturing and data collected by the Sensor Pack are sent to the server for analysis. When a Sensor Pack is in the state "active and start PurePaths", it gathers information and starts a PurePath when the corresponding method is called.

Note: Sensor state can be changed WITHOUT having to restart the SUD or using the Hot Sensor Placement feature.

Sensor Pack Specific Configuration

Some Sensor Packs provide specific configuration options which can be accessed and changed by selecting "Properties…" in the column "Options" The availiable Sensor Pack specific configuration options are listed below:

• EJB Invocation: Specify if setter and getter methods should be ignored. • JDBC: Specify if bind values should be captured; specify max. length of captures SQL

commands. Commands exceding the specified length are truncated. • Servlets: Specify filters to include or exclude URIs matching specified patterns, specify

capturing servlet attributes. • Java JDK Logging and Log4J: Specify filters to include or exclude logging events,

based on logging seveverity levels. • JMS: Enable capturing of message contents. • Exception: Specify filters to include or exclude exceptions, based on the class of the

exception.

6.3.4.3. Method Sensor Rule Configuration

Overview

By default dynaTrace Diagnostics inserts Sensors on all important component interfaces. In order to diagnose performance issues deeper in the application, at the package, class or method levels, Sensor Rules can be used. In order to know what packages, classes and methods are available to instrument, dynaTrace Diagnostics provides a Discovery Run which locates all

packages of the application. The Sensor Rule configuration is used to gather information about specific packages, classes and methods. Additionally, dynaTrace Diagnostics Sensor Rules can capture specific method arguments which are very useful in diagnosing issues.

Sensor rules are specified and are grouped into a Ruleset. Rules which are added to a Ruleset are prioritized by their order, top down. As traffic passes through the sensor the rule that matches first, is the first and only one applied to that traffic. Rules can be moved up and down in order and priority, even methods within a rule can be prioritized. See order of execution below for more details.

Note: Rulesets have lower priority than enabled Sensors. E.g. if a EJB Method is excluded which is specified in the EJB Sensor, the exclusion is overwritten.

It is recommended that only packages, classes or methods which are really critical in terms of performance are added to the Ruleset, otherwise there will be a surplus of non-essential information which has to be processed.

For Applications, which are not based upon Servlet communication, e.g. Rich Clients, the starting point for the recording the PurePaths must be determined. The Ruleset can be used to define the specific method from which to start PurePaths tracing.

A Ruleset defines the methods that get instrumented by the Diagnostics Server. These Rulesets are stored server-side in the dynaTrace Diagnostics 2.0/conf directory as

<profile_name>.profile.xml files. A Ruleset consists of a number of class rules, each of them respectively consists of a number of method rules.

A custom Sensor Pack can be generated out of one or more Class Rules or Method Rules with

the "Generate Sensor Pack…" button . The new Sensor Pack is listed within the Sensor Placement View and the Sensor Configuration View and can be manipulated within these views in the same way as predefined Sensor Packs. The rules used to generate the new Sensor Pack are removed from the list of Method Sensor Rules.

Figure: Sensor Rule Configuration

Class Browser

The Class Browser provides a convenient way to define Class Rules and Method Rules. A tree view which reflects the package structure of the classes loaded by the SUD is created, which enables the selection of packages, classes, interfaces and methods. A Class rule is generated for each selected tree node representing a package, class or interface, and a method rule is generated for each selected method node. This enables quick generation of multiple Class Rules and Method Rules.

To narrow set of displayed classes, the Class Browser can be restricted to the classes related to a specific Diagnostics Agent. Additionaly, the view can be filtered to show only classes, interfaces or methods.

The quick search functionality can be used to search the tree for classes, interfaces or methods that match a specific search string.

Based upon an SUD´s loaded classes, which have been captured by a discovery run, the Class Browser provides the ability to select rules by simple mouse clicks.

Figure: Class Browser

Patterns

Both Class and Method Rules do not necessarily specify concrete names of classes/methods. Instead they use patterns which are evaluated when the names of the current class and method are available.

These patterns can be specified using one of the following modes:

• equals: the pattern applies if the actual name is equal to the pattern text • starts: the pattern applies if the actual name starts with the given pattern text • ends: the pattern applies if the actual name ends with the given pattern text • contains: the pattern applies if the actual name contains the given pattern text • regex: this mode allows the user to use regular expressions e.g. Class[0-9]+ to

specify all classes that start with Class followed by any number

Class Rules

A Class Rule defines the container for a number of Method Rules. These Method Rules are evaluated with respect to the Class Rule they are defined within. By specifying a Class Rule with an empty pattern, all classes are affected. A Class Rule whose selection pattern ends with a dot is a Package rule and matches all classes within the specified package. Additionally, the runtime technology (Java or .NET) has to be selected. Note that dynaTrace Diagnostics also supports systems with heterogenous technology.

Class Rules are specified by patterns that reflect the fully qualified class name (e.g. java.lang.Thread) and can also define interfaces or packages. Class Rules can be set to active or inactive.

Note: By specifying a package with mode "equals" only classes contained in that package are concerned, sub-packages are ignored.

Delegation Suppression

When Delegation Suppression is turned on, the Method Rules contained in that Class Rule are combined to one logical group. Each time one method, matching one of these rules, calls another method, matching these rules, directly, only the first call is shown in the corresponding PurePath. E.g. a method read() should be instrumented in one specific class and all of its super-classes (this could be done by using inheritance modes, described below) and this method makes a call to the method read() of its super-classes. As a result, there would be a chain of read() method calls in the PurePath. To get a clearer PurePath, one could use Delegation Suppression to make all the following calls to read() disappear in the PurePath.

Method Rules

A Method Rule defines one or more methods and the way they should be instrumented. By specifying a Method Rule with an empty pattern, all methods are affected. (Note: Constructors are excluded by default. To specify a Constructor to be instrumented, the pattern has to be set to "<init>"!) Method Rules are declared by the following properties:

State

The current state of a Method Rule; can be one of the following:

• include: methods affected by this rule should be instrumented using the given sensor type

• exclude: methods affected by this rule should not get instrumented • inactive: this rule is currently inactive

API

Allows the user to specify an API name that corresponds to the methods affected by this Method Rule. Using this API name dynaTrace Diagnostics is able to calculate aggregated information about a specific API.

Visibility

Defines the visibility of methods that get instrumented (public, default, protected, private).

Inheritance

By using this option, it is possible not only to instrument methods of a specified class but also to instrument methods of super- or sub-classes. The following modes are available:

• this method: only methods are instrumented where the containing class matches the corresponding Class Rule

• inherited methods: all methods are instrumented where the containing class matches the corresponding Class Rule or the containing class extends or implements a class that matches the corresponding Class Rule (e.g. by declaring the method toString() of java.lang.Object to be instrumented with inherited methods, the method toString() of every class would get instrumented)

• super methods: all methods are instrumented where the containing class matches the corresponding Class Rule or the containing class is a super class to a class that matches the corresponding Class Rule (e.g. by declaring the method equals() of java.lang.String to be instrumented with super methods, the method equals() of java.lang.Object would get instrumented, too)

• automatic: if the pattern of the corresponding Class Rule is known to be an interface, the mode inherited methods is used, otherwise this method is applied

Note: At runtime, it is not always assured that the complete inheritance hierarchy of an introspected application is known. Especially when a program is introspected for the first time, it is most likely that method rules using inherited methods, super methods or automatic are not correctly applied. In this case restarting the application under introspection will most likely solve the problem because dynaTrace Diagnostics remembers the inheritance hierarchy of introspected applications.

Note: It is possible to specify Method Rules in a Class Rule, although no methods matching these Method Rules are contained in a matching class. For example one can create a Method Rule with pattern substring() for a Class Rule with pattern java.lang.Object .

This does not seem to make sense, but when using this Method Rule in mode "inherited methods", the method substring() of java.lang.String will get instrumented, because java.lang.String extends java.lang.Object .

Record synchronization time

The time spent on synchronization in methods that match the instrumentation rule will be recorded. This includes block times of synchronized statements/methods and wait times of Object.wait(). This Option is only enabled if synchronization diagnosis is activated, see Sensor Placement .

Only instrument method when synchronization happens

The matching methods are only instrumented if the method is synchronized or the method contains synchronization code. Option is only enabled if synchronization diagnosis is activated, see Sensor Placement .

Capture Events

Toggle the capturing state of methods instrumented due to this rule. If event capturing is disabled, the sensors placed due to this rule are disabled. The capturing state can be changed during runtime.

Capture Return Values

When this option is enabled, every time a matching method is called, the return value is recorded and shown in the corresponding PurePath.

Allow to start PurePath from this method (Entry Point)

By enabling this option it is assured that every call to matching methods will be shown in a PurePath.

Argument Rules

By specifying Argument Rules, the user can limit the matching methods to those which have the given argument types. Additionally the user can specify one argument that will be captured every time matching methods are called and will be shown in the PurePath.

Order of execution

In order to create adequate Rulesets, it is important to understand the way dynaTrace Diagnostics evaluates them. There are a few simple rules dynaTrace Diagnostics applies, to determine a Method Rule for a given method:

• Rulesets are evaluated from the first Method Rule to the last one • all matching including Method Rules are applied until the first excluding Method Rule

occurs • if no Method Rule matches, the method will not be instrumented

Note: By using the mode "inherited methods" or "super methods" the methods of the matching class are always included. If for some reason the methods of the matching class should be excluded from instrumentation, you have to prepend a Method Rule that excludes the methods from the specified class in mode "this method".

6.3.4.4. Memory Sensor Rule Configuration

Overview

enables monitoring of instanciations of specific classes and deserialisation events of instances of specific classes. The classes that are included to memory monitoring are selected by Memory Sensor Rules. Memory Sensor Rules are configured similar to Class Rules, see Method Sensor Rules . The memory monitoring data of the selected classes is displayed in the Selective Memeory view .

Figure: Sensor Rule Configuration

Class Browser

The class browser can be used to define Memory Sensor rules in the same way as Class Rules, please refer to Method Sensor Rules for details.

Memory Rules

Memory Rules can be specified for a class or a package similar to Class rules, using patterns as, as described in Method Sensor Rules . The sensors associated to a Memory Rule can be activated or deactivated at runtime by toggling the "Activated" checkbox of the Memory Rule. If the checkbox "Include Inherited Classes" is enabled, memory monitoring sensors are placed in classes that match the selection pattern of the rule and in all direct or indirect base classes of that classes.

6.4. Overhead

This section explains how to configure an application to keep the overhead marginal. There are a number of factors impacting the overhead created by dynaTrace Diagnostics. They are:

1. The number of Sensors are injected in a system (active) are directly related to the overhead imposed on the system. The more sensors activated the more overhead created. Overhead can be reduced through disabling the capture flags next to the sensors in the application configuration manager. This can be done during runtime and is wrapped for applications running under J2SE 1.4 or J2SE 5.0 without restarting the application.

2. The number of deployed Diagnostics Agents is a significant factor that can impact overhead and application performance. The more Diagnostics Agent running the more measuring points and sensors that are set, which again increases the volume of data handled by dynaTrace Diagnostics.

3. The additional context information that is traced is another factor that affects overhead. Additional information like String automatic capturing, monitoring of log events and exception monitoring can create significant overhead. Please refer to sections Sensor

Configuration and Sensor Placement to find information on how to configure capturing of this and other context related information according to your needs.

To get to minimize the level of overhead, the following best practices are recommended:

1. Limit the sensors to the important ones. The question is how to find the relevant sensors. There are two approaches:

a. Top-Down approach: Start a Discovery Run with all sensors enabled and have a look at the captured paths, especially their length. If the path length exceeds a number of about 10,000 nodes, you have to consider which information is unnecessary. Disable methods and packages step by step to get a reasonable set of measurement points.

b. Bottom-Up approach: Ask the development team which interfaces, methods and components are critical key elements regarding performance. Start the diagnosis from these components. After running a discovery run and some testing you may figure out where to search for performance issues. Through the information you get from the discovery run you may add these methods and packages to your application configuration to reduce overhead. Reduce the measured methods step by step to get a reasonable set of measurement points.

2. Restrict the number of traced requests a. Servlet filter: Trace specific servlets for specific patterns. b. Set a specific percentage of traced requests: This option is advisable if a large

number of requests per second are recorded. This feature is configurable at runtime for agents running under J2SE 1.4 and J2SE 5.0. Furthermore, this approach to performance diagnosis is advisable for production systems because it provides a statistical overview of system performance health.

6.4.1. Discovery Run

The most important benefit of the Discovery Run , identifying the packages, classes and methods of the SUD, was already mentioned in the chapter Overhead . In addition, the Discovery Run enables the registration of all Diagnostics Agents deployed to the SUD to the System Profile that corresponds to the SUD. After a Discovery Run dynaTrace Diagnostics can determine how classes are associated to each other and which methods have to be instrumented. Otherwise it may be possible that some methods are not instrumented by the standard Sensors .

Recommended Approach

1. First of all start the SUD with the default dynaTrace Diagnostics configuration. During the Discovery Run the SUD should be used the same way it is used when monitoring is activated. Eg. if a set of test cases should be used to provide load for performance monitoring, run the test case set also during the Discovery Run. If you want to use

dynaTrace Diagnostics to analyze Load Testing sessions then start a short load test that will run during the Discovery Run. This will help dynaTrace Diagnostics to detect all methods which have to be instrumented and to load all classes which are important afterwards.

2. After the Discovery Run the application should be restarted so that dynaTrace Diagnostics is able to instrument all methods correctly.

Aided by the Discovery Run, dynaTrace Diagnostics identifies and remembers the packages, classes and methods used by the SUD. This information is used by dynaTrace Diagnostics to determine which methods should be augmented with instrumentation code.

6.4.2. Diagnostics Server Health Status

Overview

The Diagnostics Client displays the Diagnostics Server Health information via a status control that shows the actual amount of measurements processed by the Diagnostics Server per second (Mps). The displayed value includes the measures received from all Diagnostics Agents of all currently monitored SUDs. The control is located in the Diagnostics Client status line and is only visible if the Diagnostics Server is available.

The value of Mps will be automatically updated based on the display update interval, which is specified in the Diagnostics Client preferences. The image of the status control indicates the actual Mps state of the Diagnostics Server.

States of measurements per second (Mps):

• Ok : The Diagnostics Server is working in a stable state. • Warning : The actual value of measurements per second reached an alerting value. • Cirtical : The Diagnostics Server is overloaded. Try to reduce the amount of

measurements by optimizing the sensor settings of your Application Profile .

6.5. System View

Overview

The System View provides information and a visual representation of all agents, their properties and the appropriate deployed sensors . To open this view, double-click on the desired System Profile from the cockpit window.

The system view, on the right part of the screen is divided in two ranges. The top half provides following tabbed information.

Visualization

The visualization tab provides an overview of the agents registered to the System Profile and the state of the agents. Agents can be assigned different visualization icons reflecting the functionality of the monitored system component, to illustrate the system architecture. Additionally, the state of the agents are indicated in this view by a state indicator which is displayed at the lower left corner of the agent visualization icons. Following agent states are displayed:

• Agent not connected: No state indicator icon

• Agent connected and capturing:

• Agent connected but capturing disabled by user:

• Agent connected but unknown state:

• Agent connected but capturing dissabled due to license problems:

Diagnostics Agent s that are registered to the System Profile are displayed within the visualisation view. Additionally, connected agents that are not not assigned to any System Profile are displayed in the visualization view of every System Profile until they are assigned to a System Profile.

Figure: Agent Visualization

In case of discovering a new Diagnostics Agent, the following dialog appears:

Figure: Agent discovery dialog

Within this dialog choose an available System Profile from the drop down list to create an Diagnostics Agent configuration for the new discovered agent and apply it to the selected System Profile. The currently selected System Profile is selected by default. The drop down list additionally offers the option to create a new System Profile for the connecting .

After the "Add Now" button is pressed the Diagnostics Agent configuration dialog is opened. If the drop down list option "New System Profile" has been selected, the System Configuration dialog is displayed, for detailed information about system profile configuration, please refer to chapter Configure System .

The "Add Later" button closes the dialog without changing any configuration settings. The new discovery Diagnostics Agent will use the default Diagnostics Agent configuration of the active System Profile and has to be configured manually on demand.

Instances

The instances tab (see below) provides information about the connected Diagnostics Agent in tabluar form. Each table row describes the state of a connected Diagnostics Agent that is assigned to the selected System Profile.

The instances table provides following Diagnostics Agent state information:

• Agent status: indicates capturing state of the . (capturing, capturing disabled by user or due to license problem)

• Instance: name, host and number of an agent in the format: <name>@<host>:<number> • Technology: indicates the runtime technology of the SUD component the Diagnostics

Agent is monitoring. (Java or .NET) • Host: hostname of this agent • Started: starting time of this agent • Event Count: number of events sent by this agent • Class Load Count: number of classes loaded by the JVM corresponding to this agent • Connected: indicates whether this agent is currently connected or disconnected • License: indicates whether the current license is valid or invalid • Capture: indicates whether capturing is currently enabled or disabled • Configuration: profile configuration that is used by this agent • Skipped Events: number of events that are skipped for this agent if saturation threshold

is exceeded • Skipped PurePaths: number of pure paths that are skipped for this agents if saturation

threshold is exceeded • Instrumentor Response Time Max: maximum time required to instrument a class

(column is hidden by default) • Instrumentor Response Time Avg: average time required to instrument a class

(column is hidden by default)

The bottom half provides the tabs, "Breakdown Chart", "Agent Properties" and "Deployed Sensors".

Breakdown Chart

This Tab provides information about the distribution of the monitored response time over the different APIs at certain points in time.

With the button , realtime charting can be switched on/off.

Agent Properties

This Tab provides detailed information about the environment of the Diagnostics Agent currently selected in the instances table.

• Operation System: operating system of the selected agent • OS Architecture: processor chipset of the agentÂ´s operating system • OS Version: operating system version • Virtual Machine: name of the virtual machine the agent is running in • VM Version: virtual machine version • VM Vendor: virtual machine vendor • Java Version: version of the agentÂ´s Java platform • Java Vendor: vendor of the agentÂ´s Java platform • Processors: number of processors in the agentÂ´s system • Maximal Memory: maximal amount of memory available for agent • Agent Host: name of agentÂ´s host • Agent Version: build version of the agent • HiResClock: indicates the availability of high resolution timers at the agent's SUD • Hot Sensor Replacement: indicates if the runtime system of the SUD enables hot

sensor replacement

Deployed Sensors

This Tab provides information about the instrumented methods for the selected Diagnostics Agent instance. With right-click on the instrumented method the class which contains this method can be decompiled.

• Method: method name • Class: name of the class containing the method • Arguments: argument types of the method • Returns: return type of the method • Api: API(s) assigned to this method • Sensor: sensor(s) applied to this method • Flags: access modifiers for this method (Pub = public, Pro = protected, Pri = private, Sta

= static, Nat = native, Fin = final, Syn = synchronized, Str = strict) • Source File: name of the source file which contains the method • Line Number: linen umber of the method within the source file

The Deployed Sensor tab can also be used to view decompiled versions of the instrumented classes. To view the decompiled code of a class, right-click it within the Deployed Sensor table and select one of the menu items "Decompile Byte Code", "Decompile Source Code", or "Decompile Mixed". "Decompile Byte Code" opens a view containing a byte code representation of the class, "Decompile Source Code" opens a view containing a Java or C# source code representation of the class, and "Decompile Mixed" opens a view containing both byte code and source code. Use the menu entry "Save Byte Code" to save the byte code to a file. Note the original class byte code is saved and used for decompilation, so no instrumentation code is visible.

6.6. Hot Update

If the active configuration of an System Profile is changed, only classes loaded after the configuration change are instrumented according to the new configuration settings. Classes loaded and instrumented prior to the configuration change do not reflect the configuration

change. The Hot Sensor Placement feature, available for all agents running under J2SE 5.0 or later, applies the Sensor Configuration , and Sensor Rulesets defined in the activated configuration also to the classes loaded prior to the configuration change. The Hot Update feature also supports selective removing of sensors, without the need to resater the SUD, which is valuable for the application of dynaTrace Diagnostics in production environments.

Hot Update works on the method layer. All methods continue to execute the original code, even during and after the hot update until completion. Methods that start after the Hot Update will run the new code with either the added or removed sensors.

dynaTrace Diagnostics allows changing the capturing behavior of Sensors without a hot restarting the application. This topic is described in the following chapter Immediate Configuration .

Note: A detailed overview about configuration changes and which action to execute for your changes to take effect is provided in Chapter Configuration Matrix .

6.7. Immediate Configuration

The instrumentation sensors of dynaTrace Diagnostics are designed in a way to support flexibility in terms of data capturing, without the need of code alterations, helping to reduces the number of required hot updates or SUD restarts to a minimum. The following list comprises the sensor settings that are propagated immediately to the respective sensors, without the need of a SUD restart or a Hot Sensor Placement:

• Sensor Capture Mode • Pure Path Percentage

• Sensor Property Configuration • Measure Subscriptions • Thresholds • Capture Events • Check PurePaths for exception events • Check PurePaths for logging events

Note: A detailed overview about configuration changes and which action to execute for your changes to take effect is provided in Chapter Configuration Matrix .

6.8. Configuration Matrix

The table below points out how and which configuration changes needs to be conducted and which classes are affected.

System under Diagnosis (SUD)

Configuration Immediate Hot Sensor Placement

SUD Restart

Sensor Configuration: Sensor Pack Capture Mode x

Sensor Configuration: PurePath Percentage x

Sensor Configuration: Max. String Length x

Sensor Configuration: Synchronization Threshold x

Sensor Configuration: Capture Events x

Sensor Configuration: Sensor Property Configuration x

Measures: Measure Subscriptions x

Measures: Thresholds Configuration x

Transactions: Transaction Configuration x

Incidents: Incident Configuration x

Charts: Chart Configuration x

Method Sensor Rules: Method Sensor Rules Configuration J2SE 5.0

x

Sensor Placement: Capture Strings automatically J2SE 5.0 x

Sensor Placement: Ignore getter and setter methods J2SE 5.0 x

Sensor Placement: Place Sensor J2SE 5.0 x

Sensor Placement: Place Sensor J2SE 1.4 x

Configuration: Communication Mode x

Sensor Placement: Enable synchronization diagnostics x

Method Sensor Rules: Method Sensor Rules Configuration J2SE 1.4

x

Memory Sensor Rules: Memory Sensor Rules Configuration x

Sensor Placement: Capture Strings automatically J2SE 1.4 x

Sensor Placement: Ignore getter and setter methods J2SE 1.4 x

Method Sensor Rules: Method Sensor Rules Configuration .NET

x

Sensor Placement: Capture Strings automatically .NET x

Sensor Placement: Ignore getter and setter methods .NET x

.NET Agent Configuration Tool: Change .NET Agent settings x

The following configuration table points out which Sensor Packs transfer instrumentation changes to the SUD after a Hot Sensor Placement. Note: Only SUDs running with J2SE 5.0 and higher are Hot Sensor Placement-able

Hot Sensor Placement-able

Sensor Pack Yes No

RMI Tagging x

EJB Invocation x

JNDI x

Remote Method Invocation (RMI) x

JDBC x

Servlets x

Java Web Services x

HTTP URL Connection Tagging x

Hibernate x

JTA x

XA x

JMS Receive Entry Point x

JMS Tagging x

Java JDK Logging and Log4J x

Memory x

JMS x

Java Method Invocation x

Exceptions x

ADO.NET x

.NET x

.NET Tagging x

ASP.NET x

.NET Web Service Tagging x

.NET Logging x

AWT x

.NET Remoting x

JMX MBean Server x

Thread Start Tagging x

Executor Tagging x

Collection x

Struts x

Map x

7. Monitoring, Business Transactions, Incidents

Overview

dynaTrace Diagnostics provides functionality to monitor application performance metrics and to generate notifications if observed values indicate performance issues. Thresholds are used to specify the expected range of observed values, and incidents can be defined to notify user if this range is exceeded.

dynaTrace Diagnostics automatically collects monitoring data for measures that are subscribed within the active profile. For information about subscribing measures, please refer to section Measures of chapter Configure System . To reduce the amount of generated data, dynaTrace Diagnostics aggregates monitoring data received within standard monitoring intervals. Data aggregation is performed in a way that preserves the statistical value of the monitoring data. Minimum, maximum, average and sum of tha values received during monitoring interval are maintained.

The monitoring data can also be accessed through dynaTrace Diagnostics´s real-time charting component, which provides various options to visualize the aggregated monitoring data. Charting features enable selection and drill down into desired intervals and integration of multiple metrics for visual correlation analysis.

Business transactions provide powerful filtering mechanisms, based on measurement values. They enable filtering and grouping of measuremnt values and defining dependencies between measurement values from different measures. This features ease extraction of statistical data about user defined business cases, like e.g. how many times a specific product was sold or the number of different users logged in during a given time period. A business transaction may produce filtered measurement data, which is provided via an automatically generated measure.

Incidents enable a flexible mapping between measuremen threshold violations and actions. Threshold violations of multiple measuremets can be logically combined, which enables conditional incidents that are raised e.g if all specified threshold violation occur simultanousely. Multiple actions can be assigned to incidents, like storing the current session Various mechanisms for user notification, ranging from incident logs which appear in the incident view to email based notification are available. Incident detection employs methods to evaluate the stability of the threshold violation state of monitored measurements, to avoid unneccessary execution of actions caused by instable threshold states.

7.1. Measure Configuration

Overview

The time series analysis mechanism enables observation of specific application parameters such as concrete methodÂ´s response times over time. Based on the obtained measure data, charts may be created to compare different metrics against each other. A meaningful example would be the correlation of memory consumption, garbage collector activities and a specific methodÂ´s response time. For exporting those charts see the chapter Reporting .

Thresholds can be define to specify value ranges for measurements. Those thresholds are used to determine if observed values are outside an acceptable range and incidents have to be raised. For detailed informaton on defining incidents, please see chapter "Incidents". Measurement data can be accessed through Charts and Notifications interactively and through the JMX interface which exposes time series data to external applications for further processing.

To start monitoring a specific application value, a measure for the application value has to be subscribed. Measure are available for a broad range of technologies like RMI, JDBC, JMS, EJB, Servlets, WebServices and JNDI as well as user defined APIs, selected methods and Virtual Machine specific health information. Data collection for subscribed measures starts immediately if an appropriate AUD is connected, or after connection of an AUD if none is connceted.

dynaTrace Diagnostics Measure Configurations provide the special metric API Execution Time, which shows the distribution of the real-time execution time of a PurePath over different APIs. Examples for predefined APIs are "Servlet" and "WebService" for the presentation tier, "App" and "RMI" for the business logic tier and "JDBC" and "ADO.NET" for the database tier. The list of APIs can be extended by user defined APIs. API membership of methods is defined on base of method rule, which is described in section "Sensor Rule Configuration" of chapter "Configure System". After receiving a complete PurePath dynaTrace Diagnostics calculates the execution time for every API in the PurePath to give a percentage based breakdown of performance. The total performance is assembled from waiting time and execution time of the particular PurePath. For charting the metric, the average execution time of an API is calculated from all PurePaths within ten second time intervals. This feature provides the ability to observe the relative performance of an API over a longer time period. The API Execution Time and API Execution CPU Time are shown automatically in the Application View .

Measure

Data aquisition for measurements is enabled by associating them with a &qout;System Profile" by subscrbing them within a profile configuration. Some measure subscriptions are automatically set up through configuration actions. Specifically, creating a new application profile and defining its tiers sets up default configurations of measure subscriptions. To view set of current measure subscriptions right-click on the desired application from within the cockpit, choose "Properties" - "Configuration" - "Measures". By default Java Virtual Machine Metrics and common APIs Execution and Execution CPU Time Metrics are presubscribed.

To subscribe to measures for an Application, right-click on the desired application and choose "Properties" - "Configuration" - "Measures", which opens the Application Configuration Manager. To subscribe a measure to the application choose "Add". The "Measure Configuration" dialog

will be opened which displays the available metric groups, containing all available metric. To subscribe a measure, expand a metric group, select the desired metric, provide measure parameters and right-click "Add". Some diagnose views like PurePath, API, Notification, RMI, JNDI, EJB, Database, Servlet, JMS and WebService allow subscribing the selected elements directly via the context menu.

A measure consists of a metric combined with General and Metric Specific Attributes. See below for definitions of these attributes.

By default, measurements are stored for 24 hours on server-side. Values older than one day, will be discarded. The observation data for a measure covering a 24 hour period, requires approximately 300kB. Clearing the system session, will also delete all measurements of measures subscribet by the system, however the measure subscribtions remain.

Interval Measurements

dynaTrace Diagnostics uses ten second time intervals as a standard measurement bucket for maintaining performance information about the application. Providing a standard interval enables meaningful and valid comparative analyses that lead to root cause identification. dynaTrace Diagnostics uses a commonly accepted method for aggregating data into the time intervals that make it easy to integrate result data into other monitoring applications.

Measures are recorded based on when the call that impacts that measure was made and the result impacts the measures for that interval If the method is called exactly one time in an interval the minimum, average and maximum value of this measure is the same. If the method is not called within the interval there is no measure point for this interval. If there are multiple method calls in the interval, the minimum, maximum and average values are set accordingly. In charting, lines are drawn between actual measured points passing through intervals with no measurements. To retrieve values from a previous measure point, the measure point must be selected by clicking on it. Additionally charts can reflect multiple value sets like the minimum, average and maximum for any measured. The measure can be subscribed multiple times to the chart and the value for drawing can be selected in the Series Properties.

General Configuration

The General Configuration Attributes provide flexibility to collect multiple series of measurement data across the profile configuration with one subscription. Diagnostics Agent s that provide measurement data for the measure can be selected with the field "Agent". The entry <all-agents> assigns all agents known to the system configuration to the measure. Entries ending with @<all-hosts> assign all Diagnostics Agents with a specific name to the measure, regardless of the Diagnostics Agents host. Entries that specify agentname and hostname identify one Diagnostics Agent (or one group of Diagnostics Agent s when clustered).

Thresholds

Thresholds are used to define ranges of measurement values that indicate normal conditions, warning or severe conditions. Thresholds are also used for the evaluation of Business Transactions and Incident Rules .

• Upper Severe: The upper severe bound for the metric. • Upper Warning: The upper warning bound for the metric. • Lower Warning: The lower warning bound for the metric. • Lower Severe: The lower severe bound for the metric.

Metric Specific Configuration

Database Metrics

Database Specific Attributes:

• SQL Statement: The SQL statement that qualifies the measure. (optional)

Time Represents the time that has been spent by the database connection component and the database management system.[ms]

CPU Time: Represents the CPU time that has been spent by database connection component and the database management system. [ms]

Execution Count: Represents the number of executed statements regardless if the statement has been prepared before.

Preparation Count: Represents the number of preparations that have occurred.

Exception Metrics

Exception Specific Attributes:

The measure configuration dialog provides two ways of declaring a method. Entering the full-qualified classname, the methodname and its arguments manually, or by the use of the browse function which presents a dialog box.

• Throwable Class: The fully qualified class name of the desired Exception to measure.

Count: Represents the number of thrown Exceptions, specified via a measuresÂ´ throwable class attribute, within a sample interval.

Virtual Machine Metrics

CPU Process Time per sample interval:

Represents the CPU time used by the process is which the Java Virtual Machine is running during the last sample interval (10 seconds). [ms]

Thread Count: The current number of live threads including both daemon and non-daemon threads.

Committed Memory: Represents the amount of memory that is guaranteed to be available for use by the Java virtual machine. [kilobyte]

Used Memory: Represents the amount of memory currently used. [kilobyte]

Max Memory: Represents the maximum amount of memory that can be used for memory management. [kilobyte]

Loaded Classes: The number of classes that are currently loaded in the Java virtual machine.

UnLoaded Classes: The total number of classes unloaded since the Java virtual machine has started execution.

GC Collection Time per sample interval:

Represents the approximate accumulated elapsed collection time during the last sample interval (10 seconds). [ms]

GC Activations per sample interval:

Represents the total number of collections that have occurred during the last sample interval (10 seconds).

Memory Pool:

Currently used, committed or max memory of a specific memory pool. [kilobyte] Metric specific parameters:

• JVM: The type of JVM of the Diagnostics Agent. (Sun, IBM or JRockit)

• Memory pool: Specifies the memory pool to monitor. (eg. Eden Space, Survivor Space etc.)

• Memory pool value: The memory pool value to monitor. (used, max or comitted)

Specific GC Activations per sample interval:

Number of activations of a specific grabege collector during the last sample interval (10 seconds). Metric specific parameters:


• Garbage collector: Specifies the garbabe collector to monitor. (eg. Copy, Mark Sweep Compact etc.)

Specific GC Collection Time per sample interval:

Accumulated time required for garbage collection by a specific garbabe collector during the last sampe interval (10 seconds). [ms] Metric specific parameters:


• Garbage collector: Specifies the garbabe collector to monitor. (eg. Copy, Mark Sweep Compact etc.)

API Breakdown Metrics

API Specific Attributes:

• The API name that qualifies the measure. The name has to match an API defined by the ruleset. (optional)

Execution Time: Represents the time that has been spent on methods of the given API without calls to other APIs. [ms]

Execution CPU Time: Represents the CPU time that has been spent on methods of the given API without calls to other APIs. [ms]

WebService Metrics

WebService Specific Attributes:

• End Point: Measuring a client-side WebService component, this field describes the URI to the targeted WebService. Measuring a server-side WebService component, this field describes the the fully qualified name of the class declaring the exported WebService method. (optional)

• Method: The method that is invoked via a WebService call. This method is usually exported via a WSDL. (optional)

Time: Represents the time that has been spent for the declared WebService including all further calls. [ms]

Bytes Received: Represents bytes received by the WebService. [byte]

Bytes Sent: Represents bytes send by the WebService. [byte]

Number of calls of the declared Web Service per PurePath:

Represents the number how often the declared WebService has been invoked from a PurePath.

Remoting Metrics

Attributes Specific for Remoting:

The measure configuration dialog provides two ways of declaring a method. Entering the full-qualified classname, the methodname and its arguments manually, or by the use of the browse function which presents a dialog box.

• Class: The fully qualified class name. (optional) • Method: The name of the targeted method without braces. (optional) • Argument: The arguments the method matches. Leaving this field empty points to a

method without arguments. (optional)

Bytes Sent: Represents the number of bytes that have been sent. [byte]

Bytes Received: Represents the number of bytes that have been recieved. [byte]

Objects Sent: Represents the number of objects that have been send by the declared method.

Objects Received: Represents the number of objects that have been recieved by the declared method.

Serialized Objects: Represents the number of objects that have been serialized by the declared method.

Deserialized Objects: Represents the number of objects that have been deserialized by the declared method.

Serialization Time: Represents the spent time for serializing object by the declared method.

Deserialization Time: Represents the spent time for deserializing object by the declared method.

Time: Represents the time for the declared RMI method including all further calls and remote calls to complete. [ms]

Method Metrics

Method Specific Attributes:

The measure configuration dialog provides two ways of declaring a method. Entering the full-qualified classname, the methodname and its arguments manually, or by the use of the browse functionality.

• Class: The fully qualified class name. (optional) • Method: The name of the targeted method without braces. (optional)

• Argument: The arguments the method expects. Leaving this field empty configures to a method without arguments. (optional)

Time: Represents the elapsed time taken by the declared method including further method calls. [ms]

CPU Time: Represents the CPU time spent for the declared method including further method calls to complete. [ms]

Argument Value:

Represents the number of calls of a method with a specific argument value within a PurePath. Used for Business Transactions. Metric specific parameters:

• Argument: specify the argument to use for comparison • Evaluation: specify how the argument is evaluated (as string

value, numeric value, or occurence) • Value: value used to compare with actual argument value • Case sensitive: define if comparison should be case sensitive

or not (only active for string typed arguments) • Ignore Whitespaces: define if comparison should ignore

whitespaces (only active for string typed arguments) • Match: specify the comparison relation to use

Invocation: Represents the number of calls of a method within a PurePath. Used for Business Transactions.

Return Value:

Represents the number of calls of a method with a specific return value within a PurePath. Used for Business Transactions. Metric specific parameters:

• Evaluation: specify how the argument is evaluated (as string value, numeric value, or occurence)

• Value: value used to compare with actual argument value • Case sensitive: define if comparison should be case sensitive


whitespaces (only active for string typed arguments) • Match: specify the comparison relation to use

Logging Metrics

Logging Specific Attributes:

• Severity: the severity level used to filter logging events.(optional)

Count: Represents the number of logging events with the specified severity level. All logging events are counted if no severity level is specified.

Web Requests Metrics

Web Requests Specific Attributes:

• URI: Declares the URI which addresses the servlet. (optional) • Query: Declares the query string to match on. If this field is left empty, any servlet call to

the declared URI matches. (optional)

Time: Represents the time to process the declared servlet methods including further method calls. [ms]

Count: Represents the number of times a method of the declared servlet has been invoked.

Header Value:

Indicates if the declared servlet was invoced with a specific header field set to a specific value within a PurePath. Used for Business Transactions. Metric specific parameters:

• Header Field: specify the name of the header field used for comparison

• Evaluation: specify how the argument is evaluated. (as string value, numeric value, or occurence)

• Value: value used to compare with actual argument value. • Case sensitive: define if comparison should be case sensitive


whitespaces (only active for string typed arguments) • Match: specify the comparison relation to use.

Parameter Value:

Indicates if the declared servlet was invoced with a specific parameter set to a specific value within a PurePath. Used for Business Transactions. Metric specific parameters:

• Parameter: specify the name of the parameter used for comparison



or not (only active for string typed arguments)

• Ignore Whitespaces: define if comparison should ignore whitespaces (only active for string typed arguments)

• Match: specify the comparison relation to use.

Request Attribute Value:

Indicates if the declared servlet was invoced with a specific request attribute set to a specific value within a PurePath. Used for Business Transactions. Metric specific parameters:

• Request Attribute: specify the name of the request attribute used for comparison





Servlet Context Attribute Value:

Indicates if the declared servlet was invoced with a specific servlet contect attribute set to a specific value within a PurePath. Used for Business Transactions. Metric specific parameters:

• Context Attribute: specify the name of the context attribute used for comparison





Session Attribute Value:

Indicates if the declared servlet was invoced with a specific session attribute set to a specific value within a PurePath. Used for Business Transactions. Metric specific parameters:

• Session Attribute: specify the name of the session attribute used for comparison





URI Pattern Value:

Counts servlet invocation that match a specific URI pattern. Metric specific parameters:

• URI Pattern: specify regular expression to define a pattern to match servlet URIs

No other parameter apply.

Naming Service Metrics

Naming Service Specific Attributes:

• Lookup: Declares the lookup name that access should be measured. (optional)

Time: Represents the spent time looking up the declared name. [ms]

CPU Time: Represents the spent CPU time looking up the declared name. [ms]

Count: Represents the number of look-ups on the specified lookup name.

Message Metrics

Message Specific Attributes:

• Destination: The name of the Message destination, either a topic or queue, that can usually be found in an JNDI namespace. (optional)

Time: Represents the time spent invoking the specified destination. [ms]

Count: Represents the number of invocations of the specified destination.

Business Transaction Metrics

Measures based on Business Transaction Metrics are created automatically during creation of Business Transactions. It is not required to create such measures manually.

CPU Duration: Represents the CPU Duration of a PurePath matched by a Business Transaction. [ms]

Duration: Represents the Duration of a PurePath matched by a Business Transaction. [ms].

Value: The value of the measure an evluate condition of a Business Transaction is based on.

Process Performance Metrics

Current CPU Load: Percentage of total CPU load generated by monitored process

Current Overall Memory Consumption:

Amount of memory consumend by the monitored process. [byte]

Windows/.NET Perfmon Counters .NET Memory Consumption (NonPaged):

Amount of NonPaged memory used by the monitored .NET Process. [byte]

.NET Memory Consumption (Paged):

Amount of Paged memory used by the monitored .NET Process. [byte]

.NET Memory Consumption (Peak):

Peak memory usage of the monitored .NET Process. [byte]

.NET Memory Consumption (System):

Amount of System memory used by the monitored .NET Process. [byte]

.NET Memory Consumption (Virtual):

Amount of Virtual memory used by the monitored .NET Process. [byte]

.NET Processor Time (Total):

Percentage of total CPU time generated by monitored .NET Process.

.NET Processor Time (User):

Percentage of user CPU time generated by monitored .NET Process.

.NET Thread Count: Number of threads run by the monitored .NET process.

WebSphere PMI Metrics

EJB Activate Count

Number of activations of all EJBs (entity and stateful)

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "beanModule" • PMI module key name: "activates" • Aggregation: Sum

EJB Concurrent Live Count

Number of concurrently living EJBs

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "beanModule" • PMI module key name: "concurrentLives" • Aggregation: Sum

EJB Pooled Count

Number of pooled stateless and entity beans

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "beanModule" • PMI module key name: "poolSize" • Aggregation: Sum

JDBC Connection Pool Allocate Count

Total number of allocated connections

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "connectionPoolModule" • PMI module key name: "numAllocates • Aggregation: Sum

JDBC Connection Pool Percent Used

Average percentage of used connections in the pool

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "connectionPoolModule" • PMI module key name: "percentUsed" • Aggregation: Sum

JDBC Connection Pool Size

Size of the connection pool

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "connectionPoolModule" • PMI module key name: "poolSize" • Aggregation: Sum

JDBC Connection Pool Number of free connections in the pool

Free Size • Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "connectionPoolModule" • PMI module key name: "freePoolSize" • Aggregation: Sum

JCA Active Count

Number of concurrently active global transactions

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "j2cModule" • PMI module key name: "activeGlobalTrans" • Aggregation: Sum

JTA Active Count

Number of concurrently active global transactions

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "transactionModule" • PMI module key name: "activeGlobalTrans" • Aggregation: Sum

Thread Active Threads Count

Number of concurrently active threads

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "threadPoolModule" • PMI module key name: "activeThreads • Aggregation: Sum

Thread Declared Hung Count

Number of declared hung threads

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "threadPoolModule" • PMI module key name: "declaredThreadHung" • Aggregation: Sum

Thread Cleared Hung Count

Number of cleared hung threads

• Availablility: WebSphere 6.0, WebSphere 6.1 • PMI module name: "threadPoolModule" • PMI module key name: "declaredThreadHangCleared" • Aggregation: Sum

Thread Concurrent Hung Count

Number of concurrently hung threads

• Availablility: WebSphere 6.0, WebSphere 6.1

• PMI module name: "threadPoolModule" • PMI module key name: "concurrentlyHungThreads" • Aggregation: Sum

WebLogic JMX Metrics

JDBC Connection Pool Active Connections Average Count

Average number of connections used by applications

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "JDBCConnectionPoolRuntime" • MBean attribute name: "ActiveConnectionsAverageCount" • Aggregation: Sum

JDBC Connection Pool Active Connections Current Count

Number of connections currently used by applications

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "JDBCConnectionPoolRuntime" • MBean attribute name: "ActiveConnectionsCurrentCount" • Aggregation: Sum

JDBC Connection Pool Active Connections High Count

Highest number of concurrently used connections since creation of the pool.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "JDBCConnectionPoolRuntime" • MBean attribute name: "ActiveConnectionsHighCount" • Aggregation: Max

JDBC Connection Pool Connection Delay Time

Average time required to create a physical connection to the database. [ms]

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "JDBCConnectionPoolRuntime" • MBean attribute name: "ConnectionDelayTime" • Aggregation: Sum

EJB Pool Access Total Count

Total number of times a bean instance was requested from the pool.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "EJBPoolRuntime" • MBean attribute name: "AccessTotalCount" • Aggregation: Sum

EJB Pool Beans In Use Current Count

Total number of bean instances currently in use from the pool.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "EJBPoolRuntime" • MBean attribute name: "BeansInUseCurrentCount" • Aggregation: Sum

EJB Pool Pooled Beans Current Count

Number of currently available bean instances in the pool.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "EJBPoolRuntime" • MBean attribute name: "PooledBeansCurrentCount" • Aggregation: Sum

EJB Pool Miss Total Count

Number of times a request for a bean failed because no free instances were available in the pool.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "EJBPoolRuntime" • MBean attribute name: "MissTotalCount" • Aggregation: Sum

EJB Pool Timeout Total Count

Number of Threads received a timeout while waiting for an available bean instance from the free pool.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "EJBPoolRuntime" • MBean attribute name: "TimeoutTotalCount" • Aggregation: Sum

Execute Queue Execute Thread Current Idle Count

The number of threads assigned to the queue that are in the state idle.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "ExecuteQueueRuntime • MBean attribute name: "ExecuteThreadCurrentIdleCount" • Aggregation: Sum

Execute Queue Execute Thread Total Count

The total number of execute threads assigned to the queue.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "ExecuteQueueRuntime • MBean attribute name: "ExecuteThreadTotalCount" • Aggregation: Sum

Execute Queue Pending Request Current Count

The number of waiting requests in the queue.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "ExecuteQueueRuntime • MBean attribute name: "PendingRequestCurrentCount" • Aggregation: Sum

Execute Queue Serviced Request Total Count

The number of requests that have been processed by the queue.

• Availablility: WebLogic 8.x, WebLogic 9.x • MBean type: "ExecuteQueueRuntime • MBean attribute name: "ServicedRequestTotalCount" • Aggregation: Sum

Thread Pool Execute Thread Idle Count

The number of idle threads in the pool, not including standby threads and stuck threads.

• Availablility: WebLogic 9.x • MBean type: "ThreadPoolRuntime" • MBean attribute name: "ExecuteThreadIdleCount" • Aggregation: Sum

Thread Pool Execute Thread Total Count

The total number of threads in the pool.

• Availablility: WebLogic 9.x • MBean type: "ThreadPoolRuntime" • MBean attribute name: "ExecuteThreadTotalCount" • Aggregation: Sum

Thread Pool Hogging Thread Count

Number of threads that are currently hogged by a request. Hogged threads will be declared as stuck after the configured timeout.

• Availablility: WebLogic 9.x • MBean type: "ThreadPoolRuntime" • MBean attribute name: "HoggingThreadCount" • Aggregation: Sum

Thread Pool Pending User Request Count

The number of pending user requests in the priority queue. Requests from internal subsystems are not included.

• Availablility: WebLogic 9.x • MBean type: "ThreadPoolRuntime" • MBean attribute name: "PendingUserRequestCount" • Aggregation: Sum

Thread Pool Throughput

The average number of requests completed per second

• Availablility: WebLogic 9.x • MBean type: "ThreadPoolRuntime" • MBean attribute name: "Throughput" • Aggregation: Sum

Tomcat JMX Metrics

Manager Active Sessions

Number of currently active sessions

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "activeSessions" • Aggregation: Sum

Manager Session Counter

Total number of sessions created by the manager

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "sessionCounter" • Aggregation: Sum

Manager Session Max Alive Time

Longest time an expired session has been alive [ms]

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "sessionMaxAliveTime" • Aggregation: Max

Manager Session Average Alive Time

Average time that expired session had been alive

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "sessionAverageAliveTime" • Aggregation: Avg

Manager Rejected Sessions

Number of sessions that were not created because the maximum number of active sessions was reached

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "rejectedSessions"

• Aggregation: Sum

Manager Expired Sessions

Number of expired sessions

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "expiredSessions" • Aggregation: Sum

Manager Processing Time

Processing time spent for session management [ms]

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "processingTime" • Aggregation: Sum

Manager Duplicates

Number of duplicated session IDs

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Manager" • MBean attribute name: "duplicates" • Aggregation: Sum

Jsp Monitor Jsp Count

Number of JSPs that have been loaded into a web application

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "JspMonitor" • MBean attribute name: "jspCount" • Aggregation: Sum

Jsp Monitor Jsp Reload Count

Number of JSPs that have been reloaded

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "JspMonitor" • MBean attribute name: "jspReloadCount" • Aggregation: Sum

Thread Pool Current Threads Busy

Number of currently busy threads in the pool

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "ThreadPool" • MBean attribute name: "currentThreadsBusy" • Aggregation: Sum

Thread Pool Current Thread Count

Total number of threads in the pool

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "ThreadPool" • MBean attribute name: "currentThreadCount" • Aggregation: Sum

Global Request Processor Request Count

Number of requests handled by the request processor

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "GlobalRequestProcessor" • MBean attribute name: "requestCount" • Aggregation: Sum

Global Request Processor Max Time

Maximum time required to process a request [ms]

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "GlobalRequestProcessor" • MBean attribute name: "maxTime" • Aggregation: Sum

Global Request Processor Bytes Sent

Accumulated number of bytes sent by the request processor

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "GlobalRequestProcessor" • MBean attribute name: "bytesSent" • Aggregation: Sum

Global Request Processor Bytes Received

Accumulated number of bytes received by the request processor

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "GlobalRequestProcessor" • MBean attribute name: "bytesReceived" • Aggregation: Sum

Global Request Processor Processing Time

Accumulated processing time consumed by the request processor

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "GlobalRequestProcessor" • MBean attribute name: "processingTime" • Aggregation: Sum

Global Request Processor Error Count

Number of errors that occurred since the starting the request processor

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "GlobalRequestProcessor" • MBean attribute name: "errorCount" • Aggregation: Sum

Cache Access Count

Number of accesses to the cache

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Cache" • MBean attribute name: "accessCount" • Aggregation: Sum

Cache Hits Count

Number of cache hits

• Availability: Tomcat 5.5 and higher • MBean type (key = "type"): "Cache" • MBean attribute name: "hitsCount" • Aggregation: Sum

Servlet Processing Time

Accumulated processing time of the servlet [ms]

• Availability: Tomcat 5.5 and higher • MBean type (key = "j2eeType"): "Servlet" • MBean attribute name: "processingTime" • Aggregation: Sum

Servlet Max Time

Maximum processing time of a request processed by the servlet [ms]

• Availability: Tomcat 5.5 and higher • MBean type (key = "j2eeType"): "Servlet" • MBean attribute name: "maxTime" • Aggregation: Sum

Servlet Min Time

Minimum processing time of a request [ms]

• Availability: Tomcat 5.5 and higher • MBean type (key = "j2eeType"): "Servlet" • MBean attribute name: "minTime" • Aggregation: Sum

Servlet Request Count Number of requests processed by the servlet

• Availability: Tomcat 5.5 and higher

• MBean type (key = "j2eeType"): "Servlet" • MBean attribute name: "requestCount" • Aggregation: Sum

Servlet Error Count

Number of errors caused by the servlet

• Availability: Tomcat 5.5 and higher • MBean type (key = "j2eeType"): "Servlet" • MBean attribute name: "errorCount" • Aggregation: Sum

Servlet Load Time

Time required loading the servlet

• Availability: Tomcat 5.5 and higher • MBean type (key = "j2eeType"): "Servlet" • MBean attribute name: "loadTime" • Aggregation: Sum

JBoss JMX Metrics

Because JBoss uses Tomcat as default servlet engine, the JMX metrics for JBoss include also the Tomcat JMX metrics. The following list only contains JBoss specific metrics.

Server Info Active Thread Count

Number of currently active threads.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "type"): "ServerInfo" • MBean attribute name: "ActiveThreadCount" • Aggregation: Sum

Server Info Active Thread Group Count

Number of currently active thread-groups.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "type"): "ServerInfo" • MBean attribute name: "ActiveThreadGroupCount" • Aggregation: Sum

Managed Connection Pool Available Connection Count

Number of ready connections.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "service"): "ManagedConnectionPool" • MBean attribute name: "AvailableConnectionCount"


Managed Connection Pool Connection Count

Number connections managed by the pool.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "service"): "ManagedConnectionPool" • MBean attribute name: "ConnectionCount" • Aggregation: Sum

Managed Connection Pool Connection Created Count

Number connections created by the pool.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "service"): "ManagedConnectionPool" • MBean attribute name: "ConnectionCreatedCount" • Aggregation: Sum

Managed Connection Pool Connection Destroyed Count

Number of destroyed connections

• Availability: JBoss 3.2.5 and higher • MBean type (key = "service"): "ManagedConnectionPool • MBean attribute name: "ConnectionDestroyedCount • Aggregation: Sum

Managed Connection Pool Connections In Use Count

Number of currently used connections

• Availability: JBoss 3.2.5 and higher • MBean type (key = "service"): "ManagedConnectionPool" • MBean attribute name: "InUseConnectionCount" • Aggregation: Sum

Entity Bean Create Count

Number of created entity

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "EntityBean" • MBean attribute name: "CreateCount" • Aggregation: Sum

Entity Bean Remove Count

Number of removed entity beans

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "EntityBean" • MBean attribute name: "RemoveCount • Aggregation: Sum

Entity Bean Ready Count

Number of entity beans in ready state.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "EntityBean" • MBean attribute name: "ReadyCount" • Aggregation: Sum

Entity Bean Pooled Count

Number of entity beans in pooled state.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "EntityBean" • MBean attribute name: "PooledCount" • Aggregation: Sum

Message Driven Bean Create Count

Number of created message driven beans.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "MessageDrivenBean" • MBean attribute name: "CreateCount" • Aggregation: Sum

Message Driven Bean Remove Count

Number of removed message driven beans.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "MessageDrivenBean" • MBean attribute name: "RemoveCount" • Aggregation: Sum

Message Driven Bean Message Count

Number of received messages.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "MessageDrivenBean" • MBean attribute name: "MessageCount" • Aggregation: Sum

Stateless Session Bean Create Count

Number of created stateless session beans.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "StatelessSessionBean" • MBean attribute name: "CreateCount" • Aggregation: Sum

Stateless Session Bean Remove Count

Number of removed stateless session beans.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "StatelessSessionBean" • MBean attribute name: "RemoveCount" • Aggregation: Sum

Stateless Session Bean Method Ready Count

Number of created stateful session beans.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "StatelessSessionBean" • MBean attribute name: "MethodReadyCount" • Aggregation: Sum

Stateful Session Bean Create Count

Number of created stateful session beans.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "StatefulSessionBean" • MBean attribute name: "CreateCount" • Aggregation: Sum

Stateful Session Bean Remove Count

Number of removed stateful session beans.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "StatefulSessionBean" • MBean attribute name: "RemoveCount" • Aggregation: Sum

Stateful SessionBean Method Ready Count

Number of stateful session beans in method ready state.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "StatefulSessionBean" • MBean attribute name: "MethodReadyCount" • Aggregation: Sum

Stateful SessionBean Passive Count

Number of stateful session beans in passive state.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "StatefulSessionBean" • MBean attribute name: "PassiveCount" • Aggregation: Sum

Servlet Service Time Accumulated execution time of the servlet service method. [ms]

• Availability: JBoss 3.2.5 and higher

• MBean type (key = "j2eeType"): "Servlet" • MBean attribute name: "ServiceTime" • Aggregation: Sum

JCA Resource Connections Wait Time

Time spent waiting for the next available connection. [ms]

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JCAResource" • MBean attribute name: "Connections WaitTime" • Aggregation: Sum

JCA Resource Connections Use Time

Time spent using a connection. [ms]

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JCAResource" • MBean attribute name: "Connections UseTime" • Aggregation: Sum

JCA Resource ConnectionPools Close Count

Number of closed connections.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JCAResource" • MBean attribute name: "ConnectionPools CloseCount" • Aggregation: Sum

JCA Resource ConnectionPools Create Count

Number of created connections.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JCAResource" • MBean attribute name: "ConnectionPools CreateCount" • Aggregation: Sum

JCA Resource ConnectionPools Free Pool Size

Number of free connections in the pool.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JCAResource" • MBean attribute name: "ConnectionPools FreePoolSize" • Aggregation: Sum

JCA Resource ConnectionPools Pool Size

Number of connections in the pool.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JCAResource" • MBean attribute name: "ConnectionPools PoolSize"


JCA Resource ConnectionPools Waiting Thread Count

Number of threads waiting for a connection.

• Availability: JBoss 3.2.5 and higher • Thread Count MBean type (key = "j2eeType"): "JCAResource" • MBean attribute name: "ConnectionPools

WaitingThreadCount" • Aggregation: Sum

JDBC Resource Connections Wait Time

Time spent waiting for the next available connection. [ms]

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JDBCResource" • MBean attribute name: "Connections WaitTime" • Aggregation: Sum

JDBC Resource Connections Use Time

Time spent using a connection.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JDBCResource" • MBean attribute name: "Connections UseTime" • Aggregation: Sum

JDBC Resource Connection Pools Close Count

Number of closed connections.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JDBCResource" • MBean attribute name: "ConnectionPools CloseCount" • Aggregation: Sum

JDBC Resource Connection Pools Create Count

Number of created connections.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JDBCResource" • MBean attribute name: "ConnectionPools CreateCount" • Aggregation: Sum

JDBC Resource Connect ion Pools Free Pool Size

Number of free connections in the pool

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JDBCResource" • MBean attribute name: "ConnectionPools FreePoolSize"


JDBC Resource Connection Pools Po ol Size

Number of connections in the pool.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JDBCResource" • MBean attribute name: "ConnectionPools PoolSize" • Aggregation: Sum

JDBC Resource Connection Pools Waiting Thread Count

Number of threads waiting for a connection.

• Availability: JBoss 3.2.5 and higher • MBean type (key = "j2eeType"): "JDBCResource" • MBean attribute name: "ConnectionPools

WaitingThreadCount" • Aggregation: Sum

dynaTrace Diagnostics Server Metrics Committed Virtual Memory

Amount of memory committed to the Diagnostics Server´s JVM. [byte]

Free Physical Memory Amount of free physical memory available at the Diagnostics Server´s host.

GC Activations Accumulated number of grababe collection events on the Diagnostics Server´s JVM.

GC Collection Time Accumulated time used for grababe collection on the Diagnostics Server´s JVM. [ms]

Incomplete Measurements

Number of measurements waiting for an event to complete

Instrumentor Response Time

Represents the time needed to instrument classes, considering all connected agents.

Measurements per Second

Number of measures received from all connected agents.

Perm Gen Space Max Maximum size of the Perm Gen memory pool of the JVM hosting the Diagnostics Server

Perm Gen Space Used Amount of memory used from the Perm Gen memory pool of the JVM hosting the Diagnostics Server

Process CPU Time Accumulated CPU process time consumed by the JVM of the Diagnostics Server

Processed Measurements per

Number of measurments processed from all connected agents per interval. (10 seconds)

Interval

PurePath Buffer Size Amount of memory currently used to store PurePaths [byte]

Skipped Events per Interval

Number of events skipped from all connected agents per interval. (10 seconds)

Skipped Pur ePaths per Interval

Number of PurePaths skipped from all connected agents per interval. (10 seconds)

Used Memory Amount of memory used by the JVM hosting the Diagnostics Server. [bytes]

7.2. Business Transaction Configuration

Overview

Business Transactions are based on measures providing measurement data which is evaluated by the business transactions. Data from underlying measures can be used in various ways. It can be used to filter data that is relevant for a specific business case types, or to define groups to identify different business case instances. Additionally, Business Transactions can be used evaluate and possibly filter data of underlying measures and feed the data into a new measure associated with the business transaction. A Business Transactions can be based on multiple underlying measures, which can be used for aforementioned tasks in various combinations. Identifed instances of Business Transactions are listed within a dedicated Business Transaction View and measures associated Business Transactions can be charted like common measures.

Add Underlying Measures

The underlying measures a Business Transaction depends on are listed in the Transaction Table of the Business Transactions, together with the function and aggregation type assigned to the different measures. The assigned function defines how data from an underlying measure is used to evaluate the Business Transaction. The available functions comprise in filter, group, evaluate and inactive which are described within the following section.

Figure: Business Transaction Data Table

Filter The filter function is used to define define value ranges of incoming data that activate a Business Transaction. The filter criterion for a filter function is the threshold of the underlying measure. If the data received from the underlying measure violates a threshold, the filter is passed. Filter functions are evaluated each time a PurePath is terminated. An arbitrary number of filters can be defined for Business Transactions that define also an evaluate function, and multiple filters are logically AND concatenated to determine if the global filter of the Business Transaction is passed. Only one filter can be defined for Business Transactions that have no evaluate function defined.

Group The group function can be used to segmentated Business Transaction according to the values received from the underlying measure. The group function, applied to a measure that provides the username of the currently logged in user, provides statisical information about Business Transactions per user. Multiple group functions can be defined for a Business Transaction. The group function is only evaluated if all filters defined for the Business Transaction are passed.

Evaluate If a Business Transaction contains a measure using the evaluate function, a new measure is created and associated with the Business Transaction. Data from the underlying measure is propagated to the measure created measure if all filters defined for the Business Transaction are passed.

Inactive Any underlying measure can be excluded from filtering, grouping or evaluation by setting its function to inactive.

The aggregation type defines how multiple values received from an underyling measure are aggregated. The aggregation type is only evaluated for PurePath related measures using the evaluate function. For measures that are not related to PurePath, the last measurement value is used to evaluate the Business Transaction which eliminates the possibility of multiple received values. Filter and group functions do not require an aggregated value.

Configure Underlying Measures

Measures that provide numeric values can be used as underlying measures for Business Transactions straght forward. The only exisiting constraint is that a threshold must be defined for measures that are used for filtering. Measures dealing with string values, like Argument Value measures require more suffisticated configuration, which is best explained by an example:

A Business Transaction is required that filters login transactions of the user "demouser". Login validation is performed by the method "isLoginValid", which requires string parameters for username and password, whereas the first parameter provides the username. First, an Argument Value measure, based on the method "isLoginValid" is created. The measure is configured to evaluate occurence of method calls where the value of the first parameter is

"demouser". A threshold must be defined for the measurement to enable its usage for the filter function. The threshold is set to 1.0 causing a threshold violation if a method call with parameter "demouser" occurs once within a threshold, which is exactly the behavour required to filter login transactions of the user "demouser". The so configured measure is assigned to a Business Transaction, and its function is set to filter.

Figure: Configuration of measure to detect login of user "demouser"

Note: As the threshold settings of measurements are used both by the Business Transactions filter function and Incidents, it is recommendet to generate separate instances measures that act as underlying measures for Business Transactions.

Busines Transaction Specific Metrics

The metrics Duration, CPU Duration, and Value within the metric group Business Transaction provide data which is specific for Business Transaction. Duration and CPU Duration provide duration measurement data related to the PurePath the evaluation of a Business Transaction is based on. The metric Value is used to initialize the output measures of Business Transaction. Every Business Transaction having an evaluate function creates a measure based on the metric Value.

Visualization of Business Transactions

The metrics associated with Business Transactions are available in the measure group Business Transactions and can be used for charting. For detailed information about charting of measures, please see chapter Charting . Business Transactions and measures associated with Business Transactions share the same name. To find the the measure associated with the Business Transaction "Demo user logged in" search the measure group Business Transactions for a measure with the name "Demo user logged in".

Additionally, evaluation of Business Transactions generates or updates entries in the Business Transaction view, which is described in section Business Transactions of chapter Diagnose Performance . An entry is created the first time the filter evaluation of a Business Transaction is passed. Subsequet positive filter evaluations increase the count of the entry and update the displayed PurePath related timing information. Further, a new entry is generated for new occurences of measurement values of measures using for group functions, assuming that required filter criterias are fulfilled. Reoccurring values result in an update of the entry representing the group. Evaluation functions also generate or update entries within the Business Transaction view.

7.3. Incidents

Overview

An Incident Rule provides a mapping between threshold violations of measures and actions, which are executed on threshold violations. Incident Rules can be based on multiple measures and different severities of threshold violations, enabling selective generation of notifications indicating system states that can only be deducted from threshold violation states of multiple measures.

Sensitivity

The sensivity settings of Incidents Rules define how incidents react on rapid changing threshold states. A specific range of the history of previous threshold states of a measure is analyzed to determine if the threshold state is stable. The state changes between the current threshold state and the oldest threshold state within the considered ranges are assigned a numeric value that is weighted according to the age of the state change. The more current the

state change is, the higher it is weighted. The percentage of weighted state changes within the considered history range is used as indicator to determine if the threshold state of a value is stable.

The calculated stability indicator is compared with a low and a high threshold. If the indicator is lower than the low threshold, the threshold state of the measure is considered stable and the current threshold state of the measure is used to evaluate the Incident Rule. If the indicator is higher than the high threshold, the threshold state of the measure is considered instable and the current threshold state is ignored. A stability indicator between low and high threshold indicates that stability of the threshold state can not be determined. In this case, the previous determined stability state is used. For PurePath based measures, the threshold state history is updated on completion of a PurePath, and the threshold state history of measures that are independent from PurePaths is updated in intervals of 10 seconds.

There are predefined sensitivity settings available that suit for different behaving measurements and different situations. Additionally it is possible to provide user defined values for the thresholds and the considered history range. To enable more accurate determination of the thresholdÂ´s stability, use a long history range. A shorter history range causes less accurate determination, but the stability detection gets faster into steady state.

A higher value for the low threshold increases the number of notifications generated for threshold violations because more threshold state changes are tolerated before the threshold state is considered instable. Use a high value for the low threshold to monitor rapid measures with rapid changing values which require immediate countermeasures on threshold violation. If the low threshold is set to a lower value, fewer threshold state changes cause the state to be considered instable and fewer notifications are created. Use a low value for the low threshold for measures that can violate thresholds for short period of time, but require countermeasures if threshold is violated for a longer time period.

The high threshold should be set at least 10% higher than the low threshold to avoid rapid changes between stable and instable state.

Measures and Conditions

An Incident Rule defines one or more conditions based on the threshold state of on or more measures. A logical concatenation type (and,or) and a threshold state (warning, severe) can be set individually assigned to each condition. If the current threshold state of a measure reaches or exceeds the threshold state defined in its condition, the condition is violated. The conditions are concatenated according their logical concatenation type. If the result of the concatenation evaluates to "true", the actions assigned to the Incident Rule are executed.

If a new measure is added to the conditons of a Incident Rule, its threshold state is initialized with the most severe threshold that is defined for the measure. If only a value for the &qout;warning" threshold is defined for the measure, the Incident Rule threshold is initialized to "warning". If a measure defines both thresholds or only the "severe&qout; threshold, the Incident

Rule threshold is initialized to severe. A measure with no defined thresholds can also be added to an Incident Rule, but in this case the Incident Rule threshold for the measure is set to "noThreshold" and the measure has no influence to the evaluation of the Incident Rule. The threshold setting of a condition can be alterd from the lowest severity level to the highest severity level defined by the underlying measure.

Figure: Measure and Condition Table

To adapt the threshold settings of a measure to the needs of a Incident Rule, select the measure in the Measure and Condition Table and click "Edit". This opens a dialog to modify the threshold settings of the measure. Note that changed threshold settings are also effective for the underyling measure. Although a measure can be used by different Incident Rules, it is not possible to define different threshold settings for the same measure. If different threshold settings are required, a copy of the measure with the desired threshold values must be created.

Figure: Threshold Modification Dialog

Actions

Multiple actions can be defined for by an Incident Rule, which are executed if the conditions of the Incident Rule evaluate to "true". A severity level (informational, warning, severe) can be set for each action, which used as parameter for action execution. The "Logging Notification", which is added to the actions of new created Incident Rules by default, uses the severity level of the action to determine the severity of generated notifications. To remove this or any other action from an Incident Rule, select the action to remove and use the "Delete" button. If a new action is added to a Incident Rule, the severity level is initialized with "informal"

Figure: Actions Table

Available actions

An action is added to an Incident Rule with the "Add" button below the Action Table, which opens a list of the available actions. If an action is selected, existing configuration parameters of the action are displayed in the properties configuration table, which can be either set during the action is added to the Incident Rule or afterwards. To add the selected action, use the button "Ok". To alter parameters of an already added action, select the action and use the button "Edit" which brings up a dialog that enables editing the parameters.

dynaTrace Diagnostics provides a plugin interface, and a plugin development SDK that enables quick and easy development of user defined action plugins. To learn more about development of user defined action plugins, please contact the dynaTrace support team.

Figure: Available Actions

Generated Incident Rules

dynaTrace Diagnostics can automatically generate incident Rules for subscribed measures or Business Rules. To generate an Incident Rule, select a subscribed measure or a Busines Transaction from the measure subscription list (Open "System Profile" → "Configuration" → "Measures") or the transaction list (Open "System Profile" → "Configuration" → "Transactions") and press the button "Generate Incident Rule". Note that the button is only enabled if a measure or a Business Transaction is selected that has at least one threshold defined.

Figure: Button Generate Incident Rule

7.4. Integration of 3rd Party Monitoring Tools

Subscribed Measures provide realtime analysis data about the System under diagnosis (SUD), which can be accessed by external tools via the JMX Interface of the Diagnostics Server. All subscribed measures are available via the JMX interface and can be requested by external monitoring tools. External Monitoring tools can be configured in a way to define Thresholds , include them into the service level system and process them. Those external tools (e.g. BCM Patrol, IBM Tivoli, Segue Silk Central Performance Manager, and CA Unicenter) can be used to aggregate realtime analysis data over months to provide an overview about the application status.

External Monitoring Tools poll realtime analyses data from Diagnostics Server, which makes new measured values available every ten seconds.

8. Charts

Overview

The dynaTrace Diagnostics enables the observation and analysis SUD components over time through its measure subscription mechanism. Through the use of charts any subscribed measure may be inspected visually over time. Charting measures will help to identify trends and answers to questions like "How does a method´s response time behave over time?" Additionally, since the charting component dynaTrace Diagnostics supports any combination of measures to be charted within the same view, users can analyze the correlation of different system components visually. This way they can observe method behavior in relation to many factors that might also impact performance to find true root causes.

Since an SUDÂ´s parameters are sampled in ten second periods, the finest granularity of charts is also ten seconds. However, charts can have courser granularity to highlight issues first. They can be manipulated interactively to zoom in and out as needed. Charts can show up to a 15 minute interval on the screen.

To zoom in along the x-axis of a chart, select the leftmost point of the zoom area. press and hold the mouse button and move to the rightmost point and release the mouse button. To zoom out again, press the mouse button inside the chart view and move from rigth to left.

Context menu options

• Set Time To…: makes usage of the filter mechanism ( Diagnosis - Filter ) to specifiy the time range of the data the chart is based on.

dynaTrace Diagnostics provides three chart types.

Line Chart

By means of connected lines the trend of a measure´s time series is visualized. This chart type may be customized by the user. Any subscribed measure may be added to it. After a sample interval has passed the measured values are drawn. If no value has been captured for an interval, nothing is plotted. Future values will be plotted again and the connected line will be interpolated to the last drawn value.

This kind of chart is suitable for correlating any kind of measures.

Figure: Line Chart

Breakdown Chart

Breakdown charts visualize the proportion of the selected measures per sample interval over time. This type of chart may be customized as well as it can be found in the application view.

An example for using this chart constitutes illustrating the proportion of executed APIs.

Figure: Breakdown Chart

8.1. Create a new Chart

Overview

Breakdown and Line charts can be created and customized. New and customized charts will be stored with the related application profile.

To create a customizable chart right-click the cockpit tree´s node saying "Charts"

→

• Name: The charts name will be displayed as chart title inside the chart as well as identifier in the cockpit tree.

• Description: A charts description. • Default Series Type: The chart type is defined here. Select either Breakdown or Line

Chart. • X-Axis Title: This text will be displayed as x-axis label. • Y-Axis Title: This text will be displayed as y-axis label.

After confirming a chart creation, a new node is added to the Chart sub tree. By right-clicking on this node the chart may be deleted or the chart properties may be changed.

8.2. Add Series Configuration

Overview

To add a series to the chart, open, via double clicking the chart´s node, and then right-click on the table below the chart, choose "Add". The opened dialog contains a table with all subscribed measures. To obtain a series which can be charted, a measure has to be contained by the measure subscription.

Figure: Series Configuration

Add, Edit and Delete Subscriptions

In the subscription table dialog box above (1), users can Add, Edit, or Delete measure subscriptions from the active profile.

Add Subscribed Measures to the Chart

Subscribed measures may be configured and added to the chart by activating the lower "Add" button. (2) Once a measure is added, the dialog box stays open for users to add multiple measure time series to the chart.

The Close button closes the dialog.

Properties for drawing a measure:

Scale Factor:

The scale factor indicates whether the real values shall be displayed, by choosing 1, or scale displayed with factor 0.000001 to 1,000,000. Choosing the "Auto" option automatically scales the series into an optimal range per series.

Source:

Use the Source drop-down list to choose the way in which measurement information is drawn.

• Min: the lowest measurement of a sample period • Avg: the average of all captured measurements • Max: the greatest measurement of a sample period • Sum: the sum of all captured measurements of a sample period • Count: the number of measurements of a sample period

Series Color:

The color used in the chart for the drawn series.

Highlighted Thresholds:

Draws the selected threshold when the corresponding checkboxes are checked

If a measure has been added to be charted its series and measure properties may be changed afterwards via a right mouse click on a chart´s table.

In addition to the drawn time series line, the charted information is represented in the table beneath the chart area.

Figure: Line Chart with Thresholds

Time Series Details table

• Series: The color used in the chart to represent the series. • Group: Represents the metric group the series belongs to. • Metric: Represents the metric name of the charted series. • Key: Represents the metric specific attribute if it exists. • Agent: The agent´s name, empty if the measure refers to all connected agents.

• Host: The agent´s host name. If the agent belongs to a cluster this field is left empty. • Current: Represents the last measured value, or displays the currently marked series

value when clicked on in the chart area above. • Min: Represents the minimum value of the charted time range. • Avg: Represents the average of all values of the charted time range. • Max: Represents the maximum value of the charted time range. • Unit: Represents the series unit of measurement. • Count: Represents the currently shown measurements. • Auto: Indicates if autoscaling is active or not. • Factor: Represents the scaling factor for drawing the related time series: • Source: Represents the currently drawn source type (min, avg, max, sum, count). • Visible: Whether the series is hidden or not. A series visibility may be changed via the

context menu. • Interval: Represents the duration of a sample interval in seconds. • Threshold Active: Represents if a series measure is sensitive for threshold violations. • Upper Severe: Represents the configured upper severe threshold for the related

measure. • Upper Warning: Represents the configured upper warning threshold for the related

measure. • Lower Warning: Represents the configured lower warning threshold for the related

measure. • Lower Severe: Represents the configured lower severe threshold for the related

measure.


• Hide: removes the series from the chart, sets the visible field, but leaves the series in the table and configuration of the chart.

• Add: Opens the series configuration dialog to add a measure series to the chart. • Remove: removes the series from the chart, the table, and configuration of the chart. • Edit Measure: brings up the Measure Editor dialog box. • Series Properties: opens the Series Configuration dialog where the series´ chart

properties are editable.

9. Sessions

Overview

dynaTrace Diagnostics has introduced the concept of "sessions" to facilitate the management of analyzed SUDs. Sessions are derived from active connections to Diagnostics Servers. Sessions enable access to real-time measurement data (accumulated at servers during SUD monitoring) and stored sessions (which contain data from previous live sessions and are available for offline analysis). Additionally, stored sessions can be compared with live sessions and other stored sessions to identify trend statistics and compare the performance of different SUD versions and configurations. Stored sessions contain monitoring data from specific sessions during user-defined time intervals. They also provide the same analysis functionality that is availabe for live sessions. Session data is both stored and analyzed within the Diagnostics Server. To facilitate sharing of session data and reduce Diagnostics Server load and network traffic, stored sessions can be converted to offline sessions, which can be stored locally and analyzed via the Diagnostics Client.

Because stored sessions contain sufficient information for isolating the root causes of performance issues, and are a faster and cheaper alternative to reproducing issues, stored sessions are a valuable tool for communicating performance issues between IT, Testing, and Development teams.

The screenshot of the Diagnostics Client Cockpit view (displayed below) shows how different session types are presented. dynaTrace Diagnostics provides three different types of sessions:

Figure: Navigation Cockpit

Live Sessions

A live session reflects the current activity of a connected Diagnostics Server instance. It constitutes the main connection to a Diagnostics Server. A connection to a Diagnostics Server can be established or terminated via the context menu of live session nodes. A live session comprises multiple system profiles, each representing an SUD. System Profiles provide interfaces for managing monitoring options and performing analysis of SUD performance data. For further information about System Profiles, please refer to the "Configure System" section.

The System Profiles of live sessions are stored on the Diagnostics Server, which enables sharing of live session settings between different Diagnostics Client connections.

dynaTrace Diagnostics enables storage of collected monitoring data for future analysis. Two different procedures are available for generating stored sessions. One option is to generate a snapshot of the monitoring data related to a SUD that is contained in the memory of the Diagnostics Server at a specific point in time. Alternatively, measures retrieved from an SUD can be recorded to a stored session during a specific time interval, enabling long-term monitoring of SUDs. After generation of a stored session is complete, a new node representing the stored session is added below the "Stored" node.

Stored Sessions

Data from stored sessions remains on the Diagnostics Server until it is deleted. The server-side location of this data enables simultaneous analysis of multiple stored sessions via multiple instances of the Diagnostics Client.

Since stored sessions are located on the Diagnostics Server, analysis of stored sessions can only be performed when the Diagnostics Server is running and an active connection between the Diagnostics Client and the Diagnostics Server is available. To enable analysis of stored sessions without a server connection, offline sessions can be generated out of stored sessions. The information stored in offline sessions is equivalent to the information stored in the original stored sessions. To generate an offline session, right-click a stored session and select "Make Offline Available" from the context menu. Alternatively, the context menu entry "Export Session" enables you to export a stored session to a dynaTrace Diagnostics Session file (*dtds).

Offline Sessions

An offline session constitutes a local copy of a server-side online session and provides the same functionality. Through the "Export Session" context menu option, a connected offline session can be exported to a dynaTrace Diagnostics Session file (*.dtds). An exported dynaTrace Diagnostics Session can be loaded via the "Import" command on the context menu "Offline" root node.

9.1. Session Management

Overview

Live Sessions:

When working on live sessions, the following functions are available from the toolbar and the Sessions menu.

• Swich Analysis On/Off : Switches analysis on or off. When analysis is switched off, all agents stop capturing data.

• Start Session Recording : Opens the Session Recording dialog to define the session (see below). Once recording has been activated, the start-recording icon becomes to the recording icon .

• Stop Session Recording : Stops session recording and changes the session recording icon back to the start-recording icon . Assuming that the recorded session is not empty and that data has been captured, a new session will be added to the stored sessions below the "Stored" node with the session name provided at the start of recording.

• Store recent PurePaths to Diagnostics Session : Opens the Store Application Session dialog and adds a new session to the stored sessions below the "Stored" node. This dialog has the same UI as the Session Recording dialog. Values in memory, from the beginning of the realtime session to the point of accepting the dialog, are stored.

• Clear System Session : Clears monitoring data from the currently selected system profile. Profile definitions and active profile settings are not deleted.

Live Sessions

The "Live" node in the dynaTrace Diagnostics cockpit provides access to the stored sessions maintained on a connected Diagnostics Server. Expanding the "Stored" node shows the stored sessions available on that server. Double-clicking an individual recorded session initiates a connection to the Diagnostics Server and expands the session´s view, displaying different view nodes for analysis of the session data, such as Performance and Event Diagnosis. For a detailed description of these nodes, please refer to chapters "Configure System", "Charting", "Diagnose Performance", "Diagnose Events", "Diagnose Runtime" and "Reporting". If the session is already connected, it can be expanded by clicking on the "+" symbol. All view nodes that are available for live sessions are also available for stored sessions. Upon double-clicking of view node, the data relevant that view is retrieved from the Diagnostics Server and presented within the view.


• Disconnect from Session: Disconnects the selected stored session from the Diagnostics Server. The session remains in the list of stored sessions, but analysis of the session data is not possible until it is once again connected.

• Make Offline Available: Downloads a copy of the session to the machine where the Diagnostics Client is running. This enables offline analysis of session data in the absence of a connection to a Diagnostics Server. After a stored session has been completely transferred into an offline session, the new offline session is represented as a node below the "Offline" node. The name of the new offline session is taken from the original stored session.

• Export Session: Exports the selected session directly to a local session file (*.dtds) by using the session-export functionality.

• Rename Session: Brings up a dialog that allows you to change the name of a stored session on the Diagnostics Server or an offline session on the Diagnostics Client.

• Details…: This dialog box displays descriptive information that was entered when the session was created.

Start Session Recording and Store Application Session dialog

Starting session recording and storing application sessions require the same information, so both actions use the same dialog.

Figure: Session Record dialog

• Name: A unique string used to identify stored or offline sessions. If this text field is left blank, a default string will be used to keep session names unique.

• Description: An optional text field for providing detailed session information. This text is displayed in a tool tip box on session tree nodes.

• Options: o PurePaths and time series: All PurePaths and time series data will be stored in

this session. o Only PurePaths marked as violated and time series: To avoid creating

sessions that are too large, this option can be used to store only those PurePaths that include violations (including time series).

o Time series: Only time series data will be stored (no PurePaths).

Session Export:

Any session can be directly exported to a local dynaTrace Diagnostics Session file (*.dtds) by using the session-export functionality. Either entire sessions or selected PurePaths can be exported. Both options are available via the application menu "File" → "Export". In addition, the export session command is available from each session´s context menu.

The export PurePath command is available as a context menu option in PurePaths views and PurePaths Entry Points views. This command is only enabled when the PurePath views or PurePaths Entry Points diagnosis views are active and PurePaths are selected. Exports can include all PurePaths or only selected PurePaths.

Exported session files can subsequently be shared with other team members and imported into their Diagnostics Clients

Figure: Session Export dialog

• All PurePaths in session: Exports all available PurePaths within the session. • All PurePaths in view: Exports all available PurePaths within the view according to

current filter settings. • Active selected PurePaths: Exports only the currently selected PurePaths. • Export to file: Export to a valid .dtds file. If no file name is specified, a default file name

will be used instead. The default file name is "session[timestamp].dtds" (for example, "session20070224173403.dtds").

• Description: An optional text field in which you can enter detailed session information. This text is displayed in a tool tip box on session tree nodes.

Session Import:

Locally stored sessions that have been exported can be imported for analysis. The Session Import command is available under the application menu "File" -> "Import…" and via the "Import…" context menu of the "Offline" node within the Cockpit view. The command opens a file selection dialog that displays all available valid dynaTrace Diagnostics Session files (*.dtds).

When a session is imported successfully, it is added to the offline session below the "Offline" node of the Cockpit node tree.

10. Diagnose Performance

Overview

This chapter provides information about all Diagnosis views. For every view a short overview is given that explains the benefit of the data contained in that view and the metrics of every view are described.

Text Search

The text search control , located in the main tool bar, enables you to search for specific textual occurrences within diagnosis views or the cockpit tree. The buttons on the right side assist you to navigate to the next or previous textual occurrence.

Filter

Overview

Every diagnosis view can be filtered by enabling the custom filter settings via the session filtering dialog . The actual applied filter settings have a short description next to the filter icon. Additional descriptive information is available in a tooltip box.

Diagnosis views use a default filter when new. When custom filter settings have been applied to any diagnosis view, the filter remains in effect for all views opened until the filter settings are changed or until the view is closed.

Filter Usage

Using the context menu option "Open as New View", a new diagnosis view will be created. Views can use other view filters as a starting point by selecting the base view´s filter from a drop down list. Further options for the view include filtering by:

• PurePath: Select time slices to focus on or specific paths • Agents: Target specific tiers or Agent activity • Webpage: Specify the webpages to target in the diagnosis • Servlet: Focus the diagnosis on specific servlets

Figure: Session Filter Dialog

Diffing

Some diagnosis view types provide means to compare data of different view instances of the

same type. The diffing button opens a dialog to select a view for comparisson. After the view is selected, the differences of the data values of the two views is calculated and presented within the original view. Values of the original view that exceed the corresponding value of the second view are displayed in red, and values of the original view that are below the corresponding value of the sceond view are displayed in green. Values which are identical in both views are displayed black.

Figure: View Selection Dialog for diffing

After a view for diffing is selected, the diffing button can be use to switch between differential view and absolute (default) display of view data.

Figure: Diffing view

The diffing feature is available for the views API Breakdown , Database , Remoting , and Methods .

Sort

dynaTrace Diagnostics views can be sorted by any column ascending or descending. Just click on the desired column to sort the table content accordingly.

Customize

Every view provides the opportunity to customize the shown columns in a views table. Open a view, choose "Customize" and select/deselect columns.

Reporting

The reporting feature is integrated in every view. For more information please read chapter Reporting .

Context menu options for all Diagnosis Views

• Open Diagnosis View: This submenu assists you to perform a quick drill-down to other diagnosis views. Only the views that contain data according to the selected item will be available.

• Details: Opens a dialog window containing detailed information. • Refresh: Updates the view´s content based on the current filter settings.

10.1. Business Transactions

Overview

All actions performed at ate SUD that match a registered Business Transaction are displayed within the Business Transaction view. Please reade here how to configure Business Transactions. The data of the Business Transaction view can be filtered according to the type of

recorded Business Transaction with . Select "group", "filter" or "evaluate" to filter respective Business Transaction types or select &qout;all" to view all currently recored Business Transactions regardless of their type.

The pie chart below the Business Transaction table visualizes the values of the currently selected column of the Business Transaction table.

Figure: Business Transaction view

Metrics

Business Transaction Metrics

• Name: Name of the Business Transaction, as used to configure the Business Transaction

• Evaluation Measure: Name(s) of the measures the Business Transaction is based on. A table row is generated for each measure

• Aggregation: Defines how data from multiple occurences of Business Transaktions of the same kind within a PurePath are accumulated

• Function: Functionality of a measure used by a Business Transaction. (group, filter, or evaluate)

• Group: Values received from grouping measures. Each occurrence of a different value creates a table row.

• Count: Number of occurrences of a specific Business Transaction. In case of grouping Transactions, number of occurences of a specific group.

• Min: Minimum received value of measures used for the evaluate function of a Business Transaction. Defaults to 1.0 for grouping measures and to 0.0 for filter measures.

• Max: Maximum received value of measures used for the evaluate function of a Business Transaction. Defaults to 1.0 for grouping measures and to 0.0 for filter measures.

• Avg: Average of all received value of measures used for the evaluate function of a Business Transaction. Defaults to 1.0 for grouping measures and to 0.0 for filter measures.

• Sum: Sum of all received value of measures used for the evaluate function of a Business Transaction. Defaults to the cardinality of a group for grouping measures and to 0.0 for filter measures.

• Time Sum [ms]: Accumulated duration of all PurePaths containing the Business Transaction

• Time Avg [ms]: Average duration of all PurePaths containing the Business Transaction • CPU Time Sum [ms]: Accumulated CPU time of all PurePaths containing the Business

Transaction • CPU Time Avg [ms]: Average CPU time of all PurePaths containing the Business

Transaction • Filter: Displays filter settings of filter Transactions, left blank for others.

Context menu options:

• Subscribe Measures… : Opens the Measure Picker dialog to add measures to a subscription. This option is only available during Realtime sessions.

• Open PurePaths : Creates a new PurePath view containing all PurePaths that are referenced by the actual selection.

10.2. API Breakdown

Overview

This view shows the distribution over the different APIs measured as configured in the active System Profile .

Figure: API View

Metrics

API Performance Metrics

• API: The name of the API • Exec Time [ms]: The time in milliseconds, it took to execute the methods from this API,

without nested calls to methods of other APIs. • Exec CPU Time [ms]: The CPU time in milliseconds, it took to execute the methods from

this API, without nested calls to methods of other APIs.



• Open API specific View : Opens the corresponding J2EE view.

10.3. PurePaths

Overview

The PurePath View is the central representation of all captured PurePaths. It is used for determining performance-critical methods and their position within the PurePath, in order to be able to recognize the cause of the performance problem. Since all special diagnosis views can be traced back to the PurePath view, it represents the basis of performance analysis. The View

is divided into two halves: In the upper half is the "Path" tab . This table component contains all data of essentially recorded PurePaths and is used as interaction basis for other

components of this view. The table in the tab "Contributors" contains all instrumented methods of the actual selected PurePath. Depending on the sort column, the most runtime-critical methods will be emphasized by background coloring to present these methods fast and saliently to the user. The lower half presents the sequential representation of PurePaths

and contains exactly the same columns as the contributors table ("Tree" tab ). Dependences between instrumented methods will be illustrated by means of a tree structure. By the selection of a certain method in the contributors table the PurePath tree is expanded correspondingly to the place where the selected contributor method is called. With this functional interaction between the contributors table and the PurePath tree, the user can efficiently navigate to desired methods within PurePaths to receive context-referred information for this method. Furthermore a diagram of configured tiers is also available in the lower half of this view

("Visualization" tab ). If several of these tiers are involved in a PurePath and if they communicate with one another directly, the communication channels are visualized by lines between communicating tiers.

The API Distribution Tab visualizes the Execution CPU Utilization and the Execution Time per API of selected PurePath methods. This view provides the opportunity to generate a sequence diagram of the selected PurePath. Therefore select a PurePath and select the "Sequence Diagram" icon on top of the view.

The PurePath and it´s included information

PurePaths allow a top-town as well as bottom-up performance diagnosis through this view.

Top-Down Diagnosis

A top-down approach, for instance, can identify certain methods as the root cause of poor performance.

Bottom-Up Diagnosis

With a bottom-up approach, for instance, one can use the presented performance measurements to identify the exact method and business transaction that caused the biggest performance issues. Additionally, bottom-up analysis can show all the effects of a method that does not perform well.

Metrics

PurePath Performance Metrics

Figure: PurePath View

• PurePath: Shows a string representing the PurePath identifier • Agent: Contains the Agent instances by name from which this PurePath starts. • Size: The number of method calls within an PurePath. Only instrumented method will be

included. • Duration [ms]: Displays the total duration of an PurePath. This value is equivalent to

total execution time of the first method of this path. • CPU Duration [ms]: The overall required CPU time for executing this path. This value is

equivalent to total CPU time of the first method of this path. • Start Time: The time when this PurePath started. • Agent ID: The numerical ID of the agent instance from which this PurePath starts. • Tag ID: Shows the continuous numerical ID of PurePaths recorded by the given agent.


• Open as UML Diagram : Shows a UML-based visualization of the actual selected PurePath in a newly created "Sequence Diagram" view.


• Store PurePaths… : Opens the store PurePaths dialog to save the selected PurePaths as a new session. This session will be available in the Online Session tree.(only available for Realtime Sessions)

• Export PurePaths… : Opens the Export Session dialog and exports all selected PurePaths to a user-defined session file.

Contributors Performance Metrics

Figure: PurePath Contributors View

• Method: Displays a string representing the method name including argument types. • Class: The fully-qualified class name of this contributor method. • Argument: Shows the argument value of this method call if arguments have been

captured. • Return: The return value of this method call. • Agent: Contains the Agent instances by name that has captured this method call. • API: The API identifier with which this method call is associated. • Total time [ms] : The overall duration of this method call from method entry until

method exit. • Execution time [ms] : The time that was taken for execution of this method only. • Percentage (%) : The percentage of execution time of this method call in relation to

the total execution time of the PurePath. • CPU Total time [ms] : The total CPU time required for executing this method call from

method entry to method exit. • CPU Execution time [ms] : The CPU time that was taken for execution of this method

only. • CPU Percentage (CPU %) : The percentage of CPU execution time of this method call

in relation to the total CPU execution time of the PurePath. • ThreadID: The ID of the thread that was responsible for executing this method call.

Column headers with this symbol indicate columns containing performance critical information. If such a column is used for sorting the intensity of the background color indicates the severity state of the dedicated value in relation to all other values contained in this column.

Figure: Tree view of a selected PurePath


• Subscribe Measures… : Opens the Measure Picker dialog to add measures to a subscription. This option is only available during Realtime session.

• Expand All : Expands all sub-paths starting from the selected node. This option is only available on the tree representation table.

• Collapse All : Collapses all sub-paths starting from the selected node. This option is only available on the tree representation table.

Figure: Visualization of the tiers

Figure: API Layer Breakdown Charts

View toolbar items:

• UML/Sequence Diagram : Shows a UML-based visualization of the actual selected PurePath in a newly created ‘Sequence Diagram’ view.

Find PurePath Feature

The PurePath search feature is available as context menu option in the Diagnostics Client menu "Edit". It offers the ability to find a single PurePath based on dynaTrace HTTP response header strings. These strings are produced by HTTP requests and set to the responded HTTP header. A dynaTrace HTTP response header string is formatted as followed:

dynaTrace: RS=session20060316102259;PT=23;PA=2

Note: The PT and PA key must have integer values assigned. The RS key is only available if the dynaTrace Diagnostics Server has Session Recording activated, otherwise the RS key is missing.

Find PurePath dialog:

Figure: Find PurePaths dialog

• Paste HTTP response header here: Paste a dynaTrace HTTP response header into this text field. If this string has a valid format the "Find" button will be enabled. Otherwise a message with detailed information is displayed in the message area of the dialog.

• Search in Session options: If the specified dynaTrace HTTP response header does not contain a value for the RS key or the value for RS could not be resolved, choose an available session (Realtime, Online or Offline Sessions) to search for the PurePath.

Usage:

To find the appropriate PurePath, copy the HTTP response header line starting with the key "dynaTrace" from your load testing tool and paste it into the text field of the Find PurePath dialog. If the specified dynaTrace HTTP response header string is valid, the "Find" button is enabled. Otherwise the keys PT or PA are invalid. In this case verify the pasted dynaTrace HTTP response header string of correct formatting.

If the RS key is not specified within the dynaTrace HTTP response header, select an available session from the Search in Session options. The search will now be performed within the selected session.

After PurePath search has been finished, a new PurePath view containing the requested PurePath will be opened.

10.4. Web Request

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing and tuning Servlets and JSPs. It makes use of dynamic bytecode instrumentation to capture performance metrics, including Java remoting metrics, across horizontal and vertical application layers. A central Diagnostics Server correlates resulting measurements to PurePaths .

Figure: The Servlets/JSP Diagnosis view

Metrics

Servlet/JSP Performance Metrics

• URI: The part of the request´s URL from the protocol name up to the query string in the first line of the HTTP request. The web container does not decode this String.

• Query: The query string that is contained in the request URL after the path. • Count: The number of times this servlet has been called. • Total Time [ms]: The overall time in milliseconds, it took to call the servlet. • Execution Time [ms]: The time in milliseconds, it took to call a servlet, without nested

calls to other methods. • Bytes Sent: The number of bytes sent as response from the servlet. • Bytes Rcvd: The number of bytes received as request to the servlet. • CPU Time [ms]: The overall required CPU time in milliseconds, it took to call this servlet.

View toolbar items:

• Group by : Select grouping - Either group by URI/Query or only by URI.

• Show : o All : Show all Servlets. o Entry Points : Show only Servlets which are entry points.

Configuration

dynaTrace Diagnostics offers the Servlet Sensor Configuration Dialog to define filter criteria in order to shrink the set of Servlets that should be analyzed. This configuration is part of the J2EE Sensor Configuration Dialog and includes filter criteria for the URI and query.

Figure: Servlet Sensor Properties Configuration




Tuning Options

Performance Tuning Tips

• Minimize Java synchronization in servlets. • Don´t use the single thread model for servlets. • Use the servlet´s init() method to perform expensive one-time initialization. • Avoid using System.out.println() calls. • Create sessions sparingly. Session creation is not free. If a session is not required, do

not create one. • Use javax.servlet.http.HttpSession.invalidate() to release sessions when they are no

longer needed. • Keep session size small, to reduce response times. If possible, keep session size below

7 KBytes. • Use the directive <%page session="false"%> in JSPs to prevent the Application Server

from automatically creating sessions when they are not necessary. • Avoid large object graphs in an HttpSession. They force serialization and add

computational overhead. Generally, do not store large objects as HttpSession variables.

• Don´t cache transaction data in HttpSession. Access to data in an HttpSession is not transactional. Do not use it as a cache of transactional data, which is better kept in the database and accessed using entity beans. Transactions will rollback upon failures to their original state. However, stale and inaccurate data may remain in HttpSession objects. The Application Server provides "read-only" bean-managed persistence entity beans for cached access to read-only data.

• To improve class loading time, avoid having excessive directories in the server CLASSPATH setting. Put application-related classes into JAR files.

• HTTP response times are dependent on how the keep-alive subsystem and the HTTP server is tuned in general.

• If you are using Solaris 8, optimize SSL by using the mtmalloc library that provides a collection of malloc routines for concurrent access to heap space. To use mtmalloc:

a. Get patch 111308-03 from http://sunsolve.sun.com/ and install it. b. Edit the startserv script located in bin/startserv for your domain, and define the

LD_PRELOAD environment variable to be: /usr/lib/libmtmalloc.so • The exact syntax to define an environment variable depends on the shell you use. • Cache servlet results when possible. • Deploy applications that do not contain EJBs as WAR files rather than as EAR files.

10.5. Database

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing and tuning database access. It makes use of dynamic bytecode instrumentation to capture performance metrics, including Java remoting metrics, across horizontal and vertical application layers. A central Diagnostics Server correlates resulting measurements to PurePaths .

Figure: The Database Diagnosis view

Metrics

JDBC Performance Metrics

• SQLStatement: The executed or prepared SQL statement. • ExecCount: Number of executions of the SQL statement • ExecTime [ms]: The time in milliseconds, it took to execute the SQL statement, without

nested calls to other methods.. • Preparations: Number of preparations of the SQL statement

• PrepTime [ms]: The time in milliseconds, it took to prepare the SQL statement. • Rows Manipulated: Number of rows manipulated by delete, insert and update

statements.




Tuning Options

Performance Tuning Tips Based on Above Metrics

• Only if you do not have a driver for your database, then use Type1 driver (JDBC-ODBC Bridge).

• For two tiered applications to communicate from a java client to a database use Type2 driver that gives better performance than Type1 driver.

• Use Type3 driver if you communicate from the client to the database via a middleware server that gives better performance when compared to Type1 and Type2 drivers.

• Use Type4 driver for two and three tiered applications. • Give the driver hints like fetchDirection or fetchSize if your driver and database support

any of them. • Use a connection pool to cache database connections • Use batch transactions. • Use the suitable isolation level for your requirement.

TRANSACTION_READ_UNCOMMITED for concurrent transaction based applications. TRANSACTION_NONE for non-concurrent transaction based applications.

• If a statement is executed more than once, then use prepared statements. • Implement stored procedures if you want to get a result from complex and multiple

statements for one single request. • Use batch update facility available in Statements. • Use batch retrieval facility available in Statements or ResultSet. • Setup proper direction for processing rows. • Use proper getter and setter methods. • Close ResultSets, Statements and Connections as soon as you do not need them

anymore. • Write precise SQL queries. • Cache read-only and read-mostly table data. • If you retrieve a big amount of data, then fetch small amounts iteratively rather than the

whole data at once.

10.6. Remoting

Overview

uses a novel approach for diagnosing and tuning Java remote method invocations (RMI). It makes use of dynamic bytecode instrumentation to capture performance metrics, including Java remoting metrics, across horizontal and vertical application layers. A central correlates resulting measurements to PurePaths .

Figure: The RMI Diagnosis View

Metrics

Java Remoting Performance Metrics

• Type: The type indicates the type of the RMI protocol used for the call. • C/S: The C/S column indicates whether a client call (C) or a server side execution (S)

has been detected. If both sides of the RMI call have been detected, the column shows (C/S).

• Method: The name of the method. • Class: The name of the class. • Agent: Contains the Agent instances by name from which this PurePath starts. • Client Count: The number of times this particular remote method has been called on the

client side. • Server Count: The number of times this particular remote method has been invoked on

the server side. • Latency [ms]: The network latency, in milliseconds, is calculated as the difference

between the client side and server side response time. • Response Time [ms]: The time, in milliseconds, it took to carry out the remote method

invocation. The client side response time includes the proxy overhead, network latency, and delegation overhead, and the actual response time of the method implementation. The server side response time includes the delegation overhead and the actual response time of the method implementation.

• Serialization Time [ms]: The time, in milliseconds, it took to serialize the request method arguments or method return value to the network stream.

• Deserialization Time [ms]: The time in milliseconds, it took to deserialize the request method arguments or the response return value. It includes the time it took to instantiate the deserialized objects.

• Request Bytes: The size of the RMI request in bytes sent by the client and/or received by the server. It includes the request header and the serialized method arguments.

• Response Bytes: The size of the RMI response in bytes sent by the server and/or received by the client. It includes the response header and the serialized method return value.

• Request Objects: The actual number of distinct objects actually transferred. ( Note: High numbers can be caused by referencing collections or numerous linked objects in the methods arguments.)

• Response Objects: The actual number of distinct objects actually transferred. ( Note: High numbers can be caused by the methods return value that reference collections or numerous linked objects.)

• Serialized Request Objects: The total number of objects that are referenced by the method arguments. ( Note: Comparably higher numbers than the request object number denote that frequently the same objects are referenced.)

• Serialized Response Objects: The total number of objects that are referenced by the method return value. ( Note: Comparably higher numbers than the response object number denote that frequently the same objects are referenced.)


• Subscribe Measuresâ€¦ : Opens the Measure Picker dialog to add measures to a subscription. This option is only available during Realtime sessions.


Tuning Options


• Fields: to reduce number of objects serialized or to reduce the network traffic volume, use the transient keyword to omit serialization of fields that are not required on the remote location.

• Transport classes: replace classes by special transfer classes that carry less information.

• Local modifications: if the number of remote method invocations is high, especially due to plenty of calls to getter and setter methods, rethink whether methods should be invoked on a remote object or whether this object should copied to the remote location,

modified without network and serialization overhead, and sent back to the remote location.

• Call merging: another technique to reduce the number of remote method invocations is to merge multiple remote method invocations into a single one. e.g. multiple setter invocations could be merged to a single method call with multiple arguments. This merging reduces the network roundtrips to a single one.

• Custom serialization for CPU optimization: use custom serialization to optimize for CPU usage (Externalizable instead of Serializable) to eliminate the overhead cost of Java Reflection; Replacing UTF-8 encoded strings by char[] can reduce CPU cost for converting strings to the UTF-8 format but also doubles network traffic volume.

• Custom serialization for size optimization: use custom serialization to optimize network usage: multiple arguments could be merged together into a single bytearray (e.g. merge two 16bit short integers into a single 32bit integer).

• Network optimization: further optimizations can be achieved on the TCP/IP network layer, such as modifying the TcpWindow size. However, network level optimizations are beyond the scope of this document.

10.7. Web Services

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing and tuning Webservices. It makes use of dynamic bytecode instrumentation to capture performance metrics, including Java remoting metrics, across horizontal and vertical application layers. A central Diagnostics Server correlates resulting measurements to PurePaths .

Figure: The Webservice Diagnosis View

Metrics

Webservices Performance Metrics

• C/S: C=Client side call to a webservice method / S=Server side execution of a webservice method. If both sides of the Webservice call have been detected, the column shows (C/S).

• Endpoint/Class: The webservice endpoint/class. • Method: The called or executed method. • Client Calls: This number indicates how often this webservice method has been called. • Server Execs: This number indicates how often this webservice method has been

executed. • Total Time [ms]: The overall time in milliseconds, it took to call or to execute a

webservice method. • Execution Time [ms]: The time in milliseconds, it took to call or to execute a webservice

method, without nested calls to other methods. • Bytes Sent: The number of bytes sent to or from this webservice method. • Bytes Rcvd: The number of bytes received by or from this webservice method. • CPU Time [ms]: The overall required CPU time, in milliseconds, it took to call or execute

this webservice method.




Tuning Options


• Requests results should be cached where possible. • Cache the web services description language (WSDL) in a centralized database and

periodically check for newer versions. • Cache schema definitions for scalability. • Use simple SOAP data types (String, Int, Float, NegativeInteger).

10.8. Components

Overview

uses a novel approach for diagnosing and tuning Enterprise Java Beans. It makes use of dynamic bytecode instrumentation to capture performance metrics, including Java remoting

metrics, across horizontal and vertical application layers. A central correlates resulting measurements to PurePaths .

Figure: The EJB Diagnosis view

Metrics

EJB Performance Metrics

• Method: The name of the method. • Class: The name of the class. • Type:

o Local Call: local call to an Entity or SessionBean. o Remote Call: remote call to an Entity or SessionBean. o HomeInterface: call to a HomeInterface. o Local HomeInterface: call to a local HomeInterface. o SessionBean: serverside execution of a SessionBean method. o MessageDrivenBean: serverside execution of a MessageDrivenBean method.

• Count: The number of times the EJB method has been called or executed. • Total Time [ms]: The overall time in milliseconds, it took to call or to execute an EJB

method. • Execution Time [ms]: The time in milliseconds, it took to call or to execute an EJB

method, without nested calls to other methods. • CPU Time [ms]: The overall required CPU time in milliseconds, it took to call or to

execute an EJB method.




Tuning Options


• Use local calls: when caller and callee are located in the same JVM, access EJBs via local calls to bypass stubs and skeletons (actually the whole RMI), and security checks.

• Use value objects: avoid single remote calls to prevent network overhead by using the Value Object Pattern.

• Use Stateless Session Beans. • Remove Unneeded Stateful Session Beans: Removing them avoids passivation of the

stateful session beans, and the attendant disk operations. • Cache EJB references: To avoid a JNDI lookup for every request, cache EJB

references in servlets. • Cache home interfaces: Since repeated lookups to a home interface can be expensive,

cache references to EJBHomes in servlets´ init() methods. • Cache EJB resources: Use setSessionContext() or ejbCreate() to cache bean

resources. This is again an example of using bean lifecycle methods to perform application actions only once where possible. Remember to release acquired resources in the ejbRemove() method.

• Explicitly call remove(): Allow stateful session EJB´s to be removed from the container cache by explicitly calling of the remove() method in the client.

• Tune the entity EJB´s pool size: Entity Beans use both the EJB pool and cache settings. Tune the entity EJB´s pool size to minimize the creation and destruction of beans. Populating the pool with a non-zero steady size before hand is useful for getting better response for initial requests.

• Cache bean-specific resources: Use the setEntityContext() method to cache bean specific resources and release them using the unSetEntityContext() method.

• Load related data efficiently for container-managed relationships (CMRs). • Identify read-only beans- Configure read-only entit y beans for read only

operations. • Use container-managed transactions: Container-managed transactions are preferred

for consistency, and provide better performance. • Don´t encompass user input time: To avoid resources being held unnecessarily for

long periods, a transaction should not encompass user input or user think time.

• Identify non-transactional methods: Declare non-transactional methods of session EJB´s with ´NotSupported´ or ´Never´ transaction attributes. These attributes can be found in the ejb-jar.xml deployment descriptor file. Transactions should span the minimum time possible since they lock database rows.

• Use TX_REQUIRED for long transaction chains: For very large transaction chains, use the transaction attribute TX_REQUIRED. To ensure EJB methods in a call chain, use the same transaction.

• Use lowest cost database locking: Use the lowest cost locking available from the database that is consistent with any transaction. Commit the data after the transaction completes rather than after each method call.

• Use XA-Capable Data Sources Only When Needed: Use XA capable data sources, only when two or more data sources are going to be involved in a transaction.

10.9. Naming Services

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing and tuning JNDI calls. The Java Naming and Directory Interface (JNDI) is providing Java applications with a unified interface to multiple naming (Lookup Names) and directory services. JNDI also is the basis for other important APIs, including RMI, EJB, JMS, and CORBA.

Figure: The JNDI Diagnosis view

Metrics

Java JNDI Performance Metrics

• Count: The number of times this particular JNDI method with its Lookup Name has been called or executed.

• Total Time [ms]: The overall time, in milliseconds, it took to execute the JNDI lookup.

• CPU Time [ms]: The overall required CPU time in milliseconds, it took to execute the JNDI lookup.

Grouping

• Lookup Name: The name used to lookup the desired object. • Agent, Class, Method: Information which agent´s method requested to lookup the

desired object.

Context Menu Options

• Details… : shows detail information for the selected JNDI record • Subscribe Measures… : Opens the Measure Picker dialog to add measures to a

subscription. This option is only available during Realtime sessions. • Open PurePaths : Creates a new PurePath view containing all PurePaths that are

referenced by the actual selection.

10.10. Messaging Services

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing and tuning JMS. It makes use of dynamic bytecode instrumentation to capture performance metrics, including Java remoting metrics, across horizontal and vertical application layers. A central Diagnostics Server correlates resulting measurements to PurePaths .

Figure: The JMS Diagnosis view

Metrics

JMS Performance Metrics

• Destination/MsgType: The rows show Messages grouped by Destination and MessageType.

• Count Sent: The number of times this Destination has sent a message with this MessageType.

• Time Sent [ms]: The time, in milliseconds, it took to send from this Destination with this MessageType.

• Bytes Sent: The number of bytes sent from this Destination with this MessageType. • Count Rcvd: The number of times this Destination has received a message with this

MessageType. • Time Rcvd [ms]: The time, in milliseconds, it took to receive by this Destination with this

MessageType. • Bytes Rcvd: The number of bytes received by this Destination with this MessageType.




Tuning Options


• Use getConnection(): JMS connections are served from a connection pool. This means that calling getConnection() on a Queue connection factory is fast.

• Tune the Message-Driven EJB´s Pool Size: Tune the Message-Driven EJB´s pool size to optimize the concurrent processing of messages.

• Cache Bean-specific Resources: Use the setMesssageDrivenContext() or ejbCreate() method to cache bean specific resources, and release those resources with the ejbRemove() method.

• Limit Use of JMS Connections : When designing an application that uses JMS connections try to use connections sparingly, by either pooling them or using the same connection for multiple sessions. The JMS connection uses two threads and the sessions use one thread each. Since these threads are not taken from a pool and the resultant objects aren´t pooled, you could run out of memory during periods of heavy usage. One workaround is to move createTopicConnection into the init of the JSP. Make sure to specifically close the session because when it stays open it ties up resources.

10.11. Methods

Overview

The Method view is divided into horizontally tiled panes, of adjustable height. The middle pane shows all methods included in the captured PurePaths . The upper and lower panes are linked to show relationships between a selected method in the middle panes and the methods that call it and that it calls. The upper pane shows all callers of the middle pane´s selected method, the lower pane shows all callees of the middle pane´s currently selected method. A doubleclick on a caller method (upper pane) or on a callee method (lower pane) automatically shifts the selection in the middle pane that method, and in turn, the upper pane and lower pane will show the caller and callees of the newly selected method respectively.

Figure: Method View

Metrics

Method Performance Metrics

• Method, Caller, Callee: Displays a string representing the method name including argument types.

• API: The API identifier with which this method call is associated. • Class: The full-qualified class name of this method. • Count: The number of times this method has been executed. • Exec Time [ms]: The method´s execution time measured as its response time minus the

response time of all called (and instrumented) methods. • Total Time [ms]: Is the overall duration of this method call from method entry until

method exit. • Exceptions: Number of times the method was exited due to an exception event. • Exec CPU Time [ms]: The CPU time that was taken for execution within this method

only. • Total CPU Time [ms]: Displays the total CPU time required for executing this method

call method entry until method exit.




10.12. Memory Allocations

Overview

The Memory Allocations view coprises the memory allocation events occurred within PurePaths. All instanciations of objects matching a Memory Sensor rule that occurred within a method call being part of a PurePath are listed here. To get information about memory consumption independent from PurePaths, use the Total Memory view.

Figure: Memory Allocations View

Metrics

Memory Allocation Metrics

• new Class: Class of the new generated object instance • Instances: Number of instances of a specific class created by one allocating method of

one allocating class within the perceived set of PurePaths • Allocating Class: Class that generated the new object instance • Allocating Method: Method which generated the new object instance • File: Name of the source file of the allocating class, if availiable. • Line#: Line number within the source file were the allocation is performed. If allocation

takes place in a native methods the line number is set to "-" • Agent: Identifies the Diagnostics Agent that registered the allocation.




10.13. Synchronization

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing synchronization. It makes use of dynamic bytecode instrumentation to capture performance metrics, including synchronization time and wait time. A central Diagnostics Server correlates resulting measurements with PurePaths .

To measure synchronization and wait times, Synchronization diagnosis must be enabled prior to the start of the application.

Figure: The Synchronization Diagnosis View

Metrics

Java Synchronization Performance Metrics

• Method: The method in which the synchronization occured. • Class: The class in which the method is defined. • Call Count: How often the method was called. • Block Count: How often the synchronized blocks blocked in this method. The

synchronization threshold is used to differentiate between blocking and non-blocking calls.

• Wait Count: How often the thread waits for other threads to be notified, the thread sleeps or is parked in this method.

• Sync Sum [ms]: The total time the method spent waiting to gain a monitor. • Sync Avg [ms]: The average synchronization time. • Sync Max [ms]: The maximum synchronization time. • Sync Min [ms]: The minimum synchronization time. • Wait Sum [ms]: The total time the method spent waiting. • Wait Avg [ms]: The average wait time.

• Wait Max [ms]: The maximum wait time. • Wait Min [ms]: The minimum wait time. • Thread: The name of the thread in which this method was called.


• Subscribe Measures… : Opens the Measure Picker dialog so that measures can be added to a subscription. This option is only available during real-time sessions.


10.14. Custom Entry Points

Overview

The PurePaths Entry Points shows an aggregated representation of equal PurePaths with same entry points. It is used to get a quick overview of all different types of PurePaths and to provide statistical data like overall sum or average of execution based values. These views make it possible to quickly associate a performance issue to a group of PurePaths and furthermore to a specific PurePath instance.

The PurePaths Entry Points view has the same visual structure as the PurePath view. The PurePaths Entry Points View contains columns for displaying statistical distributed (aggregated) values. Both user interactions and context menu options behave similarly as in the PurePath view.

Metrics

PurePaths Entry Points Performance Metrics

Figure: PurePaths Entry Points View

• PurePath Entry Points: Shows a string representing the PurePath Entry Point.

• Entry Method: The entry method where the PurePath starts. • Entry Class: The entry class where the PurePath starts. • Agent: Contains the Agent instances by name from which this PurePaths Entry Point

starts. • Count: The number of equal PurePaths contained in this PurePaths Entry Point . • Total Avg [ms]: This value describes the duration average (or average of total execution

times) of all PurePaths contained in this PurePaths Entry Point. • Total Min [ms]: Shows the value of duration (or total execution time) that is the minimum

of all PurePaths contained in this PurePaths Entry Point. • Total Max [ms]: Shows the value of duration (or total execution time) that is the

maximum of all PurePaths contained in this PurePaths Entry Point. • Total Sum [ms]: This value is the duration aggregate (sum of total execution times) of all

PurePaths contained in this PurePaths Entry Point. • CPU Total Avg [ms]: This value shows the average of total CPU times of all PurePaths

contained in this PurePaths Entry Point. • CPU Total Min [ms]: Shows the value of total CPU time that is the minimum of all

PurePaths contained in this PurePaths Entry Point. • CPU Total Max [ms]: Shows the value of total CPU time that is the maximum of all

PurePaths contained in this PurePaths Entry Point. • CPU Total Sum [ms]: This value is the sum of total CPU times of all PurePaths

contained in this PurePaths Entry Point.




View toolbar items:

• Aggregate by : Sets the aggregation mode. o Agent : Thus PurePaths can have equal structures but different involved agents

(in case of agent clustering) this aggregate mode only accepts PurePaths from exactly the same agent, e.g. myAgent@myHost:1.

o Tier : This mode allows the aggregation of PurePaths through tiers where agents of the same configuration are involved. More precisely, only the agent name is responsible for accepting a PurePath for aggregation. For example, a PurePath from myAgent@myHost:1 will also be aggregated with the PurePath from myAgent@anotherHost:2.

10.15. Tagged Web Requests

Overview

The Webpage view provides the results of a loadtest for webpages.

Figure: The Webpages Diagnosis View

Metrics

Webpages Performance Metrics

• Timer Name: The Timer Name is a identifier for a webpage provided by a loadtest tool. • Page Context: The Page Context is a identifier for a part of webpage provided by a

loadtest tool. • Count: The number of times this webpage has been rendered. • Total Time [ms]: The overall time, in milliseconds, it took to render this webpage. • Bytes Sent: The number of bytes sent as response from the servlet. • Bytes Rcvd: The number of bytes received as request to the servlet. • CPU Time [ms]: The overall required CPU time, in milliseconds, it took to render this

webpage.

View toolbar items:

• Group by : Select grouping - Either group by Timer Name/Page Context or only by Timer Name.


11. Diagnose Events

Overview


Text Search


Filter

Overview



Filter Usage




Sort


Customize


Reporting





11.1. Exception

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing exceptions. In the Java programming language exceptions are used to provide error-handling capabilities for applications. dynaTrace Diagnostics makes use of dynamic bytecode instrumentation to capture throwable classes, messages and stack traces of java classes that extend java.lang.Exception .

Figure: Exception Diagnosis view

Metrics

Exception Metrics

• Count: The number of times this particular class with its throwable class, message and stack trace has been instantiated.

View toolbar items:

• Group by : o Throwable Class/Message : This is the default setting for the Exception View.

Exception Records are listed in diagnostics view grouped by their throwable classes and messages. Exceptions with the same throwable class but with varying message contents are shown as individual exception records.

o Throwabable Class : Exception Records are listed in diagnostics view grouped by their throwable classes ignoring varying message contents.

Grouping

• Throwable Class: Class that instantiated the exception. • Message: Message of the instatiated exception • Agent, Class, Method: Information which agent´s method was instrumented to request

the exception instantiation.

Details

• Stack Trace: A list of the methods executed in sequence that led to the exception.

Figure: Exception Details

Configuration

dynaTrace Diagnostics offers the Exception Sensor Configuration Dialog to define filter criteria in order to shrink the set of extended exceptions that should be analyzed. This configuration is part of the J2EE Sensor Configuration Dialog.

Figure: Exception Sensor Properties Configuration




11.2. Logging

Overview

dynaTrace Diagnostics uses a novel approach for diagnosing logging calls executed by the Java Logging API and the Log4J Logging Framework. It offers information about the severity of logging messages. Logging APIs and Frameworks allow the developer to control which logging information is processed with arbitrary granularity.

Figure: Logging view

Metrics

Logging Metrics

• Count: The number of times this particular method with its severity and message has been executed.

Grouping

• Name: user defined logger name (eg. applications often use the classname retrieving a current logger).

• Severity: The severity (level) used for logging the message. Java Logging API: SEVERE , WARNING , INFO , CONFIG , FINE , FINER , FINEST Log4J Logging Framework: FATAL , ERROR , WARN , INFO , DEBUG

• Message: The message that is logged by the logging API / Framework. • Agent, Class, Method: Identifies which agent´s method requested the logging.

Configuration

dynaTrace Diagnostics offers the Logging Sensor Configuration Dialog to define filter criteria in order to shrink the set of extended logging events that should be analyzed. This configuration is part of the J2EE Sensor Configuration Dialog and includes filter criteria for the logger name and severity.

Figure: Logging Sensor Properties Configuration




11.3. Notification

Overview

The Notifications Views serves as event logging mechanism for Thresholds based upon License event or Threshold violations. Measures that exceed defined Thresholds are represented in this view. Thresholds Violations for Logging or Exception Measures only show up in this View if "Check PurePaths for exception events" and "Check PurePaths for logging events" are enabled. For more information see Add Application .

Notifications are useful starting points for AUD performance analysis.

Figure: Notification view

Notification Details Table

• Severity: o Categorizes a Notification as "Warning" o Indicates that a "Severe" Notification has been thrown.

• Date: The start time of the interval in which the Notification(s) occurred. • Key: The key classifies the notification providing information about metricgroup, metric

and measure of the violated threshold. • Message: Represents which observed metric has exceeded which limit. • Description: Displays the measurement that exceeded the threshold boundaries and

detailed information of the related threshold configuration. (i.e.: Measured peak value: 7938.13, Upper Severe Bound: 60.00, Upper Warning Bound: 0.00, Lower Warning Bound: 0.00, Lower Severe Bound: 0.00)

• Source: Represents the category where the Notification has been thrown. "License" for dynaTrace Diagnostics license based events and "Threshold" for defined threshold violations.

• PurePath Key: The PurePath key contains RS (sessionId), PT (PurePath Tag ID) and PA (PurePath Tag Agent ID). This key is used for the PurePath find feature .

Context Menu Options

• Details… : shows detail information for the selected Notification • Open PurePaths : Creates a new PurePath view containing all PurePaths that are

referenced by the actual selection.

12. Diagnose Runtime

Overview


Text Search


Filter

Overview



Filter Usage




Sort


Customize


Reporting





12.1. Thread

Overview

Thread view provides information about threads and their states. The information relates to the Diagnostics Agent that has been selected in the drop-down box at the top of the view. The agent list provided in this drop-down box can be refreshed by clicking the Refresh symbol next to the box or by using the Refresh button in the context menu. This view is divided into two areas. The upper area provides information about currently running threads. This list can be refreshed by clicking the Refresh button or by selecting Refresh from the context menu. The lower area shows the stack trace of the selected thread, and the monitors that the thread owns.

Figure: Thread Diagnosis View

Metrics

Thread Performance Metrics

• Thread Id: The identity hashcode of the thread, for correlation. • Group: The name of the thread group the thread belongs to. This column may be empty

because not all threads must belong to a group. • Name: The name of the thread. • CPU Time [ms]: The time, in milliseconds, that the thread used the CPU. (This

information is only available for J2SE 5.0 and higher) • Start Time: The time when the thread was started. • State: The current state of the thread. There are six defined states:

o New: A thread having this state is created but has not been started. Therefore there is no stack trace available for this thread.

o Runnable: A thread having this state can be executed by the VM. o Blocked: A thread having this state is waiting to gain a monitor. o Waiting: A thread having this state is either waiting to be notified, sleeping or

parked. o Timed waiting: A thread having this state is waiting a fixed period of time. o Terminated: A thread having this state has finished.

• Waiting On: The monitor (if any) that the thread is waiting on. • Owned By: The owner of the monitor that this thread is waiting on (if any). A monitor

may not have an owner. • Owned Monitors: The number of monitors owned by this thread.

Stack Trace

• #: The number of the stack trace element. • Class: The fully qualified name of the class, which contains the method that produced

the stack trace element. • Method: Name of the method. • Line: Line number of the source file that is currently executing. • Source File: The name of the source file for the executed method.

Owned Monitors

• Object: Object ID. • Class: Monitor class. • Entry Count: Number of times that the monitor was entered in this thread. • Waiter Count: Number of threads that are waiting to gain this monitor. • Notify Waiter Count: Number of threads that are waiting to be notified by this monitor.


• Select Owner Thread : If the thread is waiting on a monitor, the thread who owns this monitor is selected. This action can also be performed via a double-click.

• Search PurePaths : Searches the PurePaths for the thread ID, and opens the PurePath view with the results of the identified thread ID.

12.2. Total Memory

Overview

This view provides information about the heap space content of the JVM in a specific moment. The heap space content contains all referenced objects as well as objects which are no longer referenced but not freed through the garbage collector. The view is divided into two halves. The upper half contains the recent Memory Dumps in the Dump tab and visualizes selected memory dump values from the dump difference table in the Chart tab. The lower half provides the dump difference table, which shows the difference between two selected memory dumps.

The Memory View tool bar includes buttons for generating a memory dump , deleting a seleted memory dump , comparing memory dumps , and running garbage collection .

View toolbar items:

• Create Memory Dump : creates a memory dump for the selected agent • Delete Memory Dump : deletes the selected memory dump • Calculate Dump difference : calculates the difference of two selected memory dumps • Run Garbage Colletor : activates the Garbage Collector on the selected agent • Agents : agent for which information is provided in the view

The memory view helps to locate memory leaks. Following steps are recommended to locate memory leaks:

1. Create a memory dump using the memory dump button located to the far left of the Agent drop down list.

2. Perform the memory consuming action and if necessary create further memory dumps 3. After finishing the memory consuming action create a further memory dump

4. Change the settings in the scheduled dump function combobox ( ) to create memory dumps at specified time intervals without the need of user interaction.

The memory consuming classes can be found through comparing the columns in the memory dumps and trough comparing the memory usage of the classes over time.

Note: A memory dump can only be created for a connected agent.

Memory Dump Information table

• ID: The identifier of the memory dump • Time [ms]: The creation time of the dump • Agent: The designator for which the dump is created

Figure: Memory Diagnosis View: Dump Information

Metrics

Memory Difference Performance Metrics

• Class: The fully qualified classname. Classes from different classloaders are not differentiated

• Bytes: The sum of bytes which all object instances of a class allocate. The shown value is the value of the eldest dump for this agent.

• Instances: The sum of object instances of the class in memory. The shown value is the value of the eldest dump for this agent.

• Delta Bytes: The difference of the sum of bytes for the two selected dumps • Delta Instances: The difference of the sum of instances for the two selected dumps • % Delta Bytes: The difference of the sum of bytes for the two selected dumps in

percentage • % Delta Instances: The difference of the sum of instances for the two selected dumps in

percentage

Figure: Memory Diagnosis View: Heap Trace chart of selected values


• Refresh: refreshes the list of available agent

Memory Diagnostics Information Chart

Context menu options • Zoom In : provides option to change either or both axes to provide finer granularity perspective in the chart. • Zoom Out : provides option to change either or both axes to provide courser granularity perspective in the chart. • Auto Range : provides option to change either or both axes to return to the default axes ranges.

12.3. Selective Memory

Overview

The selective memory view lists the instances of classes matching to a Memory Sensor rule that

exists within the memory of the SUD at the time the view was opened. Use the button to refresh the view with the current allocation data. To remove unreferred objects from memory, a garbage collection run can be manually initiated with the button. The Diagnostics Agent

selection box can be used to select one of the connected Diagnostics Agent of the SUD as source for the view. Alternatively, selecting "all agents" uses all connected Diagnostics Agents as source of the view.

Figure: Selective Memory View

Metrics

Selective Memory Metrics

• new Class: Name of a class that is monitored for instanciations. • Instances: Number of instanances of a monitored class, allocated by one method of one

allocating class. • Allocating Class: Name of the class that allocated the monitored class • Allocating Method: Name of the method that allocated the monitored class • File: Name of the source file of the allocating class, if available. • Line#: Line number within the source file were the allocation is performed. If allocation

takes place in a native methods the line number is set to "-" • Collection Size: If the monitored class is a map or a collection, size of the collection or

map as reported by the size() method. Set to "-" for other classes. • Agent: Agent instance that instrumented the allocating class.


• Subscribe Measure… : Opens the Measure Picker dialog to add measures to a subscription. This option is only available during Realtime sessions.


13. Reporting

Overview

dynaTrace Diagnostics provides reporting components, called Reportlets, that produce HTML and PDF output based on dynaTrace Diagnostics analysis and diagnostics data. Reportlets can filter and pre-select the data for the final reports. Report configuration options include:

• selecting of report columns • defining report column sorting • selecting the number of rows that will be reported

Multiple Reportlets can be combined in a summary report generating HTML and/or PDF output. Reports are available in realtime, online and offline sessions.

View Report

Getting started

A View Report can either be called from the cockpit´s navigation tree by clicking the wished report or by clicking the report symbol within the activated view.

Report Configuration

Using the report configuration users can:

• Enter a description for the final output (e.g. additional information describing the report´s content).

• Define the output format (PDF, HTML, CSV). • Select the filename for the report export. • Create a temporary report by deselecting "Export to file".

Figure: Report Configuration Manager

After pressing "Generate" the reportlets are handed over to the ReportManager that executes the reportlet and preprocesses the report data. The resulting report file is launched by the default application.

Report Rendering

Report rendering produces HTML or PDF output written to a temporary or specified file - as defined during report configuration. After the rendering has finished the default viewer is launched and displays the generated report.

Figure: Sample HTML Report

Summary Report

Getting started

The summary report combines multiple reportlets and produces one single HTML or PDF file. The summary report can be launched from the cockpit´s navigation tree.

Report Configuration

Each reportlet can be configurated individually.

Figure: Report Configuration Manager

14. Management and Integration

This chapter explains following topics:

• Integration with Load Testing and Monitoring Tools • JMX Management • Command Line Tool

14.1. Load Testing and Monitoring Integration

This chapter explains how to integrate dynaTrace Diagnostics with several Load Testing and Monitoring Tools.

The following chapters cover these topics:

• Integration with Segue/Borland SilkPerformer and SilkCentral Performance Manager • Integration with Mercury LoadRunner • Integration with Other Load Testing and Monitoring Tools

14.2. SilkPerformer Integration

Segue/Borland SilkPerformer and SilkCentral Performance Manager Integration

dynaTrace Diagnostics can be used in combination with Segue´s/Borland´s SilkPerformer and SilkCentral Performance Manager (> version 7.0). If you perform Load Tests using the SilkPerformer workbench you can diagnose Web Services (SilkPerformer SOAP, Java/axis and .Net SOAP stacks) with dynaTrace Diagnostics.

The following subchapters explain the Integration with SilkPerformer 7.2, 7.3.1 and Borland SilkPerformer 2006 / 7.4.

Borland SilkPerformer 2006 Integration

For SilkPerformer version 2006 simply activate the dynaTrace Diagnoctics PlugIn in the System Settings of your SilkPerformer Installation.

For further information please refer to the SilkPerformer UserGuide or to the PlugIn Documentation in <dtdhome>\doc\manual.

Segue/Borland SilkPerformer v. 7.3.1 Integration

For SilkPerformer version 7.3.1 simply add the WebSetDiagnostics function to the TInit transaction of your Silkperformer script. An example integration looks as follows:

benchmark SilkPerformerRecorder

use "WebAPI.bdh"

dcluser

user

VUser

transactions

TInit : begin;

TMain : 1;

var

dclrand

dcltrans

transaction TInit

begin

WebSetDiagnostics(WEB_DIAG_dynaTraceDiagnostics);

end TInit;

...

Segue SilkPerformer v. 7.2 Integration

For SilkPerformer 7.2, load test transactions can be tagged and traced with dynaTrace Diagnostics by using the WebSetHttpTag - function in the SilkPerformer Workbench (Model Script) and adding the call for the WebSetHttpTag - function in the SilkPerformer TInit

transaction. Following tags for dynaTrace Diagnostics are supported: WEB_TAG_FLAG_Timer , WEB_TAG_FLAG_RequestId , WEB_TAG_FLAG_UserId , WEB_TAG_FLAG_Time and WEB_TAG_FLAG_PageContext . For additional help about using WebSetHttpTag ,

please check the SilkPerformer Online Help. To use the SilkPerformer Workbench with dynaTrace Diagnostics, modify the Model Script - file (*.bdf) according to the bold parts below.

//------------------------------------------------- ---------------------

// Recorded 12/23/2005 by SilkPerformer Recorder v7 .2.0.2553

//------------------------------------------------- ---------------------

benchmark SilkPerformerRecorder

use "WebAPI.bdh"

dcluser

user

VUser

transactions

TInit : begin;

TMain : 1;

var

dclrand

dcltrans

transaction TInit

begin

WebSetHttpTag("dynaTrace", WEB_TAG_FLAG_Timer | W EB_TAG_FLAG_RequestId |

WEB_TAG_FLAG_Time | WEB_TAG_FLAG_UserId | WEB_TAG_F LAG_PageContext);

end TInit;

...

14.3. LoadRunner Integration

Mercury LoadRunner Integration

HTTP Requests generated trough LoadRunner´s Virtual User Generator can be evaluated by the Diagnostics Server. This subchapter explains the necessary modifications to your script.

Start by pasting the red lines of code directly below any include directives, as shown in the example. You will find them within the LoadRunner_HTTP_Header_Tag.txt file inside the samples subdirectory of your dynaTrace Diagnostics installation.

#include "as_web.h"

addDynaTraceHeader_PC(char* timerName, char* pageCo ntext){

char* headerValue;

int headerValueLength;

headerValueLength = strlen(timerName) + 4;

if(pageContext != NULL) headerValueLength = header ValueLength + strlen(pageContext) + 4;

headerValue = (char*) malloc(sizeof(char) * header ValueLength);

strcpy(headerValue, "NA=");

strcat(headerValue, timerName);

if(pageContext != NULL){

strcat(headerValue, ";PC=");

strcat(headerValue, pageContext);

}

web_add_header("dynaTrace", headerValue);

free(headerValue);

}

addDynaTraceHeader(char* timerName){

addDynaTraceHeader_PC(timerName, NULL);

}

Action()

{

...

The code defines two methods, addDynaTraceHeader(char* timerName) and addDynaTraceHeader_PC(char* timerName, char* pageCo ntext) .

timerName is a unique identifier for a specific request to your web application, like "login_page", "contacts" or "product_download_page". All requests prepared with the same timerName will be correlated in the Diagnostics Client Webpages view.

The second function can be used to further distinguish between the different requests to the same web page, like "login_page" and "successful" or "login_page" and "failed". In most cases it will be sufficient to use just a timerName.

The sample code given below shows how to place the method calls inside your virtual user script.

Action()

{

addDynaTraceHeader("goSpace_frontend");

web_url("frontend",

"URL=http://lab1:9090/frontend",

"Resource=0",

"RecContentType=text/html",

"Referer=",

"Snapshot=t1.inf",

"Mode=HTML",

EXTRARES,

"Url=/frontend/images/topbg.gif",

"Referer=http://lab1:9090/frontend/main.jsp;jsessio nid=B958B4540D51E6C07A9AD0B0EEEAFBEF?v

iew=home", ENDITEM,

LAST);

lr_think_time( 7 );

addDynaTraceHeader("goSpace_last_minute");

web_link("last minute",

"Text=last minute",

"Snapshot=t2.inf",

EXTRARES,

"Url=images/topbg.gif",

"Referer=http://lab1:9090/frontend/menu.do?action=s pecial", ENDITEM,

LAST);

...

14.4. Integration of other Load Testing and

Monitoring Tools

Generic Load Testing and Active Monitoring Tool Integration

For diagnosing Web Services in dynaTrace Diagnostics with other General Load Testing and Monitoring Tools it is necessary to add the following information to the HTTP headers generated by the load testing tool: HTTP header: dynaTrace: VU=1;PC=.1;ID=4;NA=SearchPage Check out the sample HTTP header below:

POST /onca/soap?Service=AWSECommerceService HTTP/1. 1

Content-Type: text/xml; charset=utf-8

Host: soap.amazon.com

Content-Length: 2566

Connection: Keep-Alive

Accept: */*

User-Agent: Mozilla/4.0 (compatible; MSIE 5.5; Wind ows NT)

dynaTrace: VU=1;PC=.1;ID=4;NA=SearchPage

Description of the HTTP header string for dynaTrace Diagnostics:

• ID: This represents the ID (serial number or timestamp) of the request. • PC: This represents the page count of the request. • VU: Indicates the number of the virtual user who sent the request. • NA: This represents the timer name of the request.

14.5. JMX Management

Overview

Using Java Management Extension Java based applications can be managed and monitored. dynaTrace Diagnostics supports Java Management Extensions (JMX) as its interface for Third Party Applications integration. Through the interface integrations can:

• Retrieve server statistics (events, PurePaths, defined profiles, ...) • Execute base server operations (start server, stop server, dumping memory sessions,

hotupdate) - see dtdcmd (Command Line Tool) • Retrieve information about JVM Health (class loading, garbage collection, memory, ...) • View the collection of defined realtime metrics, measures and measurements • Query application information (latest pure path, collection of PurePaths, PurePath´s

nodes)

Server Statistics

• EventInformationBufferMaxSize: the maximum buffersize in bytes for storing event information objects

• EventInformationBufferSize: the current buffersize in bytes for storing event information objects

• PurePathBufferMaxSize: the maximum buffersize in bytes for storing pure paths • PurePathBufferSize: the current buffersize in bytes for storing pure paths • PurePathBufferNodesCount: the number of pure path nodes stored in the buffer • PurePathNodesCount: the number of pure path nodes • IncompleteNodeCount: the number of unpaired events that led to incomplete nodes • CounterSkippedNodesDueToTruncation: the number of pure path nodes that were

skipped due to truncation of the pure path

• CounterSkippedExitEventsDueToMissingEntryEvent: the number of exit events that were skipped because their entry points were missing

• Profiles: the list of application profiles defined in server´s profile configuration directory • TotalNumberOfEventsReceived: the number of events the server received from the

agents

Base Server Operations

• clear: clearing the memory session by clearing its pure paths • shutdownServer: shuts down the server • activateProfile: activates an application profile specified by its name • dump: dumps the pure paths hold by the memory session to a database session file • hotupdate: If the agent is running under a JVM that supports hot update, the loaded

classes are reinstrumented using the active profile • restartServer: performs a server shutdown followed by its restart • startSessionRecording: prepares the storage of the pure paths held in the memory

session to a database session file specified by its session name • stopSession: performs the storage of the pure paths held in the memory session to a

database session file

Application - Execution

• LatestPath: gets the latest PurePath found in the memory session • Paths: lists the PurePaths found in the memory session • getPath: lists the nodes of a PurePath specified by the PurePath´s trace tag (eg.

[email protected]#2 )

• Notifications: lists the notifications that occured since the last call of this method

Application - Metrics / Measures / Measurements

Measures for Realtime Analytics and Charting are specified using the client´s measurement configuration editor. These measures´ metrics and their values can be retrieved via JMX. The snapshot shows the measures using Java Management and Monitoring Console ( service:jmx:rmi:///jndi/rmi://localhost:2020/com.dy natrace.diagnostics.management.10 ):

14.6. Command Line Tool

Overview

dynaTrace Diagnostics offers an easy to use command line interface for basic server operations. Basic operations can be executed without requiring an installed client. It´s a less powerful alternative to the JMX management Interface .

The command line tool (dtdcmd) is shipped as a Windows Batch file ( dtdcmd.cmd ) and as a shell script ( dtdcmd.csh ) for the Unix/Linux version. It is found in the root of dynaTrace

Diagnostics installation folder. When called without command line parameters the tool´s usage is shown.

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

dynaTrace Diagnostics Commandline Tool Copyright (C ) 2004-2007 dynaTrace software GmbH

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

version 1.6.0.524 built Sun Apr 02 13:39:55 CEST 20 06

Usage:

dtdcmd [-options] hostname[:port] [dtdhome]

Where options include:

-stat displays server statistics

-dump dump the recorded pure paths,

-path displays the latest pure path.

-verbose provides a more detailed output.

-shutdown shutdown server.

-startup startup server.

-restart restart server.

-hotupdate performs a hot update of server classe s using active profile.

-startsession record a new session, optionally us ing sessionname

[-fsessionname]

-stopsession stop recording session.

Parameters

• Server Statistics: Prints information about Heap Memory, Non Heap Memory, Capturing Mode, Session Recording Status, Events and PurePaths.

• Dump Realtime Session: Saves the recorded PurePaths in a uniquely named database session file.

• Latest PurePath: Prints the latest PurePaths containing nodes´ method, execution and total CPU time values.

• Hot Update: If the agent is running under a JVM that supports hot update, the loaded classes are reinstrumented using the active profile.

• Start Session: Starts the recording of a new session. • Stop Session: The currently recorded session is saved to an uniquely named database

session file.

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

dynaTrace Diagnostics Commandline Tool Copyright (C ) 2004-2007 dynaTrace software GmbH

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

version 1.6.0.524 built Sun Apr 02 13:39:55 CEST 20 06

Connecting: //localhost:2020/com.dynatrace.diagnost ics.server.10

---- Statistics ---------------------------------

HeapMemoryCommitted=774242304

HeapMemoryMax=775487488

HeapMemoryUsed=98331768

NonHeapMemoryCommitted=138084352

NonHeapMemoryMax=167772160

NonHeapMemoryUsed=20752656

isCapture=true

startRecordingTime=null

EventInfoBufferMaxSize=1000

EventInfoBufferSize=1000

EventsReceivedCount=9292

EventsUnpairedCount=0

PurePathBufferMaxSize=1429497

PurePathBufferSize=26

PurePathBufferNodesCount=4640

PurePathNodesCount=4666

SkippedEvents=0

SkippedPurePaths=0

Server Statistics

• HeapMemoryCommited: The amount of heap memory in bytes that is committed for the Java virtual machine to use.

• HeapMemoryMax: The maximum amount of heap memory in bytes that can be used for memory management.

• HeapMemoryUsed: The amount of used heap memory in bytes. • NonHeapMemoryCommited: The amount of non-heap memory in bytes that is

committed for the Java virtual machine to use. • NonHeapMemoryMax: The maximum amount of non-heap memory in bytes that can be

used for memory management. • NonHeapMemoryUsed: The amount of used non-heap memory in bytes. • isCapture: Status of global capturing mode - true, if agents may send events to the

server. • startRecordingTime: Start time of memory session recording - null, if currently no

session is recorded. • EventInfoBufferMaxSize: The maximum buffersize in bytes for storing event information

objects. • EventsReceivedCount: The number of received events. • EventsUnpairedCount: The number of unpaired events that will lead to incomplete

nodes. • PurePathBufferMaxSize: The maximum buffersize in bytes for storing pure paths. • PurePathBufferSize: The current buffersize in bytes for storing pure paths. • PurePathBufferNodesCount: The number of pure path nodes stored in the pure path

buffer. • PurePathNodesCount: The number of pure path nodes. • Skipped Events: The number of events that are skipped for all agents if saturation

threshold is exceeded. • Skipped Pure Paths: The number of pure paths that are skipped for all agents if

saturation threshold is exceeded.

15. Shortcut Reference Table

General

Key Action

F5 Refreshs the active view

F3 Searches for the next textual occurrence within the active view

Ctrl+F3 Searches for the previous textual occurrence within the active view

Method Browser

Key Action

Ctrl+ Cursor Left Opens the selected tree node

Ctrl+ Cursor Down Closes the selected tree node

Ruleset Editor

Key Action

Ctrl+ Cursor Up Moves the selected rule up

Ctrl+ Cursor Down Moves the selected rule down

Ctrl+ Cursor Left Opens the selected tree node

Ctrl+ Cursor Right Closes the selected tree node

Space Changes the rule status of the selected rule

Delete Remove the selected rule from the ruleset

Insert Open a dialog to add a rules to the ruleset

E Open a dialog to configure the selected series

Chart View / Chart Table

Key Action

Insert Open a dialog to add measures to the chart

Delete Remove selected series from the chart

E Open a dialog to configure the selected series

Space Open a dialog to edit the charted measures of the selected series

H Hides/Shows the selected series

Chart View / Chart Table / Series Configuration

Key Action

Insert Add new measures to subscription

E Edit the selected measure

Delete Remove selected measure from the series configuration

16. FAQ/Troubleshooting

General

Q1: Why do I get no PurePaths?

Q2: Which OS does the Diagnostics Agent support?

Java

Q3: Why does the System under Diagnosis (SUD) not s tart after deploying the Diagnostics Agent?

Q4: Where can I find the JVM output?

Q5: Where can I find the Agent output?

Q6: How can I find out the Java Version the SUD is using?

Q7: Why does the SUD JVM crash when a memory dump i s performed?

.NET



General

Q1: Why do I get no PurePaths?

A4.1: Make sure that capturing is enabled and Sensors are active. → see Sensor Configuration

A4.2: Make sure that Sensors have been placed properly. Check out the Deployed Sensors table in the System View .

A4.3: Make sure to apply the settings of the system profile are propagated to the agents. Please see description of the Hot Update feature . In some cases, a restart of the SUD may be required.

A4.4: Make sure to activate Sensors as entry points for PurePaths. Default entry points are Servlets/JSPs and Web-Services. see Sensor Configuration .

A4.5: Add custom Sensors and specify methods as entry point for PurePaths. see Sensor Configuration .

• Place Sensors into methods that will act as starting point for PurePaths. This can be achieved by opening the Classbrowser within the Sensor Rules editor and selecting one or more classes and methods of the SUD. In the method rule, enable the option "allow to start PurePaths from this method". → see Methods .

A4.6: License has expired or number of active agents exceeds the license.

Q2: Which OS does the Diagnostics Agent support?

A6.1: For UNIX OS use the command " file libdtdagent.so " e.g.

bash-2.03$ file libdtdagent.so libdtdagent.so: ELF 64-bit MSB dynamic lib SPARCV9 Version 1, dynamically linked, stripped

A6.2: 32 and 64 bit versions of agent libraries are available for the Windows OS. Use the properties option of the file explorer for the *.dll file to determine the version of an agent library.

Java


A1.1: Verify the correct use of the -Xrun and -agentpath parameter.

• Windows OS needs precautions with blanks in path names, such as the "Program Files" folder. Check the foldernames for blanks, and in case there are blanks enclose the path with double quotes as described in → Agent Configuration

• Is the -Xrun used with J2SE 5.0 or later? Ensure that the option -agentpath is used for J2SE 5.0 or later → Agent Configuration

A1.2: Analyse the JVM output.

• Does the JVM report e.g. "library not found" at startup?

o This can happen when the Diagnostics Agent cannot be found (dtdagent.dll/libdtdagent.so). Check path names and file access permissions.

o In rare cases it can further happen, primarily on older unix systems, that the kernel is incompatible with the glibc libraries used by the Agent. Upgrade to a newer operating system or contact [email protected] to ask for certified platforms.

• Did the JVM crash? o In very rare situations it can happen that the JVM´s hotspot compiler cannot

correctly process the bytecode. Workaround: Remove Sensors systematically until the JVM runs successfully.

• Does the JVM output contain messages from the nativeDiagnostics Agent? Note: the native Agent Diagnostics Agent output lines can be recognized by the label "[native]"

o If there is no message marked with the label "[native]" from the native Agent, the JVM did not correctly receive the additional options for injecting the Diagnostics Agent. Ensure that the additional JVM parameters -Xrun and -agentpath are added to the startup script of the SUD and properly passed to the JVM → see Application Integration

o If there is a message with the label "[native]", but the JVM aborts, the Diagnostics Agent version may not be compatible with the Diagnostics Server. Redeploy the correct version of the Diagnostics Agent to the SUD and ensure that the correct version of the Diagnostics Agent is loaded.

• Does the JVM output contain messages from the Java Diagnostics Agent available in JVM Output? Note: the Java Agent Diagnostics Agent output lines can be recognized by the label "[java]"

o If there is no "[java]" line in the output, then its likely that the Agent cannot connect to the Diagnostics Server due to one of the following reasons:

� The Diagnostics Server has not been started within the default limit of 60 seconds after starting the SUD. Make sure to start the Diagnostics Server prior to starting the SUD.

� The TCP/IP connection to the Server cannot be established Make sure that the network and firewall is configured properly → see Firewall

� The JVM is configured for debugging or to load multiple multiple Agents. E.g. when debugging is enabled with JVM options −Xrundbgw and −Xdebug the JVM may hang Make sure to disable debugging options and remove all -Xrun and -agentpath options except the ones containing the dtdagent library.

• Does the JVM output contain "Can´t load "libdtdagent.a", because load ENOENT on shared library(s)"?

o If the JVM output contains this line the libdtdagent.so file is not found by the JVM. Make sure that you have set the LIBPATH. → see Agent Configuration

Q4: Where can I find the JVM output?

A2: For Application Servers the JVM and Diagnostics Agent output is located in LogFiles → see JBoss , Weblogic , Oracle , Websphere


A3: The Log output can be found in the log folder → the folder is located a level higher as the agent library e.g. dtdagent.dll file is located in the \lib folder, the log output can be found in the \log folder on the same level as the \lib folder.

Q6: How can I find out the Java Version the SUD is using?

A5: First of all you have to find out where the exceuted java binary is located. (e.g. /opt/IBM/WebSphere/AppServer/java/bin)

According to your OS you have to use following commands:

• For Windows OS: type " java -version "on command line • For UNIX OS: type " ./java -version "on command line e.g.

bash-2.03$ ./java -version java version "1.5.0_04" Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_04-b05) Java HotSpot(TM) 64-Bit Server VM (build 1.5.0_04-b05, mixed mode)

Q7: Why does the SUD JVM crash when a memory dump i s performed?

A7: If you use special GC options for the SUD JVM, like -Xincgc , -XX:+UseParallelGC , -XX:+UseConcMarkSweepGC or -XX:+AggressiveHeap , the Java Profiling / Tool Interface (JVMPI or JVMTI) may

crash the SUD VM.

.NET


A8.1: In some cases the necessary environment variables are not set. Please use the Agent Configuration Tool for .NET and check if profiling is enabled by the Injection State.

A8.2: In situations where you are not permitted to set the environment variables system-wide, enable profiling in local files, for example batch scripts, by setting the following environment variables. For example:

@echo off

REM set environment variables necessary for loading Diagnostics Agent

set COR_ENABLE_PROFILING=0x1

set COR_PROFILER={204599FF-741F-4984-9EB6-CC68B6F96 C55}


A9.1: The Log output for the Diagnostics Agent can be set by the Diagnostics Agent Configuration Tool.

A9.2: If the Log output hasn't been set by the Diagnostics Agent Configuration Tool, the output may be found in the log folder → the folder is located a level higher as the agent library e.g. dtdagent.dll file is located in the \lib folder, the log output can be found in the \log folder on the same level as the \lib folder.

DynaTrace Diagnostics User Guide

Documents

Transcript of DynaTrace Diagnostics User Guide