Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 82 lines (48 sloc) 2.906 kB
89c1f94 Add LICENSE and README
Norbert Hu authored
1 # HeapAudit
2
3 HeapAudit is a java agent which audits heap allocations for JVM processes.
4
36e1443 Implement support for dynamically injecting HeapAudit to JVM processes
Norbert Hu authored
5 HeapAudit runs in two modes:
6
7 - STATIC: This requires a simple integration hook to be implemented by the java
89c1f94 Add LICENSE and README
Norbert Hu authored
8 process of interest. The callback hook defines how the allocations are recorded
9 and the callback code is only executed when the java agent is loaded.
36e1443 Implement support for dynamically injecting HeapAudit to JVM processes
Norbert Hu authored
10 - DYNAMIC: This injects HeapQuantile recorders to all matching methods and dumps
11 heap allocations to stdout when removed.
89c1f94 Add LICENSE and README
Norbert Hu authored
12
13 ## Building the HeapAudit java agent
14
15 Build project with Maven:
16
17 $ mvn clean package
18
19 The built jar will be in 'target/'.
20
21 ## Implementing the HeapAudit hook
22
23 Currently, two recorders are provided with HeapAudit:
24
6433caa Update README.md
Norbert Hu authored
25 - [HeapActivity](https://github.com/foursquare/heapaudit/blob/master/src/main/java/com/foursquare/heapaudit/HeapActivity.java) prints each heap allocation to stdout
26 - [HeapQuantile](https://github.com/foursquare/heapaudit/blob/master/src/main/java/com/foursquare/heapaudit/HeapQuantile.java) accumulates allocations and dumps out summary at the end
89c1f94 Add LICENSE and README
Norbert Hu authored
27
6433caa Update README.md
Norbert Hu authored
28 Both of the above inherit from the base class HeapRecorder. Additional recording
29 behavior can be extended by implementing the record method in [HeapRecorder](https://github.com/foursquare/heapaudit/blob/master/src/main/java/com/foursquare/heapaudit/HeapRecorder.java).
89c1f94 Add LICENSE and README
Norbert Hu authored
30
6433caa Update README.md
Norbert Hu authored
31 class MyRecorder extends HeapRecorder {
89c1f94 Add LICENSE and README
Norbert Hu authored
32
6433caa Update README.md
Norbert Hu authored
33 @Override public void record(String name,
34 int count,
35 long size) {
89c1f94 Add LICENSE and README
Norbert Hu authored
36
6433caa Update README.md
Norbert Hu authored
37 System.out.println("Allocated " + name +
38 "[" + count + "] " + size + " bytes");
89c1f94 Add LICENSE and README
Norbert Hu authored
39
40 }
41
6433caa Update README.md
Norbert Hu authored
42 }
43
89c1f94 Add LICENSE and README
Norbert Hu authored
44 Recording starts when it is registered and stops when it is unregistered. Each
45 recorder can be registered globally across all threads or local to the current.
46
6433caa Update README.md
Norbert Hu authored
47 MyRecorder r = new MyRecorder();
89c1f94 Add LICENSE and README
Norbert Hu authored
48
6433caa Update README.md
Norbert Hu authored
49 HeapRecorder.register(r, false);
89c1f94 Add LICENSE and README
Norbert Hu authored
50
6433caa Update README.md
Norbert Hu authored
51 MyObject o = new MyObject();
89c1f94 Add LICENSE and README
Norbert Hu authored
52
6433caa Update README.md
Norbert Hu authored
53 HeapRecorder.unregister(r, false);
89c1f94 Add LICENSE and README
Norbert Hu authored
54
55 ## Launching the HeapAudit java agent
56
36e1443 Implement support for dynamically injecting HeapAudit to JVM processes
Norbert Hu authored
57 Launch HeapAudit statically along with the process of interest (requires MyTest
58 to implement the integration hook to register heap recorders).
89c1f94 Add LICENSE and README
Norbert Hu authored
59
60 $ java -javaagent:heapaudit.jar MyTest
61
36e1443 Implement support for dynamically injecting HeapAudit to JVM processes
Norbert Hu authored
62 Launch HeapAudit dynamically by attaching to the process of interest (does not
63 require MyTest to have any prior intrumentations).
64
65 $ java -jar heapaudit.jar 999 +Rcom/foursquare/test/MyTest.+
66
67 $ java -jar heapaudit.jar 999 -Rcom/foursquare/test/MyTest.+
68
89c1f94 Add LICENSE and README
Norbert Hu authored
69 Additional options can be passed to HeapAudit to customize which classes and/or
70 methods are not to be instrumented for recording allocations. For additional
71 information on how to specify the options, see [HeapSettings.java](https://github.com/foursquare/heapaudit/blob/master/src/main/java/com/foursquare/heapaudit/HeapSettings.java).
72
6433caa Update README.md
Norbert Hu authored
73 $ java -javaagent:heapaudit.jar="-Ccom/foursquare/test/.+" MyTest
89c1f94 Add LICENSE and README
Norbert Hu authored
74
75 ## Dependencies
76
77 - [ASM](http://asm.ow2.org/)
78
79 ## Maintainers
80
81 - Norbert Y. Hu norberthu@foursquare.com
Something went wrong with that request. Please try again.