Table of Contents:

1.0 Introduction - Description and Purpose
1.1 Requirements and Install
1.2 Known Limitations and Workarounds
1.3 Configuring Agent Controller
1.3.1 Configuring Remote Agent Controller (RAC)
1.3.2 Configuring Integrated Agent Controller (IAC)
2.0 Instrument Java Application
2.1 Instrumentation Preferences
2.2 Using filters and Byte code type
2.3 Instrument Java Application using ARM
2.3.1 Using ARM with Application Servers
2.3.2 Viewing ARM data
2.4 Instrument Java Application using JMX
2.4.1 Using Managed Agent Explorer with JMX
2.5 Instrument Java Application using CBE
2.5.1 Viewing CBE logs
2.6 Exporting instrumented jars
2.7 Running instrumented application

The Build-to-Manage Toolkit for Java Instrumentation promotes a set of management standards that have been available for Java programmers for some time. This document describes how to use these management standards to help instrument user code for response time measurement, management, and event creation.

• Application Response Measurement (ARM): Created by the Computer Measurement Group and now standardized by The Open Group, ARM measures application availability and performance. It collects response times and application-detected errors, with sampling used to lower data collection overhead. ARM uses correlator passing to track transactions across disparate systems.
• Java Management Extensions (JMX): The standard for management of Java applications, JMX describes the programming interfaces used by applications. It allows Java programs to expose attributes and operations, as well as to send notifications to management systems that conform to the JMX manager-agent architecture.
• Common Base Events (CBE): An IBM initiative that defines a common XML schema for logging and events, CBE allows autonomic systems to evaluate disparate sources of system information before taking action.

BtM is developed based-on TPTP 4.3. BtM supports two byte code instrumentation mechanism: Probekit and AspectJ.

1. Eclipse 3.2.1+
2. TPTP 4.3+
3. Technology Previews Monitoring Instrumentation and ARM
4. AspectJ requires AJDT 1.5

Follow the steps below to obtain a copy of BtM:

1. Click on the 'TPTP all-in-on' link from TPTP's download page: http://www.eclipse.org/tptp/home/downloads/downloads.php
2. Download the Agent Controller for your platform from the TPTP download page.
3. Download the ARM, JMX, and Common Base Event plugis for Eclipse and the agent control from the Build to Manage page: http://www.eclipse.org/tptp/monitoring/resources/download/btm/index.html
4. Install AJDT 1.5 (optional. If you want to use AspectJ weaving technology, you must install AJDT).

Installing BtM

1. Unzip 'TPTP all-in-on' package to the Eclipse installation directory, for example, D:\eclipse.
2. Unzip the Agent Controller to the Agent Controller installation directory, for example, D:\agentcontroller. Read the getting_started.html file included with the Agent Controller download on installation and usage.
3. Unzip the ARM, JMX, and Common Base Event Eclipse plugins into the Eclipse installation directory, for example, D:\eclipse.
4. Unzip the ARM, JMX, and Common Base Event Agent Controller plugins into the Agent Controller installation directory, for example, D:\agentcontroller.

The list below indicates some of the known limitations of the BtM.

• Adding VM arguments to Generic Server are removed after each launch of the server. 162811
• Using MX4J jars for the JMX instrumentation include the following exclude items in the Instrumentation Filter.
  • mx4j*    *    *    exclude
  • *           $*    *    exclude
  Not excluding the following filter items can cause stack overflow error.
• Managed Agent Explorer does not work when invoking operations using the remote agent controller. 161624
• Support needed to handle asynchronous events in model and user interface. 143814
• Excess logging in Tomcat with error message "-9 ARM Error". This issue does not effect profiling in any manner and will be addressed in TPTP 4.4. 166148
• Tomcat profiling fails the first time. This is a known issue and will be resolved in next release. 166062

BtM supports Integrated Agent Controller (IAC) for JMX and CBE instrumentation and Remote Agent Controller (RAC) for ARM, JMX, and CBE's.

1. Click on the 'Latest Downloads' link from TPTP's home page: http://www.eclipse.org/tptp and select the version and the build that you wish to download.
2. Select a convenient download mirror and save the zip file.
3. To install the Agent Controller, unzip the zip file into a directory of your choice (e.g. c:\raserver). For information on setting up and running Agent Controller, see the Agent Controller Getting Started Guide include in the zip.
4. Stop the Agent Controller
5. Unzip the Technology Preview (ARM Engine installed on the RAC) - RAC into the Agent Controllers plugin directory, for example, c:\raserver\plugins.
6. Unzip the Technology Preview (Monitoring Instrumentation for RAC) - RAC into the Agent Controllers plugin directory, for example, c:\raserver\plugins.
7. Run SetConfig script
8. Start the Agent Controller

1. Unzip the Technology Preview (Monitoring Instrumentation for the agent controller) into the Integrated Agent Controller's extensions directory, for example, C:\eclipse\plugins\org.eclipse.hyades.execution_4.2.0.v200606131519\iac-runtime\extensions.
2. Restart the Eclipse workbench.

All java instrumentation takes placing using the Profile menu option and Profiling wizard available within TPTP. BtM Application Response Measurement (ARM) instrumentation places in the ARM start and stop calls for the specified methods selected in the Instrument filter.

BtM Java Management Extension (JMX) instrumentation automatically registers ModelMBeans (with required metadata) for the specified methods and member variables using an after advice (or exit fragment). BtM preferences determine which MBean server is to be used. The user can have JMX notifications sent for failures, successes, JMX attribute changes, and method execution time.

The BtM Common Base Events model formats log events to a specific XML schema. Events are derived from situations that the user selects in the event wizard. BtM�s CBEs indicate the exception thrown and the stack trace of the entry and exit method.

To change the defaults, follow these steps:

1. Select Window > Preferences. The Preferences window opens.
2. From the tree on the left, select Profiling and Logging -> Instrumentation. The Instrumentation preferences pane opens.
3. Use this pane to:
   • To select byte code type
   • Setup CBE logging information and properties
4. Click Apply. Your choices take effect in all currently open profiling windows. Click OK to close the Preferences window.

In the Instrument Collector filters can be added or removed to help the user determine what packages, classes, and/or methods to be include or exclude during instrumentation. Filters can be configured from the Instrument Collector -> Edit Options.

1. Instrument Data Collector, the desired filters for instrument packages, classes or methods can be applied. For the purposes of this example, Select Default filter set.
   
   
   Figure 2.1 - Instrument Collector Filter
   
   
2. Click Add to the right of the list of rules to add a new rule to the filter set. For example, add samle.bookstore in the Package field and * in the Class field and Method name field, select INCLUDE for the Rule, then click OK.
   
   
   Figure 2.2 - Add filter
   
   
3. Click Next you must select the Byte Code Type you want to instrument your applications. Two instrumentation types are available: Probes and AspectJ. To select AspectJ type Byte Code, you must install AJDT 1.4.0; otherwise AspectJ will not be listed as an option.
4. Click Finish

1. To monitor an application using ARM, select File Menu > Run > Profile.... The Profiling wizard opens.
2. In the left pane (Configurations), select Java Application.
3. Click New. A new configuration is created with the default name New_configuration.
4. On the Main tab, browse to the Project and Main class that you want to profile.
5. From the Profile Configuration screen select the Monitor tab -> Application Response Measurement Analysis under the Instrument Collector.
   
   
   Figure 2.3 - Select ARM Analysis Type
   
   
6. Instrument type can be configured from the Application Response Measurement Analysis -> Edit Options. For most application Generic should work just fine, but for J2EE application and Tomcat you may want to use servlet, ejb and jdbc to get more detail information.
   
   
   Figure 2.4 - Select ARM Instrument Types
   
   
7. Press the Profile button at the bottom to run your application with ARM Instrumentation.

The Profiling tool using the Application Response Measurement analysis type provides the ability to attach to a running application or to launch an application for profiling. Attaching to an application means that a monitor is created to contain the results observed by an associated agent. Launching a process means that the process is started with an agent is associated with to process, and a monitor is created to contain the results observed by the agent.

Attaching to a an application server requires either statically applied probes or placing arm calls directly in the application.

• Attaching to an application
1. From the Profiling and Logging Perspective, click on the Profile drop-down menu, and select Profile... The Profile wizard opens.
2. Double click on Attach - Java Process. A new configuration is created.
3. Under the Host tab, specify the Host name or IP address and the Agent Controller port (if different from the default).
4. Select the Instrument Agent.
5. Click Apply to apply the changes.
6. Click Profile to attach to the application.
7. The Profiling Monitor view is refreshed displaying the agent representing your application. The workbench console opens, displaying program input and output.
• Launching an application
1. For Tomcat only move the armModel.jar and armProbes.jar to the Tomcat common library directory, for example C:\Program Files\Apache Software Foundation\Tomcat 5.5\common\lib.
2. From the Profiling and Logging Perspective, click on the Profile drop-down menu, and select Profile... The Profile wizard opens.
3. Double click on Apache Tomcat to profile Tomcat server or Generic Server for all other Application Servers. A new configuration is created.
4. In the Arguments tab, enter any Program arguments and/or VM arguments that you want this configuration to use. Note 1: You must set the Arm Transaction Factory property as a system property in the VM arguments. The Arm Report Factory and Arm Metric Factory are optional.

   -DArm40.ArmTransactionFactory=org.eclipse.tptp.trace.arm.internal.transaction.ArmTransactionFactoryImpl 
   -DArm40.ArmTranReportFactory=org.eclipse.tptp.trace.arm.internal.tranreport.ArmReportFactoryImpl
   -DArm40.ArmMetricFactory=org.eclipse.tptp.trace.arm.internal.metric.ArmMetricFactoryImpl
   					

   Note 2: For WebSphere the Agent Controller library path needs to add to the -Djava.library.path. C:\TPTP_AG\bin
5. In the Classpath tab, add the following jars to the class path form the list of plug-ins.

   Plugin Name	Jars needed
   org.eclipse.tptp.trace.arm	armLibrary.jar cbeLogging.jar
   org.opengroup.arm	arm40_java_interfaces.jar
   org.eclipse.hyades.execution	hexr.jar
   org.eclipse.hyades.logging.core	hl14.jar hlcore.jar
   org.eclipse.tptp.platform.logging.events	t1core.jar hlcbe101.jar
   Under Plugins dir	org.eclipse.emf.common_VERSION_NUMBER.jar Example: org.eclipse.emf.common_2.2.0.v200606221156.jar
   Under Plugins dir	org.eclipse.emf.ecore.xmi_VERSION_NUMBER.jar Example: org.eclipse.emf.ecore.xmi_2.2.0.v200606221156.jar
   Under Plugins dir	org.eclipse.emf.ecore_VERSION_NUMBER.jar Example: org.eclipse.emf.ecore_2.2.0.v200606221156.jar

   Note 3:For WebSphere you need to add the following to the classpath.

   Plugin Name	Jars needed
   org.eclipse.tptp.trace.arm	armModel.jar armProbes.jar

6. Click Apply to apply the changes.
7. Click Profile to attach to the application.
8. After application server has been started the Profile on Server dialog is shown.
9. Select the agents that are associated with the process ID you want to attach to.
10. Select the Monitor tab. Configure the profiling filters as required (2.2 Using filters and Byte code type) and Application Response Measurement analysis (2.2 Instrument Java Application using ARM)
11. Click Finish to connect to the application server.
12. The Profiling Monitor view is refreshed displaying the agent representing your application. The workbench console opens, displaying program input and output.

The Application Response Measurement Analysis type provides a number of different views and tables to help visualize the profiling data.

1. Select Application Response Measurement Analysis in the Profiling Monitor tab and right click to list the available views.
   
   
   Figure 2.5 - ARM views
   
   
2. After select the desired view the ARM data will be displayed

1. To monitor an application using JMX, select File Menu > Run > Profile.... The Profiling wizard opens.
2. In the left pane (Configurations), select Java Application.
3. Click New. A new configuration is created with the default name New_configuration.
4. On the Main tab, browse to the Project and Main class that you want to profile.
5. From the Profile Configuration screen select the Monitor tab -> Java Management Extension Analysis under the Instrument Collector.
6. Press the Profile button at the bottom to run your application with JMX Instrumentation.
7. In the Profiling Console register mbeans names will be displayed.

The Monitoring Instrumentation UI plug-in includes an implementation for JMX against org.eclipse.tptp.monitoring.managedagent.internal.ManagedResourceAgent. We can use the managed agent explorer to view those created and registered MBeans during the above instrumentation.

1. To view the MBeans created, select File Menu > Run > Profile.... The Profiling wizard opens.
2. In the left pane (Configurations), select Managed Resource.
3. Click New. A new configuration is created with the default name New_configuration.
4. Select JMX resource under Monitor tab, and press the Edit Options button to configure JMX Service URL address.
   • The Edit Options allows the user to specify the either to use the Embedded JMX MBean Server or specify a remote server.
   • If you want to retrieve the MBeans which are created and registered by Monitoring Instrumentation plug-in, you have to choose Embedded MBeanServer. If you want to view resources on any other MBeanServer, please choose Remote MBeanServer.
   
   Figure 2.6 - Create Resource Browser
   
   
5. Press the Profile button.
6. Right-click a MBean Server and select Launch agent to launch a new agent to view the details of this selected MBean.
   Figure 2.7 - Select Resource Browser
   
   
7. The Managed Agent Explorer shows the registered mbeans for the selected MBean Server. To retrieve the attributes and operations right-click on an mbean and select Launch agent.
8. The mbean info is broken into either properties (attributes in JMX) or operations.
   • To invoke attributes select the property in the Managed Agent Browser, change the value and push enter.
     Figure 2.8 - Change Property
     
     
   • To invoke operations select the operation in the Managed Agent Browser, fill in the required parameters and push the invoke button.
     Figure 2.9 - Change Property
     
     

1. To monitor an application using CBE, select File Menu > Run > Profile.... The Profiling wizard opens.
2. In the left pane (Configurations), select Java Application.
3. Click New. A new configuration is created with the default name New_configuration.
4. On the Main tab, browse to the Project and Main class that you want to profile.
5. From the Profile Configuration screen select the Monitor tab -> Common Base Event Analysis under the Instrument Collector.
6. Click Edit Option to set CBE Configuration information.
   • CBE Scenario Selection: select Method CBE Instrument or Callsite CBE Instrument scenario.
   • Instrument Type Selection: for Method CBE Instrument, it provides three instrument types: Method Catch - log event while there is an exception, Method Entry - log event while entry a method and Method Exit - log event while exit a method; for Callsite CBE Instrument, it provides two instrument types: Before Call Method - log event before the method is called and After Call Method - log event after the method is called.
   • IV. CBE Output Selection: select output CBE messages to Logging Agent or Console.
   
   
   
   Figure 2.10 - CBE Options
   
   
7. Click Finish
8. Press the Profile button at the bottom to run your application with CBE.

CBE have to output formats Logging Agent or Console. For the Console the CBE message are displayed in the Profiling perspective console. Follow the steps below to view the CBE messages in the Logging Agent.

1. For Selecting output CBE to Logging Agent, A new item CBE Analysis Logging Agent appears in Profiling and Logging view.
2. Right-Click CBE Analysis Logging Agent to Select Open With... >Log View from popup menu.
3. CBE messages will be listed in Log view

1. To export the instrumented jars, select File > Export.... The exporting wizard opens.
2. Click the plus symbol before Java node, and select "JAR file with instrumentation support".

   

3. Select the resources which you want to export, specify where the jar file will be exported, and select instrumentation type(s) you are using.

   

4. Click Finish

In order to run an instrumented application outside Eclipse environment, we need to add some required jars into classpath. The jars are list in the table in section 2.3.1.

If using Probekit, the following arguments need to add to JVM (in one line):

-XrunpiAgent:server=standalone, extensionLibrary=<rac_install_dir>\plugins\org.eclipse.hyades.probekit\lib\ProbeAgentExtension.dll, ext-pk-BCILibraryName=<rac_install_dir>\plugins\org.eclipse.hyades.probekit\lib\BCIEngProbe.dll, ext-pk-probescript=<btm_probescript_file>, filters=<filters_file>

• <rac_install_dir> is the absolute path of the installed Agent Controller, for example, C:\tptpdc
• <btm_probescript_file> is the absolute path of the btm.probescript file for your BtMed application, for example, C:\apptest\META-INF\btm.probescript
• <filters_file> is the absolute path of the file that contains the initial class filter definitions to be used during the profiling session, for example, C:\filters.txt.
  You can simply add the following filtering rule into this file:
  * * * EXCLUDE
  

If using AspectJ, the following argument needs to add to JVM (in one line):

–javaagent:<path_to_aspectjweaver.jar>

• <path_to_aspectjweaver.jar> is the absolute path of the aspectjweaver.jar file, for example, C:\aspectj\lib\aspectjweaver.jar

Copyright © 2006 IBM Corporation and others. All rights reserved. This document and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html
Author: Yun Song Huang, Yue Yu, and Matt Mings