Frequently Asked Questions

What is Plumbr?
Plumbr is a memory leak detection tool. It monitors your Java application, detects if it leaks memory and reports its findings to you with precise instructions on where the leaking occurs. With that, the time it takes to solve the leak effectively decreases from days or weeks to one hour.

Plumbr is often used as a safeguard against harm done by memory leaks. It notices the leak well before end users are affected, and gives you enough information to solve the leak and update the production systems in time.
How does Plumbr work?
The Plumbr agent monitors your application's objects' life: where and when they are created and when they are deleted by garbage collector. If Plumbr notices objects that are consistently created but never deleted, it adds them to a "watch list" suspected for memory leak. Over time the suspicion either grows or is dropped.

When the probability for a leak reaches an internal threshold, Plumbr declares a found memory leak and starts root cause analysis. After that, it tells you how to fix the leak (i.e. where the leak originates, which classes leak etc).
What is a memory leak?
Memory leak is a waste. If your application has created some Java objects during its work, but then forgot to discard them, they are left behind and consume your application memory. With time, they are accumulated and your application thrashes or crashes as a result of free memory shortage.

The main problem (and challenge!) with memory leaks comes from the fact that "application forgot to discard them" is entirely specific to the application in question. That is why Plumbr was created - to offer a general tool that would be able to find leaks in all Java applications!
What is a Permanent Generation leak?
JVM uses a separate region of memory, called Permanent Generation, for holding its metadata, mostly definitions of java classes used. When memory leak occurs and leaking objects reside in Permanent Generation, this is called a Permanent Generation leak. Plumbr also detects these types of leaks automatically.
What is a ClassLoader?
ClassLoader is a special object used by JVM in order to find and load classes required by your application. Consult the Javadoc for java.lang.ClassLoader for more information.
How do I install Plumbr?
Just download and unzip the latest version of Plumbr, then attach it to your Java application. Can't get any easier :)
What do I have to change in my application for Plumbr to work?
Nothing.

No, really. You have to change nothing in your application/source code/deployment plan in order to get advantage from using Plumbr. Our agent will work transparently with your application, monitoring memory usage and vigilantly spotting the culprit: memory leak. To attach the agents you only need to augment your server start script - for how to do it, see the attachment instructions.
How can I use Plumbr when I run my application within Eclipse?
If you run your application from within Eclipse, then do not add the "-javaagent:plumbr.jar" option into your Eclipse startup script or the eclipse.ini file. That would only attach Plumbr to your Eclipse IDE, not your actual application that you want to monitor for leaks.

Instead, select the menu “Run”, then “Run Configurations...”

Next, select your application and click on the “Arguments” tab:

The “VM arguments” field is the correct place to add the Plumbr’s -javaagent parameter.
Which JVM vendors/application containers/frameworks does Plumbr support?
Plumbr does not depend on any framework or application container per se. It works with plain java applications, Swing applications or multi-node multi-tier clustered Java EE conglomerate-applications.

JDK-wise, Plumbr is tested and known to work with JDK 5, 6 and 7 on Linux, Mac and Windows. It is also tested with different application servers - for a complete list of them and any other environment constraints refer to the support matrix.
How do I know that Plumbr is working?
When you start your application with Plumbr agents you should see the following banner in your standard output: ************************************************** * * * Plumbr (release-version) is started. * * * **************************************************

With this message Plumbr starts monitoring your application's memory usage. It doesn't display any additional info until it finds a memory leak. If you want to double-check, you can query Plumbr status via the JMX interface. Check the value of the Status attribute of the eu.plumbr.agent.jmx.PlumbrOnlineStatus MBean. If it is set to PLUMBR_STATUS_RUNNING, it means that everything is well, and Plumbr is monitoring your JVM.

If you follow the suggestions in this blog post, and still don't get any sign from Plumbr in the logs, then most probably your application doesn't have any memory leaks :) In that case, just leave Plumbr attached to be safe also in the future.
What happens when Plumbr finds a memory leak?
If Plumbr finds a memory leak in your application, it prints the following banner in your standard output and starts the root cause analysis. ***************************************************** * Plumbr found a leak! * * Starting further analysis to find the root cause. * *****************************************************

In the end, the following is printed: ************************************************************************* * Plumbr has finished leak analysis. Please find your report here: * * /path/to/report/plumbr.html * *************************************************************************

To find out the details of the memory leak, just open the report in the location specified in the log message.
Does Plumbr make my application slower?
Since Plumbr collects statistics of your application's memory dynamics and does some complex computations on it, it naturally affects the performance of your JVM/application. The question is rather - how much overhead does Plumbr create and is it worth the result?

We have measured different overhead levels, anywhere from 1-10%, and are constantly working on getting this smaller and more predictable. If, however, you encounter larger CPU or memory overhead while using Plumbr, please let us know and we will figure out what has gone wrong!
How can I send my memory usage statistics info to you?
Plumbr does most of the work for you. It analyzes your application's memory contents after each JVM garbage collection cycle and saves the statistics to your hard drive. You can browse the data in the folder where you stored plumbr.jar - just open the subfolder "plumbr". It contains memory stats for every JVM process run with the Plumbr agent.

Starting from version 1.03RC3, if your JVM has access to the Internet, Plumbr also sends the anonymous statistics to our stats server automatically. The collected data gives a statistical overview of your application's heap memory usage, and does not contain any business sensitive info.

If your JVM does not have access to the net, please send us the stats manually. Just follow these steps:
1) navigate to the folder where you stored plumbr.jar
2) zip the contents of the "plumbr" subfolder. If the folder doesn't exist or doesn't contain anything, make sure that the opsys user running your application server has rights to write to the "plumbr" subfolder.
3) upload the zip file on the statistics upload page.

Thanks a lot for contributing to Plumbr development!
How can I turn off automatic sending of memory statistics?
In order to switch anonymous usage data upload to our server off, create a new text file with a name plumbr.properties alongside plumbr.jar. Write just one line in the text file: reportUsage=false ...and that is it. From the next JVM restart on, Plumbr will not automatically send us the statistics any more.
I am running Plumbr but still get java.lang.OutOfMemoryError. What did I do wrong?
Plumbr will not automagically SOLVE the OutOfMemoryError for you. Yet :) But it gives you all the information needed for you or your developer to open the exact source code file and fix the root cause of the memory leak.
My application crashed with an OutOfMemoryError, but Plumbr said that it found the leak and started the analysis. Where's the report?
When an OutOfMemoryError is thrown and Plumbr analysis hasn't yet finished, you may restart the analysis in offline mode. Note, that the report generated in offline lacks memory usage information as well as field names in the drill down, still it may contain enough information for you to fix the leak.

To launch the offline analysis search standard output of your application for Plumbr banner that was written right before application crashed. It should contain the following line * Dump file is located here: /path/to/dump/pid_plumbr.ref

Remember or copy the mentioned file location. Then go to the folder where you unpacked Plumbr and run the following command: $java -jar plumbr.jar analyze <dump location from log file>

When Plumbr finishes its analysis it informs you of the location of the report with another banner.

PS. If you have a test case with a memory leak, make sure to donate us your memory usage statistics! This will help us to create an even better product!
Do I need the plumbr.lic file and where should I keep it?
The file plumbr.lic contains your personal Plumbr license. You can update Plumbr software independently of the license, i.e. until the license file is valid you can download a new Plumbr version and run it. The download package includes a license that allows you use Plumbr for 365 days.

The plumbr.lic file should be kept in the same folder where your plumbr.jar is. If Plumbr doesn't find a valid license file, it refuses to start.
How can I turn off sending leak reports to my email?
All leak reports that Plumbr generates are by default sent to the email which you provided when you downloaded Plumbr. To switch this off, create a new file called plumbr.properties alongside plumbr.jar or update existing one. Add the following line to this file: emailReport=false

From the next JVM restart on, Plumbr will not automatically send you emails with the reports.
How can I generate Plumbr debug log to help you troubleshoot my problem?
Go to your PLUMBR_HOME (the folder, where your plumbr.jar resides). Create a text file named plumbr.properties there (or just edit the file if it exists already). In that file, add the following two lines: logLevel=DEBUG logFile=plumbr.log
The log file will be created in the PLUMBR_HOME/reports subfolder
My Swing application hangs with Plumbr. How can I fix that?
In some cases Plumbr's own GUI capabilities may interfere with your Swing/AWT application. You can switch them off completely by adding useGui=false to PLUMBR_HOME/plumbr.properties file.