StackProbe - a low overhead Java profiler

Tutorial

  1. Installation
  2. Profiling local applications
  3. Profiling remote applications by HTTP
  4. Profiling remote applications by JMX
  5. Using filters
  6. Comparing profiles
  7. Merging profiles from different sessions

  1. Installation

    Good news: StackProbe doesn't need installation. The only thing you need is to get the latest JDK from Sun and to click the red "Run now!" icon in the upper right corner of this page. The application will be automatically downloaded and started up by the JNLP service. This has additional benefit that you always use the newest stable StackProbe version available and you don't need to bother installing upgrades.

    However, if you wish to work offline, you can download a standalone executable JAR archive from the download section and start it by simply double clicking. For this to work, your operating system must be configured to open jar files with Java, and not to unpack them. Or if you prefer using command line, you can use simply:

    java -jar stackprobe.jar

    When first started, StackProbe runs in demo mode until you install a valid license key. In the demo mode, you are allowed to profile only StackProbe itself and you cannot attach it to other local or remote Java applications. To get rid of this limitation, obtain a free trial or purchase a commercial license, and then click "Install license key" button to input the license data you have received:

    Install license key dialog

  2. Profiling local applications

    After launching, a connection dialog box listing running Java applications appears:

    Connect dialog

    The order in which you start StackProbe and the application to be profiled doesn't matter. The list of applications is refreshed automatically whenever you start or exit a Java application.

    Select an application to profile and click the Connect button. After a few seconds, the flat profile of methods and threads appears. The table displays 4 columns together with graphical representation:

    • Total - total time spent in a method
    • Runnable - time a method spent executing code (green)
    • Waiting - time a method spent waiting or sleeping (yellow)
    • Blocked - time a method spent waiting for entering a synchronized block (red)

    All values are expressed as relative time, in [%]. For example, if one thread is constantly executing inside a method (or in any of its callees), it yields 100% total activity of that method. Times spent in the same method by more than one thread add up, so values greater than 100% are possible, e.g. 2 threads waiting forever on an Object.wait call give it 200% activity.

    When you select a method, the call trees appear in the right pane, so that you can observe which other methods call the selected method and which methods are called by the selected method. You can also check, how much time each thread spends executing the selected method.

  3. Profiling remote applications by HTTP

    You can attach StackProbe to any remote application without changing the configuration of the remote application. Download the stackprobe-agent.jar from our site and save it on the computer that runs the remote application. Then run the jps command to get the process ID of the application you want to profile:

    user@localhost$ jps
    5976 Jps
    6100 your-app.jar

    To enable remote profiling of the application "your-app.jar" on port 8000, you should write:

    user@localhost$ java -jar stackprobe-agent.jar 6100 8000
    StackProbe agent loaded successfully. Listening at port: 8000

    From now on, you can connect the StackProbe profiler to your application by using the "Remote connection" tab.

  4. Profiling remote applications by JMX

    Before you can remotely profile your application, you must tell it to listen for remote JMX connections from StackProbe on some HTTP port. This is done by setting these system properties when starting the JVM:

    -Dcom.sun.management.jmxremote
    -Dcom.sun.management.jmxremote.port=8004
    -Dcom.sun.management.jmxremote.authenticate=false
    -Dcom.sun.management.jmxremote.ssl=false

    You can choose any free port number instead of the 8004 used in the example.

    Next, in the connect dialog specify the hostname (or IP address) and the port number where the remote application listens , click the Connect button and proceed in the same way as with local connection.

    If you wish, you can secure the connection to the remote application with username and password. To do this, on the remote computer:

    1. Copy the password template file, jmxremote.password.template, to your home directory.
    2. Set file permissions so that only you can read and write the password file.
    3. Add passwords for the roles such as monitorRole and controlRole (or just uncomment 2 lines in that file - some default passwords are already there).
    4. Additionally to the previous properties, set these system properties when you start the JVM:

      -Dcom.sun.management.jmxremote.authenticate=true
      -Dcom.sun.management.jmxremote.password.file=pwFilePath

      where pwFilePath is the path to the password file.
    5. Give the role (user name) and password in the Connect dialog of StackProbe.

  5. Using filters

    The filters are accessible through the configuration dialog box. You can set thread and method filters. The filters decide, whether a thread or method should be profiled. There are two types of filters: rejecting and accepting. The list of filters is searched from the top to the bottom and the first matching filter applies. If none of the filter matches, then the thread/method is profiled. Matching is done using Java regular expressions. Threads are filtered on their names and methods are filtered on their fully qualified names (package name, class name and method name).

    Examples:

    • Thread-[0-9]+ matches "Thread-1", "Thread-2", and so on.
    • net\.sf\..* matches any method from the package "net.sf".
    • net.sf.* matches also any method from the package "net.sf", and probably some more (but who cares, if it's shorter).
    • Object matches any method of the class "Object", regardless of the package it belongs to.

  6. Comparing profiles

    StackProbe enables you to compare current profile to any previously saved profile or two previously saved profiles with each other. Click the Compare profile icon on the toolbar and select the previously saved profile that you want to be a reference profile. The currently visible profile will be compared to the reference profile. Every value will get additional icon showing if it is lower, greater or equal to the value taken from the reference profile. Additionally, when you select a thread or method, the comparison details are shown in the Profile comparison section. The current values, reference values, absolute and relative differences are shown.

    Note: Sometimes StackProbe displays that two values are equal, though the profile comparison table shows non-zero difference. This means that the difference is too small or there has been too few samples gathered, to consider this difference statistically significant and you should not reason that these two profiles are different.

  7. Merging profiles from different sessions

    1. Connect StackProbe to your application and let it gather some samples.
    2. Save the profile and exit.
    3. Connect StackProbe again.
    4. Load the previously saved profile - current profile is overwritten.
    5. Let StackProbe gather more samples.
    6. Save the profile and exit.
    7. Go to 3. if needed.