JVM development tools for finding memory and garbage problems.
It can be used as a library - as part of custom regression and performance testing frameworks - or as an sbt plugin to get a report on a
main class (or scala
Lion's Share produces HTML reports with interactive Google Charts, e.g. shapeless'
This project is twinned with Shelmet for heap analysis.
To use the plugin, add the following to your project's
addSbtPlugin("com.github.fommil.lion" % "sbt" % "1.0.0")
Then you may run
sbt lion to get a report using the default settings on your project's
The full list of settings is best read from the source code of the plugin.
The following are some example settings that can be defined in
build.sbt to customise the setup:
lionRuns := 50 // number of times to run the main class (without instrumentation) lionClass := Some("path.to.MyMain") // override mainclass just for lions-share lionOut := new File("my-results") // output directory for lions-share reports and log files lionAllocRuns := 0 // runs with the allocation agent (slow) lionAllocTrim := None // no trimming, or trim to this many top-allocated objects lionAllocRate := 30 // number of seconds to wait between polling the allocation agent. lionAllocTrace := Map.empty[String, Long] // classes and byte sample threshold
There are some examples under the examples module, including:
- demonstration of
Somecreation churn and performance impact prompting SI-8519
staging.scalaexample which does runtime invocation of
To use the Garbage Collection analyser as part of your own testing or analysis framework, you must start your applications with these flags:
-Xloggc:gc.log -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintTenuringDistribution -XX:+PrintHeapAtGC
GcAnalyser classes are then at your disposal, producing a
DataTable case class that can be marshalled (using Spray JSON) to the exact form required by Google Charts
DataTable class. See
GcReporter and the companion
report.html for an example.
To use the allocation agent, you must obtain
agent-assembly.jar and start your application with
-javaagent:agent-assembly.jar=OUTFILE PERIOD TRACES
OUTFILEis the file to write the samples
PERIODis the number of seconds between snapshotting the sampler
TRACESis a comma separated list of
Please check the issue tracker to see if we are already aware of an issue (including a workaround). The biggest issues are;
- Only specific JVMs are supported by the garbage collection log parser, and G1 is not supported at all.
You might need to run your application under a supported JVM, e.g.:
JAVA_HOME=/opt/jdk1.7.0_51 sbt lion
and if you need really robust garbage collection log parsing, try the commercial product Censum by jClarity.
- CPU (instrumentation) sampling
- Scala REPL support (e.g. allocation sizes for a block)
- non-instrumentation timeseries instance counts