svn commit: r881593 - /incubator/kato/trunk/org.apache.kato/USING

[mo...@apache.org]

Author: monteith
Date: Tue Nov 17 22:52:01 2009
New Revision: 881593

URL: http://svn.apache.org/viewvc?rev=881593&view=rev
Log:
More USING information.

Modified:
    incubator/kato/trunk/org.apache.kato/USING

Modified: incubator/kato/trunk/org.apache.kato/USING
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/USING?rev=881593&r1=881592&r2=881593&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/USING (original)
+++ incubator/kato/trunk/org.apache.kato/USING Tue Nov 17 22:52:01 2009
@@ -52,7 +52,9 @@
     lib/kato.hprof.reader-${project.version}.jar
 
 
-lib/kato.cjvmti-${project.version}.jar
+The CJVMTI dump format needs the following jar on the classpath:
+    lib/kato.cjvmti-${project.version}.jar
+
 
 
 
@@ -62,7 +64,54 @@
 
 The API, and specification.
 
-Using kato view.
+KatoView
+========
+
+KatoView is a command line tool for analyzing dumps.
+A script is provided in Linux and Windows versions to launch it:
+    bin/katoview.sh
+    bin/katoview.cmd
+
+The scripts can be run like so:
+    katoview [ -verbose ] -dump <dump_file> 
+
+Where "katoview" is suffixed with .sh or .cmd.
+
+The script should be passed a dump file after the -dump parameter.
+KatoView will use any JSR-326 compliant implementation, but currently
+only hprof files and cdmp (CJVMTI agent dumps) will read.
+
+KatoView supports a large number of different commands. Use the help
+command for a list of commands. Further help can be brought up using
+"help" followed by the command name. 
+Commands may have subcommands. For example, the "info" command 
+must be called with sub commands.
+
+For example, the "thread" sub command of "info" command can be invoked
+with the wildcard "*" to list all threads.
+
+> info thread *
+
+
+        native threads for address space # 0
+         process id: <data unavailable>
+
+         no native threads found with specified id
+
+        Java threads not associated with known native threads:
+
+            name:          DestroyJavaVM
+            Thread object: 0x181b
+            JVMTI state:   ALIVE RUNNABLE
+            Thread.State:  RUNNABLE
+            Priority:      5
+            monitor:       <no associated monitor>
+            thread frames: <no frames to print>
+
+
+There are some caveats. Not all of the implementations of the JSR-326 API
+will provide enough information for every katoview command to operate correctly.
+
 
 Using HProf
 =============
@@ -70,3 +119,10 @@
 Using the JDI server
 ====================
 
+The JDI server allows an ordinary Java debugger to attach to a
+dump file as if it were a remote application.
+
+To launch the JDI-Server, run the "jdi-server.sh" on Linux or
+the "jdi-server-cmd" script on Windows.
+
+