[wiki.stajistics] push by - Edited wiki page GettingStarted through web user interface. on 2011-07-14 19:19 GMT

[staji...@googlecode.com]

Revision: 6655fcb32ef1
Author: troy.k...@gmail.com
Date: Thu Jul 14 12:19:49 2011
Log: Edited wiki page GettingStarted through web user interface.
http://code.google.com/p/stajistics/source/detail?repo=wiki&r=6655fcb32ef1

Modified:
/GettingStarted.wiki

=======================================
--- /GettingStarted.wiki Tue Jun 21 08:17:45 2011
+++ /GettingStarted.wiki Thu Jul 14 12:19:49 2011
@@ -96,7 +96,63 @@

== Track Something! ==

-As mentioned, a StatsTracker can be used directly in client code to track
specific things.
+=== Preparing for Statistics Collection ===
+
+The first step to using Stajistics in your code is to obtain an instance
of a StatsFactory, which is done as follows:
+
+{{{
+ StatsFactory statsFactory = StatsFactory.forClass(getClass());
+}}}
+
+Ideally, like a Logger, the StatsFactory can be stored as a static
variable within your class (a StatsFactory is thread safe):
+
+{{{
+ import org.stajistics.StatsFactory;
+
+ public MyClass {
+ private static StatsFactory statsFactory =
StatsFactory.forClass(MyClass.class);
+ }
+}}}
+
+The first thing to do with a StatsFactory is to create a key to represent
a particular target.
+
+{{{
+ StatsKey key = statsFactory.newKey("myAlgorithm");
+}}}
+
+As StatsKeys are immutable, they too are thread safe, and can be stored
statically to avoid the overhead of creation every time the target is
executed.
+
+{{{
+ import org.stajistics.StatsFactory;
+ import org.stajistics.StatsKey;
+
+ public MyClass {
+ private static StatsFactory statsFactory =
StatsFactory.forClass(MyClass.class);
+
+ private static StatsKey myAlgorithmKey =
statsFactory.newKey("myAlgorithm");
+ }
+}}}
+
+The `myAlgorithmKey` instance can now represent all invocations of the
theoretical myAlgorithm. But, what happens if you want to collect
statistics related to something that can only be known at runtime? This is
where key copying and key attributes come in to play. Say, for example,
that the myAlgorithm method takes a String parameter that specifies the
underlying strategy by which the method satisfies its contract. The
performance of myAlgorithm may vary based on the strategy used, so
measurements need to be stored specific to the strategy. The solution is to
make a copy of the myAlgorithmKey at runtime which has an attribute
specifying the passed-in strategy:
+
+{{{
+ public MyClass {
+ private static StatsFactory statsFactory =
StatsFactory.forClass(MyClass.class);
+
+ private static StatsKey myAlgorithmKey =
statsFactory.newKey("myAlgorithm");
+
+ public void myAlgorithm(String strategy) {
+ StatsKey strategySpecificKey =
+ myAlgorithmKey.buildCopy()
+ .withAttribute("strategy", strategy)
+ .newKey();
+
+ // Use strategySpecificKey (how to use a key is described blow)
+ }
+ }
+}}}
+
+Lastly, what if you wanted to track the performance of myAlgorithm for all
strategies combined as well as per-strategy. For this case, you would
simply use both keys at once: myAlgorithmKey and strategySpecificKey. How
to do this will become clear shortly. Keep reading.

=== Incidents ===

@@ -104,8 +160,8 @@

{{{
public void somethingInteresting() {
- Stats.incident("somethingInteresting");
- // do something
+ statsFactory.incident(key);
+ // do something interesting
}
}}}

@@ -113,8 +169,9 @@

{{{
public void somethingInteresting() {
- IncidentTracker tracker = Stats.getIncidentTracker(new
StatsKey("somethingInteresting"));
+ IncidentTracker tracker = statsFactory.getIncidentTracker(key);
tracker.incident();
+ // do something interesting
}
}}}

@@ -124,7 +181,7 @@

{{{
public void bigLongAlgorithm() {
- SpanTracker tracker = Stats.track("bigLongAlgorithm");
+ SpanTracker tracker = statsFactory.track(key);
try {
// Buuuubble soooort!
} finally {
@@ -137,7 +194,7 @@

{{{
public void bigLongAlgorithm() {
- SpanTracker tracker = Stats.getSpanTracker(new
StatsKey("bigLongAlgorithm"));
+ SpanTracker tracker = statsFactory.getSpanTracker(key);
tracker.track();
try {
// Buuuubble soooort!
@@ -153,7 +210,7 @@

{{{
public void setUserAge(int age) {
- ManualTracker tracker = Stats.getManualTracker("user.age");
+ ManualTracker tracker = statsFactory.getManualTracker(key);
tracker.setValue(age);
tracker.commit();

@@ -165,11 +222,33 @@

{{{
public void setUserAge(int age) {
- Stats.getManualTracker("user.age").setValue(age).commit();
+ statsFactory.getManualTracker(key).setValue(age).commit();

this.age = age;
}
}}}
+
+=== Aggregating Keys ===
+
+In each of the above tracker examples, multiple key instances can be
passed into the appropriate StatsFactory method that returns a Tracker
instance. This would record the collected data for each key individually.
+
+To extend the example started in the "Preparing for Statistics Collection"
section, myAlgorithm could aggregate the `myAlgorithmKey` and the
`strategySpecificKey` like so:
+
+{{{
+ public void myAlgorithm(String strategy) {
+ StatsKey strategySpecificKey =
+ myAlgorithmKey.buildCopy()
+ .withAttribute("strategy", strategy)
+ .newKey();
+
+ SpanTracker tracker = statsFactory.track(myAlgorithmKey,
strategySpecificKey);
+ try {
+ // Run the algorithm
+ } finally {
+ tracker.commit();
+ }
+ }
+}}}

=== Getting Dynamic ===