incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From monte...@apache.org
Subject svn commit: r805718 - /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
Date Wed, 19 Aug 2009 09:57:19 GMT
Author: monteith
Date: Wed Aug 19 09:57:19 2009
New Revision: 805718

URL: http://svn.apache.org/viewvc?rev=805718&view=rev
Log:
Add example of how to identify a dump.

Modified:
    incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml?rev=805718&r1=805717&r2=805718&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/examples.xml Wed Aug
19 09:57:19 2009
@@ -230,4 +230,240 @@
 	
 	</para>
 	</sect2>
-</sect1>
\ No newline at end of file
+	
+	
+	<sect2 xml:id="api.examples.what">
+	<title>Identifying Java VM</title>
+	<para>
+	This example demonstrates how the JVM that generated a snapshot might be identifyed. The
following information
+	is reported using the image and java APIs:
+	<itemizedlist>
+	<listitem><para>hostname of the machine the snapshot was generated on.</para></listitem>
+	<listitem><para>The process ID.</para></listitem>
+	<listitem><para>The command line.</para></listitem>
+	<listitem><para>The executable that was running the Java program (e.g. "/usr/bin/java").</para></listitem>
+	<listitem><para>The command line.</para></listitem>
+	<listitem><para>The loaded native libraries.</para></listitem>
+	<listitem><para>The version reported by the JVM.</para></listitem>
+	<listitem><para>The options passed to the JVM.</para></listitem>

+	</itemizedlist>
+	</para>
+	<para>
+	First, we have the class declaration, and imports. Note the use of both API's.
+<example xml:id="api.examples.what.declaration">
+<title>Declaration of WhatAnalyzer class</title>
+<programlisting>
+<![CDATA[
+package org.apache.kato.examples;
+
+import javax.tools.diagnostics.image.CorruptDataException;
+import javax.tools.diagnostics.image.DataUnavailable;
+import javax.tools.diagnostics.image.Image;
+import javax.tools.diagnostics.image.ImageAddressSpace;
+import javax.tools.diagnostics.image.ImageModule;
+import javax.tools.diagnostics.image.ImagePointer;
+import javax.tools.diagnostics.image.ImageProcess;
+import javax.tools.diagnostics.runtime.ManagedRuntime;
+import javax.tools.diagnostics.runtime.java.JavaRuntime;
+import javax.tools.diagnostics.runtime.java.JavaVMOption;
+/**
+ * This Analyzer generates a reports information useful for
+ * identifying the JVM that was running when the snapshot was taken.
+ * Elements from the Java and Image APIs are used.
+ */
+public class WhatAnalyzer implements ImageAnalyzer {
+
+	@Override
+	public void analyze(Image image) {
+]]>
+</programlisting>
+</example>
+
+The hostname is first printed out. Unlike some examples, the exceptions are being properly
here.
+As it is important to get out as much information as possible, calls to the API are made
with
+try/catch blocks around each individual method
+The stack traces for <classname>DataUnavailable</classname> are not usually reported
as this
+is not an error condition. Instead, a message is inserted to indicate that information is
uknown.
+
+<example xml:id="api.examples.what.hostname">
+<title>Getting the hostname</title>
+<programlisting>
+<![CDATA[
+		// Report the hostname.
+		String hostname;
+		try {
+			hostname = image.getHostName();
+		} catch (DataUnavailable e) {
+			hostname = "<Could not retrieve hostname";
+		} catch (CorruptDataException e) {
+			hostname = "<Error retrieving hostname>";
+			e.printStackTrace();
+		}
+		System.out.println("Snapshot was generated on " + hostname);
+]]>
+</programlisting>
+</example>
+	
+Here the program iterates over all of the address spaces, and then the processes.
+The process ID is printed out, which is returned as a String. It is suggested
+that implementors return a decimal integer.
+		
+<example xml:id="api.examples.what.processid">
+<title>Reporting the process ID</title>
+<programlisting>
+<![CDATA[
+		for (ImageAddressSpace as : image.getAddressSpaces()) {
+			for(ImageProcess process : as.getProcesses()) {
+				String processID;
+				try {
+					processID = process.getID();
+				} catch (DataUnavailable e) {					
+					processID = "<Unknown>";
+				} catch (CorruptDataException e) {
+					processID = "<Error>";
+					e.printStackTrace();
+				}
+				System.out.println("Process ID="+processID);
+]]>
+</programlisting>
+</example>
+
+The API can return the command line that was used to start a process.
+The command line is a single String that was generated from the options
+passed to the process concatenated and separated by spaces. 
+
+<example xml:id="api.examples.what.commandline">
+<title>Command line</title>
+<programlisting>
+<![CDATA[
+
+				String commandLine;
+				try {
+					commandLine = process.getCommandLine();
+				} catch (DataUnavailable e) {
+					commandLine = "<Unknown>";
+				} catch (CorruptDataException e) {
+					commandLine = "<Error>";
+					e.printStackTrace();
+				}
+				System.out.println("Command line: "+commandLine);
+]]>
+</programlisting>
+</example>
+
+Here the executable that started the process is reported. This is the executable that 
+launched the JVM -t ypically this is the "java" program. Alternatives include  
+"javac" and "appletviewer".
+			
+<example xml:id="api.examples.what.executable">
+<title>Executable name</title>
+<programlisting>
+<![CDATA[
+
+				String executable;
+				try {
+					executable = process.getExecutable().getName();
+				} catch (CorruptDataException e) {
+					executable = "<Unknown>";
+				} catch (DataUnavailable e) {
+					executable = "<Error>";
+					e.printStackTrace();
+				}
+				System.out.println("Process Executable "+ executable);
+]]>
+</programlisting>
+</example>
+
+This code prints out the names of the libraries that were loaded by the process.
+This should include any JNI libraries that were configured. Note that it is also
+possible to determine where in memory these libraries have been mapped using the
+<methodname>ImageModule.
+. This can
+be used to identify where a thread might have crashed.
+			
+<example xml:id="api.examples.what.libaries">
+<title>Process libraries</title>
+<programlisting>
+<![CDATA[
+
+				System.out.println("Loaded Libraries:");
+				try {
+					for(ImageModule module : process.getLibraries()) {
+						System.out.println("\t" + module.getName());
+					}
+				} catch (DataUnavailable e) {
+					System.out.println("No libraries found.");
+				} catch (CorruptDataException e) {
+					System.out.println("Error retrieving libraries:");
+					e.printStackTrace();
+				}
+				
+				for (ManagedRuntime runtime : process.getRuntimes()) {
+					if (runtime instanceof JavaRuntime) {
+						analyzeRuntime ((JavaRuntime) runtime);
+					}
+				}
+			}
+		}
+	}
+
+	public void analyzeRuntime(JavaRuntime jr) {
+]]>
+</programlisting>
+</example>
+
+The following code reports the Java VM version. This is implementation dependent,
+but is expected to contain more than just the version of Java that is supported.
+			
+<example xml:id="api.examples.what.version">
+<title>Java VM Version</title>
+<programlisting>
+<![CDATA[
+		
+		try {
+			System.out.println("Java VM version:`"+jr.getVersion()+"'");
+		} catch (CorruptDataException e1) {
+			System.out.println("Error retrieving Java VM version");
+			e1.printStackTrace();
+		}
+		]]>
+</programlisting>
+</example>
+			
+The following code reports the options that were passed to the JVM when it was created.
+The options are generated and passed on by the executable the launches Java. Some of these
+might be passed on the command line (such as by the "java" executable), but might also include
+options taken in from configuration files, as well as being generated by the launcher itself.
+			
+<example xml:id="api.examples.what.options">
+<title>Java VM Options</title>
+<programlisting>
+<![CDATA[
+		
+		System.out.println("VM options:");
+		try {
+			for (JavaVMOption option : jr.getJavaVMInitArgs().getOptions()) {
+				String optionString = "\t\t\""+option.getOptionString()+"\"";
+				
+				ImagePointer extra = option.getExtraInfo();
+				if (extra != null) {
+					optionString += ", extraInfo=0x"+Long.toHexString(extra.getAddress());
+				}
+				
+				System.out.println(optionString);
+			}
+		} catch (DataUnavailable e) {
+			System.out.println("Unable to report VM options");
+		} catch (CorruptDataException e) {
+			System.out.println("Error retrieving VM options");
+			e.printStackTrace();
+		}
+	}
+}
+]]>
+</programlisting>
+</example>
+
+	</para>
+	</sect2>
+</sect1>



Mime
View raw message