More Go doc for metric

Author: Peter Mogensen

metric/client.go

@@ -5,6 +5,9 @@ import (
 	"time"
 )
 
+// Client is the main object the applications holds to do metrics.
+// It can be used directly for ad-hoc events, or be used to create persistent
+// gauge/conter/timer/... objects optimised for bulk metric generation.
 type Client struct {
 
 	// Wait for all flushers to empty before exiting Stop()
@@ -32,7 +35,7 @@ func init() {
 
 // NewClient returns you a client handle directly if you do not want to use the
 // global default client.
-// Create a new metric client with a factory object for the sink.
+// Creates a new metric client with a factory object for the sink.
 // If sink == nil, the client will not emit metrics until a Sink is set.
 func NewClient(sinkf SinkFactory, opts ...MOption) (client *Client) {
 
@@ -51,13 +54,13 @@ func NewClient(sinkf SinkFactory, opts ...MOption) (client *Client) {
 	return
 }
 
-// Set options on the default metric client
+// SetDefaultOptions sets options on the default metric client
 func SetDefaultOptions(opts ...MOption) {
 	c := defaultClient
 	c.SetOptions(opts...)
 }
 
-// Set options on a client - like the flush interval for metrics which
+// SetOptions sets options on a client - like the flush interval for metrics which
 // haven't them selves a fixed flush interval
 func (c *Client) SetOptions(opts ...MOption) {
 	conf := make(map[string]interface{})
@@ -74,12 +77,14 @@ func (c *Client) SetOptions(opts ...MOption) {
 	c.fmu.Unlock()
 }
 
+// SetDefaultSink sets the sink for the default metics client
 func SetDefaultSink(sinkf SinkFactory) {
 	c := defaultClient
 	c.SetSink(sinkf)
 }
 
-// The the Sink factory of the client
+// SetSink sets the Sink factory of the client.
+// You'll need to set a sink before any metrics will be emitted.
 func (c *Client) SetSink(sinkf SinkFactory) {
 	c.fmu.Lock()
 
@@ -119,7 +124,7 @@ func (c *Client) Start() {
 	c.running = true
 }
 
-// Stops the global default metrics client
+// Stop the global default metrics client
 func Stop() {
 	defaultClient.Stop()
 }
@@ -182,19 +187,27 @@ func (c *Client) Flush() {
 	c.defaultFlusher.FlushSink()
 }
 
+// Counter creates an ad-hoc counter metric event.
+// If flush is true, the sink will be instructed to flush data immediately
 func (c *Client) Counter(name string, val int, flush bool) {
 	c.defaultFlusher.RecordNumeric64(MeterCounter, name, Numeric64{Type: Int64, value: uint64(val)}, flush)
 }
 
+// Gauge creates an ad-hoc gauge metric event.
+// If flush is true, the sink will be instructed to flush data immediately
 func (c *Client) Gauge(name string, val uint64, flush bool) {
 	c.defaultFlusher.RecordNumeric64(MeterGauge, name, Numeric64{Type: Uint64, value: uint64(val)}, flush)
 }
 
+// Timer creates an ad-hoc timer metric event.
+// If flush is true, the sink will be instructed to flush data immediately
 func (c *Client) Timer(name string, d time.Duration, flush bool) {
 	val := d.Nanoseconds()/int64(1000000)
 	c.defaultFlusher.RecordNumeric64(MeterTimer, name, Numeric64{Type: Uint64, value: uint64(val)}, flush)
 }
 
+// Sample creates an ad-hoc histogram metric event.
+// If flush is true, the sink will be instructed to flush data immediately
 func (c *Client) Sample(name string, val int64, flush bool) {
 	c.defaultFlusher.RecordNumeric64(MeterHistogram, name, Numeric64{Type: Int64, value: uint64(val)}, flush)
 }

metric/gauge.go

@@ -9,19 +9,19 @@ import (
 // wrt. the absolute value.
 // Can be used as a client side maintained counter too.
 
-// The default gauge type using a uint64
+// GaugeUint64 is the default gauge type using a uint64
 type GaugeUint64 struct {
 	name string
 	val  uint64
 }
 
-// A gauge using an int64 - meaning it can be decremented to negaive values
+// GaugeInt64 is a gauge using an int64 - meaning it can be decremented to negaive values
 type GaugeInt64 struct {
 	name string
 	val  int64
 }
 
-// A go-metric compatible float64 gauge which stores its value as a uint64
+// GaugeFloat64 is a float64 gauge which stores its value as a uint64
 // to implement Flush() fast
 type GaugeFloat64 struct {
 	name string
@@ -59,17 +59,17 @@ func (g *GaugeUint64) Name() string {
 	return g.name
 }
 
-// Mtype to implement Meter interface
+// MeterType to implement Meter interface
 func (g *GaugeUint64) MeterType() int {
 	return MeterGauge
 }
 
-// Update the gauge value
+// Set will update the gauge value
 func (g *GaugeUint64) Set(val uint64) {
 	atomic.StoreUint64(&g.val, val)
 }
 
-// Get the gauge value
+// Value returns the gauge value
 func (g *GaugeUint64) Value() uint64 {
 	return atomic.LoadUint64(&g.val)
 }

metric/sink.go

@@ -13,6 +13,10 @@ type Sink interface {
 	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.
+// This allows a sink implementation to avoid using several layers of locks.
 type SinkFactory interface {
 	Sink() Sink
 }

metric/sink/statsd/statsd.go

@@ -25,20 +25,24 @@ type statsdSink struct {
 	buf []byte
 }
 
+// Buffer sets the package size with which writes to the underlying io.Writer (often an UDPConn)
+// is done.
 func Buffer(size int) Option {
 	return Option(func(s *statsdSinkFactory) error {
 		s.max = size
 		return nil
 	})
 }
 
+// Prefix is prepended with "prefix." to all metric names
 func Prefix(pfx string) Option {
 	return Option(func(s *statsdSinkFactory) error {
 		s.prefix = pfx + "."
 		return nil
 	})
 }
 
+// Peer is the address of the statsd UDP server
 func Peer(addr string) Option {
 	return Option(func(s *statsdSinkFactory) error {
 		conn, err := net.DialTimeout("udp", addr, time.Second)
@@ -49,15 +53,16 @@ func Peer(addr string) Option {
 		return nil
 	})
 }
-	
+
+// Output sets an general io.Writer as output instead of a UDPConn.
 func Output(w io.Writer) Option {
 	return Option(func(s *statsdSinkFactory) error {
 		s.out = w
 		return nil
 	})
 }
 
-// A Sink sending data to a UDP statsd server
+// New creasted a SinkFactory which is used to create Sinks sending data to a UDP statsd server
 // Provide a UDP address, a prefix and a maximum UDP datagram size.
 // 1432 should be a safe size for most nets.
 func New(opts ...Option) (sink *statsdSinkFactory, err error) {
@@ -73,6 +78,7 @@ func New(opts ...Option) (sink *statsdSinkFactory, err error) {
 	return
 }
 
+// Sink implmenets the SinkFactory interface.
 func (s *statsdSinkFactory) Sink() (metric.Sink) {
 	newsink := &statsdSink{out: s.out, max: s.max, prefix: s.prefix}
 	newsink.buf = make([]byte,0,512)