Update docs

Author: Peter Mogensen

metric/client.go

@@ -229,30 +229,65 @@ func (c *Client) Flush() {
 
 //--------------------------------------------------------------
 
+// RegisterCounter is equivalent to Register(NewCounter(), opts) with the default Client.
 func (c *Client) RegisterCounter(name string, opts ...MOption) *Counter {
 	meter := NewCounter(name)
 	c.Register(meter, opts...)
 	return meter
 }
 
+// RegisterGauge is equivalent to Register(NewGauge(), opts) with the default Client.
 func (c *Client) RegisterGauge(name string, opts ...MOption) *GaugeUint64 {
 	meter := NewGauge(name)
 	c.Register(meter, opts...)
 	return meter
 }
 
+// RegisterTimer is equivalent to Register(NewTimer(), opts) with the default Client.
 func (c *Client) RegisterTimer(name string, opts ...MOption) Timer {
 	meter := NewTimer(name)
 	c.Register(meter, opts...)
 	return meter
 }
 
+// RegisterHistogram is equivalent to Register(NewHistogram(), opts) with the default Client.
 func (c *Client) RegisterHistogram(name string, opts ...MOption) Histogram {
 	meter := NewHistogram(name)
 	c.Register(meter, opts...)
 	return meter
 }
 
+
+//--------------------------------------------------------------
+
+// RegisterCounter is equivalent to Register(NewCounter(), opts) with the default Client.
+func RegisterCounter(name string, opts ...MOption) *Counter {
+	meter := NewCounter(name)
+	defaultClient.Register(meter, opts...)
+	return meter
+}
+
+// RegisterGauge is equivalent to Register(NewGauge(), opts) with the default Client.
+func RegisterGauge(name string, opts ...MOption) *GaugeUint64 {
+	meter := NewGauge(name)
+	defaultClient.Register(meter, opts...)
+	return meter
+}
+
+// RegisterTimer is equivalent to Register(NewTimer(), opts) with the default Client.
+func RegisterTimer(name string, opts ...MOption) Timer {
+	meter := NewTimer(name)
+	defaultClient.Register(meter, opts...)
+	return meter
+}
+
+// RegisterHistogram is equivalent to Register(NewHistogram(), opts) with the default Client.
+func RegisterHistogram(name string, opts ...MOption) Histogram {
+	meter := NewHistogram(name)
+	defaultClient.Register(meter, opts...)
+	return meter
+}
+
 //--------------------------------------------------------------
 
 // AdhocCounter creates an ad-hoc counter metric event.

metric/doc.go

@@ -4,7 +4,41 @@ Package metric is a generic metric package for the standard metric types gauges/
 This implementation is aimed at being as fast as possible to not discourage metrics on values in hotpaths just because of locking overhead. This requires some client side buffering (and flusher go-routines) and, especially for the timer/histogram event type, a relatively large data structure to create a ring-buffer with mostly lock-free writes. (it uses condition variables for flushing).
 This design is for the use case where you have a lot of timer/histogram metric events going to a few buckets.
 
-The API is accessed via Client objects. (There's a default global client). The low latency and speed is achieved by creating permanent buffering metrics objects for each metric. Alternatively you can manually send ad-hoc metrics directly to the Clients configured sink. This allows for use cases where you don't have a small set of known metrics receiving many events, but rather many metrics receiving few evetns each.
+The API consists of 3 main types of objects:
+
+   * Meter - the object doing the actual measuring. (possibly buffering measurements)
+   * Sink  - an object to which Meter readings can be sent. Sinks can have internal buffering which can be flushed
+   * Client - an object responsible for sending Meter readings to an assigned Sink, possibly at configured flushing intervals.
+
+The API supports 3 approaches to maintaining your metrics:
+
+Ad-hoc
+
+Ad-hoc generation of metric events without a Meter object (explicitly flushing the Client sink):
+This is a relative slow, but simple way to generate metric data.
+This allows for use cases where you don't have a small set of known metrics receiving many events, but rather many metrics receiving few events each:
+
+   metric.SetDefaultSink(sink)
+   metric.AdhocGauge("gauge", 17, true)
+
+Manually
+
+Manually making readings of a meter directly to a Sink. (use this only if strictly needed)
+
+   gauge := metric.NewGauge("gauge")
+   gauge.Set(17)
+   gauge.FlushReading(sink)
+   sink.Flush()
+
+Managed
+
+Registring a buffered Meter object with a client. This is the fastest method.
+The low latency API is accessed via Client objects. (There's a default global client). The speed is achieved by creating permanent buffering metrics objects for each metric.
+
+   client := metric.NewClient(sink, metric.FlushInterval(time.Second))
+   gauge := client.RegisterGauge("gauge")
+   gauge.Set(17)
+
 
 The statsd sink also does client side buffering before sending UDP packages and is flushed when asked, or when running full. You can set the max size of the UDP datagrams created.
 */

metric/histotimer.go

@@ -21,7 +21,7 @@ func NewHistogram(name string) Histogram {
 	return Histogram{t}
 }
 
-// Sample record new event for the histogram
+// Sample records new event for the histogram
 func (e Histogram) Sample(d int64) {
 	//e := (*eventStream)(h)
 	e.enqueue(uint64(d))

metric/sink.go

@@ -2,13 +2,7 @@ package metric
 
 import "github.com/One-com/gone/metric/num64"
 
-// Sink is a sink for metrics data which methods are guaranteed to be called
-// synchronized. Thus it can keep state like buffers without locking
-// metric Client should Record*() to a Sink.
-// The idea is that the Sink in principle needs to be go-routine safe,
-// but Sink.Record*() will be called synchronized and only from one go-routine, so you can spare
-// the synchronization in the Record*() implementation it self if the Sink can
-// be called upon to Clone a new instance for each go-routine using the sink.
+// Sink is a sink for metrics data which methods need to be go-routine safe
 type Sink interface {
 	// Record a named value of any time with the Sink
 	Record(mtype int, name string, value interface{})
@@ -20,18 +14,18 @@ type Sink interface {
 	// not being able to guarantee the values can be stack allocated.
 	RecordNumeric64(mtype int, name string, value num64.Numeric64)
 
-	// Flush flushes the record values from Sink buffers.
+	// Flush flushes the record values from the program internal Sink buffers.
 	Flush()
 }
 
-// SinkFactory is the interface of objects returned to the user by sink implementations.
-// It serves to be able for gone/metric to create new Sink objects which can be called.
-// concurrently under external locking.
+// UnlockedSink implmentors can return a Sink which does not need to protect it self
+// against access from multiple go-routines.
+// This is used by flushing go-routines to save a lot of locking when flushing metric
+// event buffers to the Sink.
 // The returned Sink is guaranteed to only be called from one go-routine under a lock.
 // This allows a sink implementation to avoid using several layers of locks.
-// A sink implementation can chose not to exploit this and a simple SinkFactory can
+// A sink implementation can chose not to exploit this and not implement the interface or
 // just return it self as a Sink an do locking on all access.
-
 type unlockedSink interface {
 	UnlockedSink() Sink
 }

metric/sink_test.go

@@ -20,7 +20,7 @@ func TestReplaceNilSink(t *testing.T) {
 		t.Fatal(err)
 	}
 
-	gauge := metric.Default().RegisterGauge("gauge")
+	gauge := metric.RegisterGauge("gauge")
 
 	gauge.Set(23)
 	metric.Flush()
@@ -60,7 +60,7 @@ func TestFlushSink(t *testing.T) {
 	metric.SetDefaultSink(sink)
 	metric.SetDefaultOptions(metric.FlushInterval(500 * time.Millisecond))
 
-	gauge := metric.Default().RegisterGauge("auto")
+	gauge := metric.RegisterGauge("auto")
 
 	gauge.Set(25)