[wiki.stajistics] push by - Edited wiki page GettingStarted through web user interface. on 2011-06-21 15:17 GMT
staji...@googlecode.com
Author: troy.k...@gmail.com
Date: Tue Jun 21 08:17:45 2011
Log: Edited wiki page GettingStarted through web user interface.
http://code.google.com/p/stajistics/source/detail?repo=wiki&r=2be7b6172b6f
Modified:
/GettingStarted.wiki
=======================================
--- /GettingStarted.wiki Tue Jun 21 05:57:19 2011
+++ /GettingStarted.wiki Tue Jun 21 08:17:45 2011
@@ -4,6 +4,14 @@
== Getting To Know Stajistics ==
+=== Terminology ===
+
+ * Target - Something upon which statistical data can be measured and
collected.
+ * Key - Represents a target. Associated with trackers and a session.
+ * Tracker - Knows how to measure statistical data. Several instances per
key.
+ * Session - Stores and performs calculations on statistical data. One
instance per key.
+ * Field - A named unit of data stored in a session. Several fields per
session.
+
=== Keys ===
In Stajistics, a key is what answers the question, "On what do I collect
statistics?"
@@ -14,9 +22,9 @@
As an example, a key of "org.myapp.service.requests" may be assigned to
track the number of requests that a service receives. As another example, a
key of "org.myapp.servlet.sessions" might track the number and duration of
user sessions managed by a web app.
-TODO: describe how StatKey attributes are used
-
-For more details on keys, see the
[http://www.stajistics.org/stajistics-core/apidocs/org/stajistics/StatsKey.html
StatsKey JavaDoc]
+A StatsKey is typically composed of a static name, as well as any number
of attributes, which incorporate runtime data into the uniqueness of the
key. For example, a key that represents how long an application executes
could be composed of a simple static name, such as, "myapp.executionTime".
There would be no need to incorporate runtime data into the key because
there is just _one_ application lifespan. However, a key that represents
how long a user has been logged in, for example, must incorporate the
runtime data of the user name or ID to make the key unique per-user. So, a
key could be composed having a static name, "myapp.user.logins", and with
an attribute, "username"="john", where "john" is supplied at runtime, upon
a user login.
+
+For more details on keys, see the
[http://code.google.com/p/stajistics/source/browse/stajistics-core/src/main/java/org/stajistics/StatsKey.java
StatsKey source and JavaDoc]
=== Trackers ===
@@ -63,6 +71,8 @@
|| ManualTracker || Collects whatever numerical data is fed to it. ||
|| 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. ||
+For any SpanTracker, calling track() marks the beginning point of the span
being monitored, while calling commit() marks the end point of the span.
+
== What Gets Collected? ==
When a tracker collects a unit of statistical data, it hands it off to the
session where it is stored and/or minor initial calculations are performed
upon it. A piece of data stored in a session is known as a field, and is
identified by a name.
@@ -72,16 +82,17 @@
The following is a table of standard fields stored in a session:
|| Field Name || Description ||
-|| hits || TODO ||
-|| firstHitStamp || TODO ||
-|| lastHitStamp || TODO ||
-|| commits || TODO ||
-|| first || TODO ||
-|| last || TODO ||
-|| min || TODO ||
-|| max || TODO ||
-|| sum || TODO ||
-
+|| hits || The total number of times a tracker was invoked. ||
+|| firstHitStamp || The long time stamp of the first hit recorded by the
session. ||
+|| lastHitStamp || The long time stamp of the most recent hit recorded by
the session. ||
+|| commits || The total number of times a unit of data was submitted to
the session. ||
+|| first || The first unit of data committed to the session. ||
+|| last || The most recent unit of data committed to the session. ||
+|| min || The smallest seen unit of data committed to the session. ||
+|| max || The largest seen unit of data committed to the session. ||
+|| sum || The total of all units of data committed to the session. ||
+
+The 'hits' field is incremented when IncidentTracker#incident() is called,
or when SpanTracker#track() is called. The 'commits' field is incremented
upon IncidentTracker#incident() calls as well, and when
SpanTracker#commit() is called. For IncidentTrackers, hits and commits are
essentially the same metric, but for SpanTrackers, comparing hits to
commits (i.e. hits - commits) shows the number of trackers currently "in" a
span.
== Track Something! ==