incubator-kato-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From spo...@apache.org
Subject svn commit: r806080 - /incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml
Date Thu, 20 Aug 2009 08:04:44 GMT
Author: spoole
Date: Thu Aug 20 08:04:44 2009
New Revision: 806080

URL: http://svn.apache.org/viewvc?rev=806080&view=rev
Log:
tidy up of introduction 

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

Modified: incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml
URL: http://svn.apache.org/viewvc/incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml?rev=806080&r1=806079&r2=806080&view=diff
==============================================================================
--- incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml (original)
+++ incubator/kato/trunk/org.apache.kato/kato.docs/src/docbkx/chapters/Introduction.xml Thu
Aug 20 08:04:44 2009
@@ -33,23 +33,7 @@
 		<para>This project is about bringing together people and ideas to
 			create a common, cross industry API, and we can't think of a better
 			place to do that than in Apache.</para>
-	</section>
-
-	<section xml:id="introduction.background">
-		<title>Background</title>
-		<para>Post-mortem versus Live Monitoring: It's worth noting
-			that the term "post mortem" is used loosely. It does not just imply
-			dead Java Virtual Machines and applications; JSR 326 also covers
-			living, breathing applications where the dump artefacts are
-			deliberately produced as part of live monitoring activity. Live
-			monitoring generally means tracing, profiling, debugging, or even
-			bytecode monitoring and diagnosis by agents via the
-			java.lang.instrument API . It can also mean analysis of dumps to look
-			for trends and gather statistics.
-			The live-monitoring diagnostic space
-			is well served except for this last
-			area, which is where JSR 326 can
-			help.
+		<para>
 			IBM developed an API called DTFJ ("Diagnostic Tooling and
 			Framework for
 			Java") as a means of providing its support teams a basis
@@ -63,6 +47,9 @@
 		<para>In 2009 IBM donated the implementation dependent portions of
 			DTFJ to the Apache Kato project</para>
 	</section>
+
+
+
 	<section xml:id="introduction.rationale">
 		<title>Rationale</title>
 		<para>JSR 326 exists because of the widely acknowledged limitations
@@ -72,29 +59,39 @@
 			happen, but
 			few credible or pervasive tools exist for helping resolve
 			problems
-			when all has gone suddenly and horribly wrong.
+			when all has gone suddenly and horribly wrong.</para>
+		<para>
 			Outside of "live
-			monitoring" there is no standard way to provide diagnostics
+			monitoring" there is no standard way to provide
+			diagnostics
 			information, and hence no standard tools.
-			Each tool writer has to
+			Each tool writer
+			has to
 			figure out how to access the data individually
-			and specifically for
+			and specifically
+			for
 			each JVM vendor and operating system.
-			This sparsity of tools has meant
+			This sparsity of tools has
+			meant
 			that users have limited options in
 			diagnosing their own problems,
 			especially unexpected or intermittent
-			failures.
+			failures.</para>
+		<para>
 			Consequently these
-			users turn to the providers of their software to work out what
+			users turn to the providers of their software
+			to work out what
 			is
 			happening.
-			Application, middleware, and JVM vendors are spending
+			Application, middleware, and JVM vendors
+			are spending
 			increasing time supporting
-			customers in problem diagnosis. Emerging
+			customers in problem diagnosis.
+		</para>
+		<para>Emerging
 			trends indicate that this is
-			going to get worse. 
-    </para>
+			going to get worse.
+		</para>
 		<para>
 			Today JVM heap sizes are measured in small numbers of gigabytes,
 			processors on desktops come in twos or fours,
@@ -103,38 +100,86 @@
 			analyse problems in
 			these configurations,
 			we use a disparate set of diagnostic tools and
-			artefacts. If the
+			artefacts. </para>
+		<para>If the
 			problem can't be reproduced in a debugger,
 			then
-			things quickly get complicated. There are point tools for problems
-			like deadlock analysis or the ubiquitous Java out-of-memory problems,
-			but overall the Java diagnostic tools arena is fragmented and JVM- or
+			things
+			quickly get complicated. There are point tools for problems
+			like
+			deadlock analysis or the ubiquitous Java out-of-memory problems,
+			but
+			overall the Java diagnostic tools arena is fragmented and JVM- or
 			OS-specific. Tool writers have to choose their place in this matrix.
-			We want to change that by removing the need for tool writers to make
-			a choice. By enabling tool writers to easily target all the major JVM
+		</para>
+		<para>We want to change that by removing the need for tool writers
+			to make
+			a choice.</para>
+		<para>By enabling tool writers to easily target all the major JVM
 			vendors and operating systems,
 			we expect the number and capability of
 			diagnostic tools to greatly
-			increase.
-			Tomorrow it gets harder; heap
-			sizes hit 100's of gigabytes, processors come
-			packaged in powers of
-			16, and the JVM commonly executes a wide range
-			of language
-			environments.
-			We can't tackle tomorrow's problems until we have a
-			platform to address
-			today's.
+			increase.</para>
+		<para>
+			Tomorrow it gets harder; heap sizes hit 100's of gigabytes,
+			processors come packaged in powers of 16, and the JVM commonly executes
+			a wide range of language environments.</para>
+		<para>
+			We can't tackle tomorrow's problems until we have a platform to
+			address	today's.
 	</para>
 	</section>
+	<section xml:id="introduction.pmvslm">
+		<title>Post Mortem versus Live Monitoring</title>
+		<para>It's important to understand what the term "post mortem"
+			means as far as JSR 326 is concerned and how it fits within the
+			general Post-mortem versus Live Monitoring space.
+		</para>
+		<para>For JSR 326 the term "post mortem" is used loosely: it does
+			not just imply dead Java Virtual Machines and applications; JSR 326
+			also covers living, breathing applications where the dump artefacts
+			are deliberately produced as part of live monitoring activity.
+		</para>
+		<para>For JSR 326 "Post Mortem" just means "after the fact"</para>
+		<para>Live monitoring generally means tracing, profiling,
+			debugging, or even
+			bytecode monitoring and diagnosis by agents via the
+			java.lang.instrument API. It can be a surprise to understand that It
+			can also mean analysis of dumps to look
+			for trends and gather
+			statistics.</para>
+		<para>
+			The live-monitoring diagnostic space
+			is well served except for this
+			last
+			area. The mutation speed of modern applications under load can
+			sometimes mean
+			that monitoring systems cannot keep pace since they
+			need to do complex
+			analysis
+			<emphasis>on-the-fly</emphasis>
+			The obvious solution is to take a snapshot of a running system and
+			analyse the results
+			<emphasis>off-line</emphasis>
+		</para>
+		<para>
+			JSR 326 can help with this "Snapshot monitoring" by providing a
+			standard mechanism for generating a snapshot and for reading the
+			contents
+			of the snapshot later.
+		</para>
+	</section>
 	<section>
 		<title>Tell me more about "Diagnostic Artifacts"</title>
 		<para>
 			Simply put, when something goes wrong you'd like to know why.
-			A diagnostic artifact is whatever material is left when your
+			A
+			diagnostic artifact is whatever material is left when your
 			application or JVM fails.
-			Sometimes it's a message to the console, or a record in a log file.
-			Hopefully you'll get enough information to figure out what happened and fix
+			Sometimes it's a message to the console, or
+			a record in a log file.
+			Hopefully you'll get enough information to
+			figure out what happened and fix
 			the problem.
 		</para>
 		<para>
@@ -145,40 +190,66 @@
 		<para>
 			In those situations you need access to more information so you can
 			dig into the causes of your problem.
-			Historically the sorts of artifact you need are split into two types: those which
-			show a time element
-			and those that are a snapshot of working system. The former of these
+			Historically the sorts of
+			artifact you need are split into two types: those which
+			show a time
+			element
+			and those that are a snapshot of working system. The former of
+			these
 			types is of course a trace, while the
 			latter comes under the term
 			<quote>dump</quote>
 			or
-			<quote>core file</quote>.</para>
-			<para>It's these latter type that JSR 326 is designed to consume.
+			<quote>core file</quote>
+			.
+		</para>
+		<para>It's these latter type that JSR 326 is designed to consume.
 		</para>
 	</section>
 	<section>
 		<title>What types of Dump are supported by this API?</title>
-		<para>The Apache Kato incubator project is developing the reference implementation
for JSR 326. 
-		That work includes the development of an implementation that can read standard binary HPROF
files and an experimental new dump
-		 that uses JVMTI to expose more information than is currently in a HPROF file.
+		<para>The Apache Kato incubator project is developing the reference
+			implementation for JSR 326.
+			That work includes the development of an
+			implementation that can read
+			standard binary HPROF files and an
+			experimental new dump
+			that uses JVMTI to expose more information than
+			is currently in a HPROF
+			file.
 		</para>
-		<para>Other JVM vendors can develop implementations to support the API for their
own dumps.</para>     
+		<para>Other JVM vendors can develop implementations to support
+			the API for their own dumps.</para>
 	</section>
 	<section>
 		<title>What data can I expect to find in a Dump?</title>
-			<para>
-			Dumps come in all shapes and sizes. There is no definitive statement of contents.  The
API is designed to accomodate this fact by providing a mechanism to signal that data is not
available.
-			Note that the design of the API to handle data optionality is still not completed.   
+		<para>
+			Dumps come in all shapes and sizes. There is no definitive
+			statement of contents. The API is designed to accomodate this fact by
+			providing a mechanism to signal that data is not available.
+			Note that
+			the design of the API to handle data optionality is still not
+			completed.   
 			</para>
-			<figure id="process1" pgwide="0"><title>Dump contents</title>
-					<mediaobject >
-					<imageobject>
-						<imagedata format="SVG"	depth="3in" scalefit="1" fileref="../figures/process.svg"
/>
-					</imageobject>
-				</mediaobject>
-			</figure>
-			<para>Its still possible to determine broad categories for the contents of a dump.
In <xref linkend='process1'/>  you can see that its reasonable to have three categories
-
-			 from the dump which has all process information down to the dump which only contains
objects from the Java heap.</para>  
+		<figure id="process1" pgwide="0">
+			<title>Dump contents</title>
+			<mediaobject>
+				<imageobject>
+					<imagedata format="SVG" depth="3in" scalefit="1"
+						fileref="../figures/process.svg" />
+				</imageobject>
+			</mediaobject>
+		</figure>
+		<para>
+			Its still possible to determine broad categories for the contents of
+			a dump. In
+			<xref linkend='process1' />
+			you can see that its reasonable to have three categories -
+			from the
+			dump which has all process information down to the dump which
+			only
+			contains objects from the Java heap.
+		</para>
 	</section>
-	
+
 </chapter>
\ No newline at end of file



Mime
View raw message