Add LICENSE and README

LICENSE.txt

@@ -0,0 +1,13 @@
+Copyright (c) 2011, Foursquare Labs, Inc.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,74 @@
+# HeapAudit
+
+HeapAudit is a java agent which audits heap allocations for JVM processes.
+
+HeapAudit requires a simple integration hook to be implemented by the java
+process of interest. The callback hook defines how the allocations are recorded
+and the callback code is only executed when the java agent is loaded.
+
+## Building the HeapAudit java agent
+
+Build project with Maven:
+
+	$ mvn clean package
+
+The built jar will be in 'target/'.
+
+## Implementing the HeapAudit hook
+
+Currently, two recorders are provided with HeapAudit:
+	- [HeapActivity](https://github.com/foursquare/heapaudit/blob/master/src/main/java/com/foursquare/heapaudit/HeapActivity.java) prints each heap allocation to stdout
+	- [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
+
+Both of the above inherit from the base class HeapRecorder. Additional recording
+behavior can be extended by implementing [HeapRecorder](https://github.com/foursquare/heapaudit/blob/master/src/main/java/com/foursquare/heapaudit/HeapRecorder.java).
+
+	For instance:
+
+	    class MyRecorder extends HeapRecorder {
+
+	        @Override public void record(String name,
+	                                     int count,
+	                                     long size) {
+
+	            System.out.println("Allocated " + name +
+	                               "[" + count + "] " + size + " bytes");
+
+	        }
+
+	    }
+
+Recording starts when it is registered and stops when it is unregistered. Each
+recorder can be registered globally across all threads or local to the current.
+
+	For instance:
+
+	    MyRecorder r = new MyRecorder();
+
+	    HeapRecorder.register(r, false);
+
+	    MyObject o = new MyObject();
+
+	    HeapRecorder.unregister(r, false);
+
+## Launching the HeapAudit java agent
+
+Launch HeapAudit as a java agent at the java command line.
+
+	$ java -javaagent:heapaudit.jar MyTest
+
+Additional options can be passed to HeapAudit to customize which classes and/or
+methods are not to be instrumented for recording allocations. For additional
+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).
+
+	For instance:
+
+	    $ java -javaagent:heapaudit.jar="-Ccom/foursquare/test/.+" MyTest
+
+## Dependencies
+
+- [ASM](http://asm.ow2.org/)
+
+## Maintainers
+
+- Norbert Y. Hu [email protected]