From kato-commits-return-793-apmail-incubator-kato-commits-archive=incubator.apache.org@incubator.apache.org Thu Nov 19 15:26:09 2009 Return-Path: Delivered-To: apmail-incubator-kato-commits-archive@minotaur.apache.org Received: (qmail 4090 invoked from network); 19 Nov 2009 15:26:09 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.3) by minotaur.apache.org with SMTP; 19 Nov 2009 15:26:09 -0000 Received: (qmail 33290 invoked by uid 500); 19 Nov 2009 15:26:09 -0000 Delivered-To: apmail-incubator-kato-commits-archive@incubator.apache.org Received: (qmail 33269 invoked by uid 500); 19 Nov 2009 15:26:09 -0000 Mailing-List: contact kato-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: kato-dev@incubator.apache.org Delivered-To: mailing list kato-commits@incubator.apache.org Received: (qmail 33259 invoked by uid 99); 19 Nov 2009 15:26:09 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 19 Nov 2009 15:26:09 +0000 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.4] (HELO eris.apache.org) (140.211.11.4) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 19 Nov 2009 15:25:59 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id F3FFC23888FD; Thu, 19 Nov 2009 15:25:37 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r882174 - /incubator/kato/trunk/org.apache.kato/USING Date: Thu, 19 Nov 2009 15:25:37 -0000 To: kato-commits@incubator.apache.org From: monteith@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20091119152537.F3FFC23888FD@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org 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