Offline Profiling


  JProfiler's offline profiling capability allows you to run profiling sessions from the command line without the need for starting JProfiler's GUI front end. Offline profiling makes sense if you want to
  • perform profiling runs from a scripted environment (e.g. an ant build file)
  • save snapshots on a regular basis for QA work
  • profile server components on remote machines via slow network connections
Performing an offline profiling run for your application is analogous to remote profiling with special library parameters passed to the profiling agent VM parameter -agentpath:[path to jprofilerti library]:
  • offline switch
    Passing offline as a library parameter enables offline profiling. In this case, a connection with JProfiler's GUI is not possible.
  • session ID
    In order for JProfiler to set the correct profiling settings, a corresponding session has to be configured in JProfiler's GUI front end. The ID of that session has to passed as a library parameter: id=nnnn. Your settings in the profiling settings dialog are used for offline profiling. The session ID can be seen in the top right corner of the application settings dialog.
  • config file location (optional)
    The config file that is read for extracting the session with the specified ID has to be passed via config={path to config.xml}. The config file is located in the .jprofiler9 directory in your user home directory (on Windows, the user home directory is typically c:\Documents and Settings\$USER). If you leave out this parameter, JProfiler will try to detect the config file location automatically.

A summary of all library parameters is available in the remote session invocation table.

If you profile on a machine where JProfiler is not installed, you will need to transfer the contents of the bin/{your platform} directory as well as the JAR file bin/agent.jar and the config file {User home directory}/.jprofiler9/config.xml.

Example:

A typical invocation for offline profiling will look like this:

        java "-agentpath:C:\Program Files\jprofiler9\bin\windows\jprofilerti.dll=offline,id=109,config=C:\Users\bob\.jprofiler9\config.xml"
        "-Xbootclasspath/a:C:\Program Files\jprofiler9\bin\agent.jar"
        -classpath myapp.jar com.mycorp.MyApp

Please study the remote session invocation table to generate the correct invocation for your JVM. Also, please don't forget that the platform-specific native library path has to be modified, just like for remote profiling.

  With the command line utility bin/jpenable, you can start offline profiling in any running JVM with a version of 1.6 or higher. With command line arguments you can automate the process so that it requires no user input. The supported arguments are:
  Usage: jpenable [options]

  jpenable starts the profiling agent in a selected local JVM, so you can connect
  to it from a different computer. If the JProfiler GUI is running locally, you
  can attach directly from the JProfiler GUI instead of running this executable.

  * if no argument is given, jpenable attempts to discover local JVMs that
    are not being profiled yet and asks for all required input on the command
    line.
  * with the following arguments you can partially or completely supply all
    user input on the command line:

    -d  --pid=PID      The PID of the JVM that should be profiled
    -n  --noinput      Do not ask for user input under any circumstances

    GUI mode: (default)
    -g  --gui          The JProfiler GUI will be used to attach to the JVM
    -p  --port=nnnnn   The port no which the profiling agent should listen for a
                       connection from the JProfiler GUI

    Offline mode:
    -o  --offline      The JVM will be profiled in offline mode
    -c  --config=PATH  Path to the config file that holds the profiling settings
    -i  --id=ID        ID of the session in the config file. Not required, if
                       the config file holds only a single session.

  Note that the JVM has to be running as the same user as jpenable, otherwise
  JProfiler cannot connect to it.
  An exception are Windows services running under the local system account if you
  list them interactively with jpenable.
If you just need a heap snapshot, consider using the jpdump command line tool that saves an HPROF dump without loading the profiling agent into the VM.
  If the generated snapshots have heap dumps in them, you can use the jpanalyze executable to prepare the heap dump analysis in advance. Opening the snapshot in the JProfiler GUI will then be very fast. The executable is named jpanalyze.exe on Windows and jpanalyze on Unix-based operating systems and is located in the bin directory of a JProfiler installation. If you execute it with the -help option, you will get help on its usage:
  Usage: jpanalyze [options] "snapshot file" ["snapshot file" ...]

  where "snapshot file" is a snapshot file with one of the extensions:
             .jps, .hprof, .hpz, .phd
        [options] is a list of options in the format -option=value

  Options:
      -obfuscator=none|proguard|yguard
          Deobfuscate for the selected obfuscator. Defaults to "none", for other
          values the mappingFile option has to be specified.
      -mappingfile=[file]
          The mapping file for the selected obfuscator.
      -removeunreferenced=true|false
          If unreferenced or weakly referenced objects should be removed.
      -retained=true|false
          Calculate retained sizes (biggest objects). removeunreferenced will be
          set to true.
      -retainsoft=true|false
          If unreferenced objects are removed, specifies if soft references
          should be retained.
      -retainweak=true|false
          If unreferenced objects are removed, specifies if weak references
          should be retained.
      -retainphantom=true|false
          If unreferenced objects are removed, specifies if phantom references
          should be retained.
      -retainfinalizer=true|false
          If unreferenced objects are removed, specifies if finalizer references
          should be retained.
The removeUnreferenced, the retained and all the retain* command line options correspond to the options in the heap walker options dialog.
  If you start your application from an ant build file, you can use the ant task to easily profile your application in offline mode.
  If you already have a launched "Application" session defined, you can generate a start script for offline profiling with the local to offline conversion wizard on the "Convert" tab of the start center or by selecting Session->Conversion Wizards->Convert Application Session To Offline from the main menu.
  To control CPU profiling, triggering of heap dumps and saving of snapshots during an offline profiling session, you can use the
  • Profiling API
    JProfiler's profiling API allows you to control the profiling agent from your own code. An example on how to use the offline profiling API is available in the $JPROFILER_HOME/api/samples/offline directory.
  • Triggers

    With triggers, you can define all profiling actions in the JProfiler GUI.

  • JProfiler MBean

    On Java 1.5+, the profiling agent registers an MBean that gives access to all profiling actions. MBeans are configurable in jconsole:

    Most methods of the com.jprofiler.api.agent.Controller are reflected in the MBean. For documentation of the MBean operations, please see the javadoc of com.jprofiler.api.agent.mbean.RemoteControllerMBean.

    The MBean may also be accessible via configuration facilities of an application server or other tools.

  • Command line controller

    With Java 1.5+, you can use the command line controller tool to interactively record profiling data and save snapshots in a convenient way without having to use a separate MBean viewer.

  If wish to analyze profiling information at run-time, you can use the profiling platform that is part of JProfiler. Please see the javadoc in $JPROFILER_HOME/api/javadoc and the sample in $JPROFILER_HOME/api/samples/platform for more information.