DX Application Performance Management

Author: CA

Document ID:  TEC616757

Last Modified Date:  9/10/2014

• Products
  • CA Application Performance Management
• Releases
  • CA Application Performance Management:Release:CA APM 9.6
• Components
  • INTROSCOPE

Description:This article instructs how to manually instrument your applications with ProbeBuilder. Manual ProbeBuilding is a non-dynamic method of instrumenting your applications.Important Note: introscope supports various methods for instrumenting applications. Using ProbeBuilder is not compatible with these other methods.Also, Use these methods before using ProbeBuilder: JVM AutoProbe and AutoProbe for application servers.Solution:CA APM--Manual ProbeBuildingHow to Manually Instrument Your Applications with ProbeBuilderThis article provides instructions for manually instrumenting your applications with ProbeBuilder. Manual ProbeBuilding is a non-dynamic method of instrumenting your applications.Important! Introscope supports other methods of instrumenting applications. Use these methods before using ProbeBuilder: JVM AutoProbe and AutoProbe for application servers. Do not use ProbeBuilder with other methods of instrumentation.To use manual ProbeBuilding, perform these tasks:

• Review the prerequisites
  
  
• Choose one of the following options:
  
  
  • Use the ProbeBuilder wizard This option provides a GUI dialog for running ProbeBuilder.
    
    
  • Use the command-line ProbeBuilder This option provides a command-line interface for environments without a windowing system.
    
    
• Run instrumented code
  
  
• Switch back to non-instrumented code
  
  
• Configure the ProbeBuilderWizard.lax file

Review the PrerequisitesBefore you begin, ensure that you have performed these tasks:

• Installed the Java Agent.
  
  
• Configured Java Agent and Enterprise Manager connection properties.
  
  
• Configured the Java Agent name.
  
  
• Configured the ProbeBuilder options.

Note: For more information about installing and configuring the Java agent and configuring ProbeBuilder options, see the CA APM Java Implementation Guide.Use the ProbeBuilder WizardIf your computer has a windowing environment, perform these tasks:

• Add probes to bytecode with ProbeBuilder Wizard
  
  
• Update the application startup script

Add Probes to Bytecode with ProbeBuilder WizardUse the ProbeBuilder wizard to add probes to bytecode. When you run ProbeBuilder manually, it instruments classes on disk before the application server is run.Follow these steps:

1. If you have custom PBDs, add them to the <Introscope_Home>/config/custompbd directory of the Enterprise Manager.
   
   Important! This directory is not the same as the <Agent_Home>/wily/hotdeploy directory used by the Java Agent to deploy custom PBDs. If you have custom PBDs in the hotdeploy directory and are now using the ProbeBuilder Wizard, copy the PBDs you want to use from the hotdeploy directory to the Enterprise Manager config/custompbd directory.
   
   
2. Launch the ProbeBuilder Wizard from your <Introscope_Home> directory. On the Welcome screen, click Next.
   
   
3. Enter or browse to your bytecode directory and click Next.
   
   Note: You can also select .jar files or individual .class files.
   
   
4. Click Select Java Bytecode to enter your desired directory and click Next.
   
   
5. Enter the name and location for the new directory for the instrumented code, or click Browse to select a location. The default name is the original directory with the suffix "isc."
   
   Note: If you select a directory that already exists, ProbeBuilder Wizard displays a dialog asking if you want to overwrite the directory. Click Overwrite to overwrite the existing files as necessary, or click Cancel to go back to the previous dialog to select another location.
   
   
6. Click Next if you did not overwrite an existing directory.
   
   
7. In the System Directives window, locate the set of system directives that correspond to your environment. If your application server is not listed, use the Default Java selection, and click Next.
   
   Note: You have a choice of either using system directives files in which most tracer groups are turned on (FULL) or only a subset of tracer groups are turned on (TYPICAL).
   
   
8. If you installed custom directives files in your config/hotdeploy directory, they appear in the Custom Directives window. Check the box next to any custom directives you want to use with this bytecode, then click Add Probes.
   
   Introscope adds Probes to the specified bytecode. This operation might take several minutes.
   
   
9. When the Finished window opens, click Exit or Add Additional Probes to add Probes to another directory.

Update the Application Startup ScriptAfter adding probes to the bytecode, update the application startup script to specify the location of the instrumented code and the Java agent.Follow these steps:

1. Edit the classpath of the application startup script to include locations of the directories containing the instrumented code created with the ProbeBuilder. Make sure this reference precedes the reference to the original code in the classpath.
   
   
2. Edit the classpath in the application startup script to include the path to the <Introscope_Home>/lib/Agent.jar.
   
   For example, edit an existing classpath:
   
   <your_application_path>/classes:/<your_application_path>/lib/app.jar
   
   MainClass
   
   to look like this:
   
   <your-applicationpath>.isc/classes:/<your-applicationpath>.isc/lib/
   
   app.jar:/Introscope_Home/lib/Agent.jar MainClass
   
   
3. Save the changes.
   
   
4. Start your application with the new startup script.
   
   The script is updated.

Use the Command-Line ProbeBuilderIf your computer does not have a windowing environment, perform these tasks:

• Add probes to bytecode with command-line ProbeBuilder
  
  
• Edit the classpath

Add Probes to Bytecode with Command-Line ProbeBuilderYou activate the command-line ProbeBuilder by running a Java command as shown in the following example. Use the ProbeBuilder command-line commands to specify directives, code location, and the instrumented code destination.Note: If you are processing a large .jar file, you can increase the memory in your JVM memory settings. Consult your JVM documentation for instructions.Example: Invoke ProbeBuilder from the Agent directoryjava -cp ext/ProbeBuilder.jar com.wily.introscope.api.IntroscopeProbeBuilder

-directives default.pbl,stream.pbd
-origdir /usr/myApp/classes
-destdir /usr/myApp/classes.isc -verbose

Example: Invoke ProbeBuilder from the Enterprise Manager directoryjava -cp lib/ProbeBuilder.jar com.wily.introscope.api.IntroscopeProbeBuilder

-directives default.pbl,stream.pbd
-origdir /usr/myApp/classes
-destdir /usr/myApp/classes.isc -verbose

Note: This example uses the /wily directory, so paths are relative to the directory. The syntax for the Java command depends on your Java version and other settings in your environment. The ProbeBuilder classpath varies, depending on whether you installed it using an agent installer or the full Introscope installer.Follow these steps:

1. Use the following command to specify directives:
   
   -directives|-pbd filename [...]
   
   Type a comma-separated list of ProbeBuilder Directives files (.pbd), ProbeBuilder list files (.pbl), or directories to scan. At least one PBD or PBL file name is required.
   
   Select either a full or typical .pbl file, depending on how much information you want gathered (see Full or typical tracing options).
   
   If you used the default Java Agent installer, you see all possible default PBD and PBL files in the \wily directory. However, if you used an application-server specific Java Agent installer, you only see PBD and PBL files specific to that application server.
   
   
2. To specify your original code location and your instrumented code destination, select one set of the next three pairs using directories, jar files, or classes.
   
   -origdir directory -destdir directory
   
   Specifies the original directory name (including subdirectories) and the destination directory.
   
   -origjar filename -destjar filename
   
   Specifies the original archive file name, including .jar, .zip, .war, .rar, and .ear archives and the destination archive file name.
   
   -origclass filename -destclass filename
   
   Specifies the original class file name and the destination class file name.
   
   You have the following options:
   
   -skipitems
   
   Skips any files that are not Java bytecode files or archive files (.jar and .zip files). If -skipitems is not set, the non-Java bytecode files are copied to the destination, unchanged.
   
   -help -h -?
   
   Displays a help screen.
   
   -prompt
   
   Turns on an interactive text UI when problems arise.
   
   -verbose
   
   Displays informational messages about each operation that the program performs.
   
   

Edit the Classpath

After adding probes to the bytecode, update the classpath of the application startup script to reflect the locations of the instrumented code and the Java agent.Follow these steps:

1. Edit the classpath of the application startup script to include locations of the directories containing the instrumented code created with the ProbeBuilder. Make sure this reference precedes the reference to the original code in the classpath.
   
   
2. Edit the classpath in the application startup script to include the path to the Agent.jar file.
   
   For example, you might edit a classpath that looks like this:
   
   <your_application_path>/lib/app.jar MainClass
   
   to look like this:
   
   <your-applicationpath>.isc/lib/app.jar:/<ApplicationServer_Home>/wily/Agent.jar MainClass
   
   
3. Save the changes.
   
   
4. Start your application with the new startup script.

The classpath is set.Run Instrumented CodeThere are three ways to run instrumented code instead of your original code:

• In classpaths, replace original class paths with instrumented code paths.
  
  The instructions in this chapter directed you to perform this process when you instrumented your application for the first time.
  
  
• Prepend paths to classpaths.
  
  If only part of the application code was instrumented, you could place the instrumented code paths before the original-code paths (prepend) in the classpath.
  
  If you do this, instrumented code loads and reports performance data. Non-instrumented code still loads and works as expected, but does not report performance data.
  
  
• Place instrumented code in original classpath.
  
  Use this method when classpaths are set in many places:
  
  
  • Move the original code to a new location. Leave the classpaths unchanged. Then move the instrumented code to the original location.
    
    
  • On a UNIX computer, you could also create a symbolic link from the current location of the instrumented code to the original location.
    
    Note: Be careful using this method in a production environment. With this method, it is easy to forget whether you are using the original or the instrumented code.

Switch Back to Non-Instrumented CodeIf you want to switch back to using non-instrumented code, undo the steps of modifying classpaths to run instrumented code.Follow these steps:

1. If you put the paths to your instrumented code into the Java classpaths, then replace paths to the instrumented code in Java classpaths with original paths.
   
   
2. If you added paths to the instrumented code in front of the paths to the original code, remove prepended paths to classpaths.
   
   Remove the prepended portion of the classpath so that only the original classpath remains.
   
   
3. If you put instrumented code in the original classpath, then remove the Instrumented code from the original path and place the original code in the original classpath.

If you used symbolic links on a UNIX system, point the symbolic link to the original directory or remove the link and move the code into the original classpath.Configure the ProbeBuilderWizard.lax FileConfigure the properties in the ProbeBuilderWizard.lax file.Follow these steps:

1. Open the ProbeBuilder Wizard.lax file for editing here:
   
   <Introscope home>/Introscope ProbeBuilder Wizard.lax
   
   
2. Configure the following properties:
   
   lax.nl.current.vm
   
   Specifies the VM to use the next time the ProbeBuilder is started. Can be set to any installed JDK.
   
   lax.stderr.redirect
   
   Specifies the Standard Error Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file.
   
   Default: blank
   
   lax.stdin.redirect
   
   Specifies the Standard Input. Leave blank for no input, console to read from the console window, or any path to a file to read from that file.
   
   Default: blank
   
   lax.stdout.redirect
   
   Specifies the Standard Output. Leave blank for no output, console to send to a console window, or any path to a file to save to the file.
   
   Default: blank
   
   
3. Save the changes.
   
   The configuration is set.

Search the Entire CA APM Knowledge Base