librato

README

go-librato

This is both a Go client to the Librato Metrics API and a command-line tool for piping data into the client.

Usage

From Go:

m := librato.NewSimpleMetrics(user, token, source)
defer m.Wait()
defer m.Close()

c := m.GetCounter("foo")
c <- 47

g := m.GetGauge("bar")
g <- 47

cc := m.GetCustomCounter("baz")
cc <- map[string]int64 {
	"value": 47,
	"measure_time": 1234567890,
}

cg := m.GetCustomGauge("bang")
cg <- map[string]int64 {
	"value": 47,
	"measure_time": 1234567890,
}
cg <- map[string]int64 {
	"measure_time": 1234567890,
	"count": 2,
	"sum": 94,
	"max": 47,
	"min": 47,
	"sum_squares": 4418,
}

Alternatively you can use the collated mode so data will be sent when enough measurements are available:

collate_max := 3
m := librato.NewCollatedMetrics(user, token, source, collate_max)
c := m.GetCounter("foo")
g := m.GetGauge("bar")
c <- 1
c <- 2
c <- 3 // send here ...
g <- 10
g <- 20
g <- 30 // send here ...

As above, custom metrics are also available.

You can also use the command line tool to send your data:

thing | librato -u "rcrowley" -t "ZOMG" -s "$(hostname)"

export LIBRATO_USER="rcrowley"
export LIBRATO_TOKEN="ZOMG"
export LIBRATO_SOURCE="$(hostname)"
tail -F /var/log/thing | librato -c 100

The librato tool accepts one metric per line. The first field is either a c or a g to indicate that the metric is a counter or a gauge. The second field is the name of the metric, which may not contain spaces. The remaining fields may either be numeric or - but must provide a combination of non-- values acceptable to the Librato Metrics API.

Regular expressions:

# Value-only counters and gauges.
^([cg]) ([^ ]+) ([0-9]+)$

# Custom counters with a value and optionally a timestamp.
^(c) ([^ ]+) ([0-9]+) (-|[0-9]+)$

# Custom gauges with a value, timestamp, count, sum, max, min, and sum-of-squares (or some combination thereof).
^(g) ([^ ]+) (-|[0-9]+) (-|[0-9]+) (-|[0-9]+) (-|[0-9]+) (-|[0-9]+) (-|[0-9]+) (-|[0-9]+)$

Examples:

c foo 47
g bar 47
c baz 47 1234567890
g bang 47 1234567890 - - - - -
g bang - 1234567890 2 94 47 47 4418

Installation

Installation requires a working Go build environment. See their Getting Started guide if you don't already have one.

As a library:

go get github.com/rcrowley/go-librato

The librato.a library will by in $GOROOT/pkg/${GOOS}_${GOARCH}/github.com/rcrowley/go-librato should be linkable without further configuration.

As a command-line tool:

git clone git://github.com/rcrowley/go-librato.git
cd go-librato/cmd/librato
go install

The librato tool will be in $GOBIN.

Documentation

Overview

Go client for Librato Metrics

<https://github.com/rcrowley/go-librato>

Index

• Constants
• type CollatedMetrics
  • func (m *CollatedMetrics) Close()
  • func (m *CollatedMetrics) GetCounter(name string) chan int64
  • func (m *CollatedMetrics) GetCustomCounter(name string) chan map[string]int64
  • func (m *CollatedMetrics) GetCustomGauge(name string) chan map[string]int64
  • func (m *CollatedMetrics) GetGauge(name string) chan int64
  • func (m *CollatedMetrics) NewCounter(name string) chan int64
  • func (m *CollatedMetrics) NewCustomCounter(name string) chan map[string]int64
  • func (m *CollatedMetrics) NewCustomGauge(name string) chan map[string]int64
  • func (m *CollatedMetrics) NewGauge(name string) chan int64
  • func (m *CollatedMetrics) SetTransport(transport http.RoundTripper)
  • func (m *CollatedMetrics) Wait()
• type Metrics
  • func NewCollatedMetrics(user, token, source string, collateMax int) Metrics
  • func NewMetrics(user, token, source string) Metrics
  • func NewSimpleMetrics(user, token, source string) Metrics
• type SimpleMetrics
  • func (m *SimpleMetrics) Close()
  • func (m *SimpleMetrics) GetCounter(name string) chan int64
  • func (m *SimpleMetrics) GetCustomCounter(name string) chan map[string]int64
  • func (m *SimpleMetrics) GetCustomGauge(name string) chan map[string]int64
  • func (m *SimpleMetrics) GetGauge(name string) chan int64
  • func (m *SimpleMetrics) NewCounter(name string) chan int64
  • func (m *SimpleMetrics) NewCustomCounter(name string) chan map[string]int64
  • func (m *SimpleMetrics) NewCustomGauge(name string) chan map[string]int64
  • func (m *SimpleMetrics) NewGauge(name string) chan int64
  • func (m *SimpleMetrics) SetTransport(transport http.RoundTripper)
  • func (m *SimpleMetrics) Wait()

Constants

const Version = "0.1"

Set the UserAgent string

Types

type CollatedMetrics

type CollatedMetrics struct {
	// contains filtered or unexported fields
}

Librato `CollatedMetrics` structs encapsulate the credentials used to send metrics to the API, the source tag for these metrics, the maximum number of metrics to collate, bookkeeping for goroutines, and lookup tables for existing metric channels.

func (*CollatedMetrics) Close

func (m *CollatedMetrics) Close()

Close all metric channels so no new messages may be sent. This is a prerequisite to `Wait`ing.

func (*CollatedMetrics) GetCounter

func (m *CollatedMetrics) GetCounter(name string) chan int64

Get (possibly by creating) a counter channel by the given name.

func (*CollatedMetrics) GetCustomCounter

func (m *CollatedMetrics) GetCustomCounter(name string) chan map[string]int64

Get (possibly by creating) a custom counter channel by the given name.

func (*CollatedMetrics) GetCustomGauge

func (m *CollatedMetrics) GetCustomGauge(name string) chan map[string]int64

Get (possibly by creating) a custom gauge channel by the given name.

func (*CollatedMetrics) GetGauge

func (m *CollatedMetrics) GetGauge(name string) chan int64

Get (possibly by creating) a gauge channel by the given name.

func (*CollatedMetrics) NewCounter

func (m *CollatedMetrics) NewCounter(name string) chan int64

Create a counter channel by the given name.

func (*CollatedMetrics) NewCustomCounter

func (m *CollatedMetrics) NewCustomCounter(name string) chan map[string]int64

Create a custom counter channel by the given name.

func (*CollatedMetrics) NewCustomGauge

func (m *CollatedMetrics) NewCustomGauge(name string) chan map[string]int64

Create a custom gauge channel by the given name.

func (*CollatedMetrics) NewGauge

func (m *CollatedMetrics) NewGauge(name string) chan int64

Create a gauge channel by the given name.

func (*CollatedMetrics) SetTransport

func (m *CollatedMetrics) SetTransport(transport http.RoundTripper)

SetTransport lets us use a custom Roundtripper Useful in-case some other part of the program overrides http.DefaultClient / http.DefaultTransport

func (*CollatedMetrics) Wait

func (m *CollatedMetrics) Wait()

Wait for all outstanding HTTP requests to finish. This must be called after `Close` has been called.

type Metrics

type Metrics interface {
	Close()
	GetCounter(name string) chan int64
	GetCustomCounter(name string) chan map[string]int64
	GetCustomGauge(name string) chan map[string]int64
	GetGauge(name string) chan int64
	NewCounter(name string) chan int64
	NewCustomCounter(name string) chan map[string]int64
	NewCustomGauge(name string) chan map[string]int64
	NewGauge(name string) chan int64
	Wait()
}

func NewCollatedMetrics

func NewCollatedMetrics(user, token, source string,
	collateMax int) Metrics

Create a new `CollatedMetrics` struct with the given credentials, source tag, and maximum collation. Initialize all the channels, maps, and goroutines used internally.

func NewMetrics

func NewMetrics(user, token, source string) Metrics

func NewSimpleMetrics

func NewSimpleMetrics(user, token, source string) Metrics

Create a new `SimpleMetrics` struct with the given credentials and source tag. Initialize all the channels, maps, and goroutines used internally.

type SimpleMetrics

type SimpleMetrics struct {
	// contains filtered or unexported fields
}

Librato `SimpleMetrics` structs encapsulate the credentials used to send metrics to the API, the source tag for these metrics, bookkeeping for goroutines, and lookup tables for existing metric channels.

func (*SimpleMetrics) Close

func (m *SimpleMetrics) Close()

Close all metric channels so no new messages may be sent. This is a prerequisite to `Wait`ing.

func (*SimpleMetrics) GetCounter

func (m *SimpleMetrics) GetCounter(name string) chan int64

Get (possibly by creating) a counter channel by the given name.

func (*SimpleMetrics) GetCustomCounter

func (m *SimpleMetrics) GetCustomCounter(name string) chan map[string]int64

Get (possibly by creating) a custom counter channel by the given name.

func (*SimpleMetrics) GetCustomGauge

func (m *SimpleMetrics) GetCustomGauge(name string) chan map[string]int64

Get (possibly by creating) a custom gauge channel by the given name.

func (*SimpleMetrics) GetGauge

func (m *SimpleMetrics) GetGauge(name string) chan int64

Get (possibly by creating) a gauge channel by the given name.

func (*SimpleMetrics) NewCounter

func (m *SimpleMetrics) NewCounter(name string) chan int64

Create a counter channel by the given name.

func (*SimpleMetrics) NewCustomCounter

func (m *SimpleMetrics) NewCustomCounter(name string) chan map[string]int64

Create a custom counter channel by the given name.

func (*SimpleMetrics) NewCustomGauge

func (m *SimpleMetrics) NewCustomGauge(name string) chan map[string]int64

Create a custom gauge channel by the given name.

func (*SimpleMetrics) NewGauge

func (m *SimpleMetrics) NewGauge(name string) chan int64

Create a gauge channel by the given name.

func (*SimpleMetrics) SetTransport

func (m *SimpleMetrics) SetTransport(transport http.RoundTripper)

SetTransport lets us use a custom Roundtripper Useful in-case some other part of the program overrides http.DefaultClient / http.DefaultTransport

func (*SimpleMetrics) Wait

func (m *SimpleMetrics) Wait()

Wait for all outstanding HTTP requests to finish. This must be called after `Close` has been called.