add more comments and fix for a counter

metrics/librato/librato.go

@@ -46,6 +46,7 @@ type Librato struct {
  sums *lv.Space
  percentiles []float64 // percentiles to track
  logger log.Logger
+ debug bool
  numConcurrentRequests int
  maxBatchSize int
 }
@@ -87,7 +88,7 @@ type Metric struct {
  MeasureTime *int64 `json:"measure_time,omitempty"`
  Name string `json:"name"`
  Value *float64 `json:"value,omitempty"`
- Source *string `json:"string,omitempty"`
+ Source *string `json:"source,omitempty"`
 }
 
 type Option func(*Librato)
@@ -148,6 +149,13 @@ func WithHttpClient(c *http.Client) Option {
  }
 }
 
+// WithDebug enables debug logging
+func WithDebug() Option {
+ return func(lb *Librato) {
+ lb.debug = true
+ }
+}
+
 // New returns a Librato object that may be used to create metrics.
 // Callers must ensure that regular calls to Send are performed, either
 // manually or with one of the helper methods.
@@ -165,6 +173,7 @@ func New(user, token string, options ...Option) *Librato {
  percentiles: []float64{0.50, 0.90, 0.95, 0.99},
  numConcurrentRequests: maxConcurrentRequests,
  maxBatchSize: maxValuesInABatch,
+ debug: false,
  }
 
  for _, optFunc := range options {
@@ -176,8 +185,8 @@ func New(user, token string, options ...Option) *Librato {
  return lb
 }
 
-// NewCounter returns a counter. Observations are aggregated and emitted once
-// per write invocation.
+// NewCounter returns a counter. Observations are aggregated and only last value emitted once
+// per write invocation. See http://kb-docs-archive.librato.com/faq/glossary/whats_a_counter/
 func (lb *Librato) NewCounter(name string) metrics.Counter {
  return &Counter{
  name: name,
@@ -186,7 +195,10 @@ func (lb *Librato) NewCounter(name string) metrics.Counter {
 }
 
 // NewGauge returns an gauge, which will calculate count, sum, min, max
-// of observed data before sending it to librato
+// of observed data before sending it to librato.
+// Based on count/sum librato will calculate average value
+// this can be used to report average request payload size, etc.
+// See: http://kb-docs-archive.librato.com/faq/glossary/whats_a_gauge/
 func (lb *Librato) NewGauge(name string) metrics.Gauge {
  return &Gauge{
  name: name,
@@ -196,7 +208,11 @@ func (lb *Librato) NewGauge(name string) metrics.Gauge {
 }
 
 // NewSumGauge returns Gauge which will calculate sum of submitted values
-// before sending them to librato
+// before sending them to librato.
+// This can be used to monitor requests count, for example.
+// Every request will increment add 1 to the gauge value
+// and sum of all values will be reported to librato
+// See: http://kb-docs-archive.librato.com/faq/glossary/whats_a_gauge/
 func (lb *Librato) NewSumGauge(name string) metrics.Gauge {
  return &Gauge{
  name: name,
@@ -265,9 +281,13 @@ func (lb *Librato) Send() error {
  }
 
  lb.counters.Reset().Walk(func(name string, lvs lv.LabelValues, values []float64) bool {
- sum := sum(values)
+ // for counter we need take latest value because
+ // If you POST metrics as a counter, Librato will plot the derivative, i.e.
+ // the delta of values that monotonically increase over time
+ // http://kb-docs-archive.librato.com/faq/glossary/whats_a_counter/
+ val := last(values)
  add(CounterPayload{
- Value: &sum,
+ Value: &val,
  Name: name,
  Source: getSourceFromLabels(lvs),
  })
@@ -388,6 +408,10 @@ func (lb *Librato) postMetric(body *RequestPayload) error {
 }
 
 func (lb *Librato) makeRequest(data *bytes.Buffer, url string) error {
+ if lb.debug {
+ lb.logger.Log("during", "Send", "body", data)
+ }
+
  req, err := http.NewRequest(http.MethodPost, url, data)
  if nil != err {
  return err