[wiki.stajistics] push by - Edited wiki page GettingStarted through web user interface. on 2011-06-21 03:20 GMT
staji...@googlecode.com
Author: troy.k...@gmail.com
Date: Mon Jun 20 20:20:47 2011
Log: Edited wiki page GettingStarted through web user interface.
http://code.google.com/p/stajistics/source/detail?repo=wiki&r=e4291a2dab0e
Modified:
/GettingStarted.wiki
=======================================
--- /GettingStarted.wiki Mon Jun 20 18:31:27 2011
+++ /GettingStarted.wiki Mon Jun 20 20:20:47 2011
@@ -1,70 +1,13 @@
-#Stajistics usage first steps
+#summary Stajistics usage first steps
= Getting Started =
-== 1. Prerequisites ==
-
-The most basic use of Stajistics requires Java 1.6. It is recommended that
Stajistics be used in application configurations that expose management via
JMX. While Stajistics can happily collect statistics without it, being able
to monitor statistics in real time using JMX is really where Stajistics
shines.
-
-== 2. Install Stajistics ==
-
-Installation only requires that you add `stajistics-core-<version>.jar`
and its dependent jars to your project classpath. The only dependency of
the stajistics-core module is `slf4j-api-<version>.jar` for logging. Refer
to [http://www.slf4j.org the SLF4J website] for information on how to
configure logging.
-
-Stajistics provides feature extensions in the form of separate module
jars. One of the reasons for this is that a given feature may require
additional dependency jars. This project model allows the user to select
the desired features while not forcing the need for dependency jars of
undesired features.
-
-=== Using Maven ===
-
-==== Releases ====
-
-NOTE: THE MAVEN REPOSITORY IS CURRENTLY DOWN. PLEASE DOWNLOAD ARTEFACTS
FROM THE DOWNLOADS SECTION FOR THE TIME BEING. Sorry :(
-
-Add the following to your repositories:
-
-{{{
- <repositories>
- <repository>
- <id>stajistics</id>
- <url>http://repository.stajistics.org/releases</url>
- </repository>
- </repositories>
-}}}
-
-Add the following to your dependencies:
-
-{{{
- <dependency>
- <groupId>org.stajistics</groupId>
- <artifactId>stajistics-core</artifactId>
- <version>[version]</version>
- </dependency>
-}}}
-
-==== Snapshots ====
-
-Add the following to your repositories:
-{{{
- <repository>
- <id>stajistics</id>
- <url>http://repository.stajistics.org/snapshots</url>
- <snapshots>
- <enabled>true</enabled>
- </snapshots>
- </repository>
-}}}
-
-Add the following to your dependencies:
-{{{
- <dependency>
- <groupId>org.stajistics</groupId>
- <artifactId>stajistics-core</artifactId>
- <version>[version]-SNAPSHOT</version>
- </dependency>
-}}}
-
-== 3. Getting To Know Stajistics ==
+== Getting To Know Stajistics ==
=== Keys ===
+In Stajistics, a key is what answers the question, "On what do I collect
statistics?"
+
To track statistics about something, a key must be assigned to that
something. In Stajistics documentation, something to track is referred to
as a _target_. The purpose of a key is to provide a handle which can be
used to access and manipulate statistical data and configuration that is
specific to a _target_.
Assigning a key to a _target_ can be as simple as selecting a unique key
name and, in your Java code, passing the key name String into one of the
available statistics collection methods. A key can be represented by a
StatsKey instance, or by a simple String (which is converted into a
StatsKey automatically under the hood). Keys in String form are supported
as a convenience for clients migrating from other statistics/monitoring
APIs, but keys in StatsKey instance form are far more useful, and as such,
are recommended over the use of String keys.
@@ -77,6 +20,8 @@
=== Trackers ===
+In Stajistics, a tracker is what answers the question, "how do I measure
things to get statistical data from them?"
+
A StatsTracker is what receives statistical data from a _target_ piece of
code. It is the main interface between the client code and the Stajistics
system for the collection of data. A StatsTracker is associated with a
single StatsKey, however, there may be many StatsTracker instances alive at
a time for a StatsKey.
There are three main types of trackers, all of which implement the
StatsTracker interface:
@@ -90,6 +35,8 @@
=== Sessions ===
+In Stajistics, a session is what answers the question, "What statistical
data do I store?"
+
A StatsSession holds statistical data (in memory) collected over the
lifetime of a running application. A StatsSession is also associated with a
single StatsKey, and there will only ever be one StatsSession instance
alive for a StatsKey.
Every StatsTracker instance has a reference to its StatsSession, and when
it is told, it will publish the data it collected to the session for longer
term storage.
@@ -100,7 +47,23 @@
Statistical data does not have to live in a session in-memory forever.
When the application shuts down, or when prompted by the management
interface, data can be dumped to a more permanent medium, such as a
filesystem or a database. (Note: this capability is not currently
implemented, but planned for the near future).
-== 4. Track Something! ==
+== What Can I Track? ==
+
+The following is a table of tracker implementations that are standard in
the stajistics-core module.
+
+|| Tracker Name || Description ||
+|| TimeDurationTracker || Records the amount of time, in various
precisions, between a start and end point. ||
+|| ConcurrentAccessTracker || Tracks how many simultaneous accesses occur
to a span defined by a start and end point. ||
+|| HitFrequencyTracker || Measures the amount of time between accesses to
a span defined by a start and end point. ||
+|| GarbageCollectionTimeTracker || Records the amount of time spent in
garbage collection between a start and end point. ||
+|| ThreadCPUTimeTracker || Records the amount of CPU time allotted to a
thread between a start and end point. ||
+|| ThreadBlockTimeTracker || Measures the amount of time a thread spent
blocking between a start and end point. ||
+|| ThreadWaitTimeTracker || Measures the amount of time a thread spent
waiting between a start and end point. ||
+|| CompositeSpanTracker || Aggregates several configurable trackers into
one for simple collection of multiple kinds of data on a single span
defined by a start and end point. ||
+
+TODO: talk about where the data goes.
+
+== Track Something! ==
As mentioned, a StatsTracker can be used directly in client code to track
specific things.
@@ -212,6 +175,6 @@
}}}
-== 5. View Collected Statistics ==
-
-TODO
+== View Collected Statistics ==
+
+Coming soon...