README.md

The Allocation Instrumenter is a Java agent written using the java.lang.instrument API and ASM. Each allocation in your Java program is instrumented; a user-defined callback is invoked on each allocation.

How to get it

The latest release is available from Maven Central as:

<dependency>
  <groupId>com.google.code.java-allocation-instrumenter</groupId>
  <artifactId>java-allocation-instrumenter</artifactId>
  <version>3.3.4</version>
</dependency>

Basic usage

In order to write your own allocation tracking code, you have to implement the Sampler interface and pass an instance of that to AllocationRecorder.addSampler():

AllocationRecorder.addSampler(new Sampler() {
  public void sampleAllocation(int count, String desc, Object newObj, long size) {
    System.out.println("I just allocated the object " + newObj +
      " of type " + desc + " whose size is " + size);
    if (count != -1) { System.out.println("It's an array of size " + count); }
  }
});

You can also use the allocation instrumenter to instrument constructors of particular classes. You do this by instantiating a ConstructorCallback and passing it to ConstructorInstrumenter.instrumentClass():

try {
  ConstructorInstrumenter.instrumentClass(
      Thread.class, new ConstructorCallback<Thread>() {
        @Override public void sample(Thread t) {
          System.out.println("Instantiating a thread");
        }
      });
} catch (UnmodifiableClassException e) {
  System.out.println("Class cannot be modified");
}

For more information on how to get or use the allocation instrumenter, see Getting Started.