Version bump to 0.2.0. Updates to README. Add HISTORY file.

CHANGELOG

@@ -0,0 +1,9 @@
+## 0.2.0
+
+* Added the Camayoc::Stats#event method to do general event logging
+* Refactored handler event propagation; handlers now implement an event(stat_event) method instead of count and timing
+* Logging and IO handler formatter Procs now take a single StatEvent as an argument
+
+## 0.1.0
+
+* Initial release

README.md

@@ -1,9 +1,9 @@
 Overview
 ========
-Camayoc is a flexible way to keep track of application stats. Inspired by 
-various logging frameworks (especially Log4r) it makes it easy to send stats 
-information to multiple destinations via the use of Handlers. Right out of the 
-box, it supports sending stats to the following:
+Camayoc is a flexible way to keep track of application stats and events. 
+Inspired by various logging frameworks (especially Log4r) it makes it easy to 
+send stats information to multiple destinations via the use of Handlers. Right 
+out of the box, it supports sending stats to the following:
 
 * A [statsd daemon](https://github.com/etsy/statsd/) for ridiculously easy [Graphite](http://graphite.wikidot.com/) stats
 * An in-memory hash for in-process stats
@@ -12,13 +12,25 @@ box, it supports sending stats to the following:
 
 Philosophy
 ----------
-Application stats are critical. But even critical things get ignored if they're 
-hard (believe me, we know). Stats should be easy:
+Keeping track of what goes on in your application is critical. But even 
+critical things get ignored if they're hard (believe me, we know). Camayoc's aim 
+is to make logging events and capturing stats easy:
 
-* Collecting stats should take just one line of code
-* All stat collection should be fire-and-forget with no error handling required
-* Organizing stats should be easy
-* There should be essentially no performance cost to collecting stats
+* Collecting this data should take just one line of code
+* All data collection should be fire-and-forget with no error handling required
+* Organizing stats and events should be easy
+* There should be essentially no performance cost to collecting this data
+
+Events vs Stats
+---------------
+In general, events are things that happen in your application that you care 
+about. There are two ways to keep track of events:
+
+* Keep summary stats about event occurances around (counts, etc)
+* Keep a detailed record of events that occur in a some sort of log or collection
+
+Through its use of flexible handlers, Camayoc makes it possilbe to do one or 
+both of these through a single simple interface.
 
 Examples
 ==========
@@ -96,6 +108,24 @@ There are other options as well like :if and :unless that take Procs that can
 be executed to determine if a metric should be sent to the specified handler.
 See Camayoc::Handlers::Filter for more.
 
+Event Logging
+-------------
+Sometimes you may want to keep a detailed log of events that occur instead of 
+summarizing then via counts. Below is an example of logging event data in a 
+space-delimited format to an IO stream:
+
+    event_log = Camayoc["events"]
+    fmt = Proc.new do |event| 
+      ([event.ns_stat, Time.now.to_i] + Array(event.value)).join(" ") 
+    end
+    event_log.add(Camayoc::Handlers::IO.new(STDOUT,:formatter=>fmt))
+
+    event_log.event("foo",["bar","baz"])
+
+This will produce the following on stdout:
+
+    events:foo 1321564751 bar baz
+
 Available Handlers
 ==================
 Statsd
@@ -105,13 +135,21 @@ Class: Camayoc::Handlers::Statsd
 This handler sends data to the statd daemon for use in graphite. If you can get 
 graphite and statsd going, then you'll get pretty graphs.
 
+This handler does not support logging details about events since this isn't 
+really what statsd and graphite are for. Any calls to the event method will be 
+treated as count stats when sent to statsd.
+
 Memory
 ------
 Class: Camayoc::Handlers::Memory
 
 Stores counts and timing data in an in-memory hash. This might be handy for 
 storing some temporary in-process stats.
 
+If you use this handler for event logging, data will be stored in an in-memory 
+array with a configurable max size. If that size is exceeded, older events will 
+be evicted to make room for new events.
+
 Logger
 ------
 Class: Camayoc::Handlers::Logger
@@ -120,13 +158,18 @@ Writes out stat values and a timestamp to a logger instance for later analysis.
 The format and method called on the logger can be controlled by constructor 
 arguments. See the class for details.
 
+This handler is best for event logging, especially when combined with a custom 
+formatter.
+
 IO
 --
 Class: Camayoc::Handlers::IO
 
 Writes out stats values and a timestamp to some stream of your choice. See 
 class for configuration details.
 
+Another good event logging handler.
+
 Redis (Experimental)
 --------------------
 Class: Camayoc::Handlers::Redis (require "camayoc/handlers/redis" first) 
@@ -137,23 +180,37 @@ time-based stats system. It does make it easy to collect some simple counts and
 some timing data. You can easily retrieve the stored data from redis by using 
 the #get method.
 
+This handler does not currently support event logging.
+
 
 Implementing a Handler
 ======================
-Let's say you want to implement your own handler, pehaps to MongoDB. Handlers 
+
+v0.2+ Incompatibility Notice
+----------------------------
+As of Version 0.2.0, handlers must implement an event method. In 0.1.0, 
+handlers had to implement count and timing methods. Now handlers are encouraged 
+to dispatch events as described below.
+
+Implementation Example
+---------------------- 
+Let's say you want to implement your own handler, perhaps to MongoDB. Handlers 
 just need to respond to a simple interface. See Camayoc::Handlers::StatEvent 
-for info on the argument to the two methods.
+for info on the argument to the event method.
 
     class SomeHandler
-      def count(stat_event)
-        # Do something
-      end
-      
-      def timing(stat_event)
-        # Do something
+      def event(evt)
+        case evt.type
+          when :count   then handle_count(evt)  # do something with a count stat
+          when :timing  then handle_timing(evt) # do something with a timing stat
+          when :generic then handle_other(evt)  # do something with a generic event
       end
     end
 
+If you were writing a MongoDB handler, the above might increment a value in 
+a collection on :count and :timing and store raw data to a collection for 
+:generic events.
+
 If you write a handler and would like it included in Camayoc, please fork 
 and send a pull request and we'll get it integrated in.
 

lib/camayoc/version.rb

@@ -1,3 +1,3 @@
 module Camayoc
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end