incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r882174 - /incubator/kato/trunk/org.apache.kato/USING
Date Thu, 19 Nov 2009 15:25:37 GMT
Author: monteith
Date: Thu Nov 19 15:25:37 2009
New Revision: 882174

URL: http://svn.apache.org/viewvc?rev=882174&view=rev
Log:
Doc changes

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=882174&r1=882173&r2=882174&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/USING (original)
+++ incubator/kato/trunk/org.apache.kato/USING Thu Nov 19 15:25:37 2009
@@ -2,7 +2,83 @@
 ==============================
 
 This file explains how to use the various subprojects that constitute
-Apache Kato. 
+Apache Kato.
+
+Overview
+========
+
+Apache Kato supplies the following:
+
+    . A JVMTI agent for enabling Java Virtual Machines to produce rich
+      dumps (CJVMTI)
+    . A JNI library and Java API for causing hprof or CJVMTI dumps to be generated
+      programmatically.
+    . an API that allows Java programs to read dumps from JVMs.
+    . Documentation for the API (JavaDoc + spec).
+    . An implementation of the API that reads hprof dumps.
+    . An implementation of the API that read CJVMTI dumps.
+    . KatoView - A command line tool for analyzing dumps.
+    . JDI Server - A tool for allowing existing Java debuggers
+        to attach to dumps.
+
+These would be used like so:
+
+    1. Configure JVM with CJVMTI/hprof agent.
+    2. Run program.
+    3. Generate dump.
+    4. Run tool that uses API to analyze dump.
+
+CJVMTI
+======
+
+The CJVMTI agent allows the JVM to produce dumps that contain more information
+about the state of the JVM than hprof. 
+
+To start the JVM with the agent, pass the following option to the "java" command,
+or equivalent:
+
+    -agentpath:lib/cjvmti-linux-x86-${project.version}=s,r
+    -agentlib:cjvmti-linux-x86-${project.version}=s,r
+
+Where "s" is the number of stack frames that should be stored. Only those frames
+will be scanned for heap roots.
+"r" is the depth into the object graph the agent will store references from.
+"0" should be passed as "s" or "r" if they should be are unlimited, which is the default.
+
+For example:
+
+    -agentlib:cjvmti-windows-x86-${project.version}=3,4
+
+Will, on Windows, store the top three stack frames and will scan all objects up to
+4 references deep from those stack frames.
+
+With a stack trace like so:
+    Object.wait(long, int)
+    ReferenceQueue.wait(long)
+    ReferenceQueue.remove(long)
+    ReferenceQueue.remove()
+    Disposer.run()
+    Thread.run()
+
+Only the following stack traces would appear:
+    Object.wait(long, int)
+    ReferenceQueue.wait(long)
+    ReferenceQueue.remove(long)
+
+If there was a linked list in ReferenceQueue:
+    ALinkedList list;
+
+As the agent will only (in this case) scan objects 4 deep into the object graph,
+only the 3rd object into the list would be incorporated into the dump.
+
+e.g. ReferenceQueue -> ALinkedList -> Node -> Node -> Node 
+
+Limitations
+-----------
+
+. if local variable information is not available (JIT frames, no local variable info in class),
+  the variables won't appear in the debugger. Heap objects may be missing as a result.
+. 
 
 The API
 =======
@@ -55,15 +131,6 @@
 The CJVMTI dump format needs the following jar on the classpath:
     lib/kato.cjvmti-${project.version}.jar
 
-
-
-
-Installing agent libraries.
-Generating dumps.
-    VM api, ctrl + break.
-
-The API, and specification.
-
 KatoView
 ========
 
@@ -113,9 +180,6 @@
 will provide enough information for every katoview command to operate correctly.
 
 
-Using HProf
-=============
-
 Using the JDI server
 ====================
 
@@ -123,6 +187,36 @@
 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.
+the "jdi-server.cmd" script on Windows, passing the name
+of a dump as the first parameter.
+
+The command usage is:
+
+     JDI Command Line Post-Mortem Debugger
+    ------------------------------------------
+    -v           Increase verbosity (for each instance)
+    -q           Decrease verbosity (for each instance)
+    -t           Set cache time
+    -a           Terminate server after last client disconnects
+    -p           TCPIP port number.
+    --nohash     Do not MD5 hash core. (!USE WITH CAUTION!)*
+    --nofile     File cache is no loaded or saved, caches still happen*
+    --delaywrite Resave cache file only on shutdown*
+    --nocache    Disable cache
+    Last argument is path to dump file
+    Default TCPIP port is 8000.
+    * May improve speed over a network
+
+After running the command like so:
+    jdi-server.sh cjvmtiV0.cdmp
+
+a debugger can be pointed at the machine, like so:
+
+    jdb -attach localhost
+
+if the "-p" parameter is being used to set the port (say, to 8372),
+the following can be done:
+
+    jdb -attach localhost:8732
 
 



Mime
View raw message