In this post I'd like to introduce my new Java library called named-frames. The library allows including runtime-generated information into JVM/Java stack traces and thread dumps

Motivation

Time from time I look into feedback emails and application logs. Some of such logs contain exceptions and thread dumps. It is always nice to know the build number of the product from which those dumps were captured. The truth is that the build number or the product version is usually not included in the dump.

I had a dream to include the build number of the application and some other meaningful data strait into execution call stack. So that every problem report contains those details, no matter how the report was generated.

In addition to the build number you may include much more information in the call stack. For example, current task names or any other data that is meaningful for faster debugging.

The Library Usage

The application should wrap it's code into the call to the library in the following way:

The captured stacktrace is the following:

The most exciting part of the call stack is the line with dynamically generated string inside:

In the same way you may include as much named stack frames as needed by wrapping each into a call to the NamedStackFrame#frame() method.

Implementation details

The library is implemented in pure Java 1.5, with Maven as a project model. I intentionally avoided any runtime dependencies in the library to avoid dependencies hell in usages.

The named method is added via dynamic code generation. I use the compiled class byte-code as the template for the code-generation. For each given unique stack frame name the library generates and loads a class into an internal classloader. The generated class is reused for all future calls for the same stack frame name.

It is important to notice, that each generated class consumes space in the PermGen of the JVM. (This is changed in Java 1.8). I recommend to check if the full possible set of the used names in your program is limited and will not lead to PermGen OOMs. Unused loaded classes can be garbage-collected by the JVM (depending on the provided JVM options)

Sources & Binaries

The library code is available under the MIT license

The library is available on GitHub: https://github.com/jonnyzzz/named-java-frames.

I published the snapshot build of the library into a maven repository. In a several weeks I plan to apply for the Maven Central publishing

comments powered by Disqus