graphigo

README

Graphigo

A simple go client for the graphite monitoring tool.

Features

• simple and clean API
• send a whole bunch of metrics and send them all with one TCP call
• supports timeouts
• supports prefixes
• sane defaults
• all client functions are automatically noops if the client is nil
• good test coverage and documentation
• stable API via gopkg.in

Installation

Use go get to install graphigo:

go get gopkg.in/fgrosse/graphigo.v2

No additional dependencies are required.

Usage

package main

import (
	"time"
	"gopkg.in/fgrosse/graphigo.v2"
)

func main() {
    c := graphigo.Client{
    	// If you omit the entire address localhost:2004 will be assumed
    	// Just omitting the port is also valid and wil use the default port
		Address: "graphite.your.org:2004",

		// set a custom timeout (seconds) for the graphite connection
		// if timeout = 0 then the graphigo.DefaultTimeout = 5 seconds is used
		// Setting Timeout to graphite.TimeoutDisabled (-1) disables the timeout
		Timeout: 42,

		// set a custom prefix for all recorded metrics of this client (optional)
		Prefix: "foo.bar.baz",
	}

	if err := c.Connect(); err != nil {
		panic(err) // do proper error handling
	}

	// close the TCP connection properly if you don't need it anymore
	defer c.Close()

	// capture and send values using a single line
	c.SendValue("hello.graphite.world", 42)

	// capture a metric and send it any time later. You can use any type as value
	// The next line could also be simplified with graphigo.CaptureMetric 
	metric := graphigo.Metric{Name: "test", Value: 3.14, Timestamp: time.Now()}
	defer c.Send(metric)

	// create a whole bunch of metrics and send them all with one TCP call
	c.SendAll([]graphigo.Metric{
		{Name: "shut", Value: 1},
		{Name: "up", Value: 2},
		{Name: "and", Value: 3},
		{Name: "take", Value: 4},
		{Name: "my", Value: 5},
		{Name: "money", Value: 6},
	})
}

Alternatives

• https://github.com/marpaia/graphite-golang
• https://github.com/ohlol/graphite-go

Contributing

Any contributions are always welcome (use pull requests). Please keep in mind that I might not always be able to respond immediately but I usually try to react within the week ☺.

Documentation

Overview

Package graphigo provides a simple go client for the graphite monitoring tool. See http://graphite.readthedocs.org/en/latest/overview.html

Example

c := graphigo.Client{
	// If you omit the entire address localhost:2004 will be assumed
	// Just omitting the port is also valid and wil use the default port
	Address: "graphite.your.org:2004",

	// set a custom timeout (seconds) for the graphite connection
	// if timeout = 0 then the graphigo.DefaultTimeout = 5 seconds is used
	// Setting Timeout to graphite.TimeoutDisabled (-1) disables the timeout
	Timeout: 42,

	// set a custom prefix for all recorded metrics of this client (optional)
	Prefix: "foo.bar.baz",
}

c.Connection = newConnectionMock()
if err := c.Connect(); err != nil {
	panic(err) // do proper error handling
}

// close the TCP connection properly if you don't need it anymore
defer c.Close()

// capture and send values using a single line
c.SendValue("hello.graphite.world", 42)

// capture a metric and send it any time later. You can use any type as value
// The next line could also be simplified with graphigo.CaptureMetric
metric := graphigo.Metric{Name: "test", Value: 3.14, Timestamp: time.Now()}
defer c.Send(metric)

// create a whole bunch of metrics and send them all with one TCP call
c.SendAll([]graphigo.Metric{
	{Name: "shut", Value: 1},
	{Name: "up", Value: 2},
	{Name: "and", Value: 3},
	{Name: "take", Value: 4},
	{Name: "my", Value: 5},
	{Name: "money", Value: 6},
})

Index

• Constants
• type Client
  • func (c *Client) Close() error
  • func (c *Client) Connect() (err error)
  • func (c *Client) Send(m Metric) error
  • func (c *Client) SendAll(metrics []Metric) (err error)
  • func (c *Client) SendValue(name string, value interface{}) error
• type Metric
  • func CaptureMetric(name string, value interface{}) Metric
  • func (m Metric) String() string
  • func (m Metric) UnixTimestamp() int64

Examples

• Package

Constants

const (
	// DefaultTimeout is the timeout that is applied when connecting to a graphite server.
	// It is used if no explicit timeout has been configured on a client.
	DefaultTimeout = 5

	// DefaultGraphitePort is the port a graphite server runs on by default.
	// This port is used if you don't supply any port in the Address of the client.
	DefaultGraphitePort = "2004"

	// TimeoutDisabled is used to disable the client timeout entirely.
	TimeoutDisabled = -1
)

Types

type Client

type Client struct {
	// Address is used when connecting to the graphite server. Use address:port notation.
	// If Address is empty then any call to Connect will try to connect to a local
	// graphite instance. If you just omit the :port part the DefaultGraphitePort
	// constant will be used instead.
	Address string

	// Timeout is the maximum duration that the client will wait for a response from the server.
	// If timeout is zero then the DefaultTimeout is used.
	// Setting Timeout to -1 disables the timeout.
	Timeout time.Duration

	// Prefix is prepended to all metric names (separated from original name by a dot).
	// If Prefix is empty this does nothing.
	Prefix string

	// Connection is used to communicate with the graphite client.
	// You would normally not interfere with this but this can be handy for testing.
	Connection io.WriteCloser
}

Client is a simple TCP client for the graphite monitoring tool.

func (*Client) Close

func (c *Client) Close() error

Close implements the io.Closer interface by closing the clients Connection. If c is nil this will do nothing (noop)

func (*Client) Connect

func (c *Client) Connect() (err error)

Connect attempts to establish the connection to the graphite server. This will return an error if a TCP connection can not or has already been established.

If c is nil this will do nothing (noop)

func (*Client) Send

func (c *Client) Send(m Metric) error

Send sends a graphigo.Metric to graphite. This can be used to send a metric which has been recorded earlier.

Use `SendValue` if you want to create and send a metric in one step. Use `SendAll` if you want to send multiple metrics at once. This will return an error if the client has not yet been connected or the metric name is empty.

If c is nil this will do nothing (noop)

func (*Client) SendAll

func (c *Client) SendAll(metrics []Metric) (err error)

SendAll sends multiple graphigo.Metric to graphite. This can be used to send multiple metrics that have been recorded earlier.

Use `Send` if you want to send a single metric. If the client has not yet been connected or if any of the metrics has an empty name this function will return an error.

If c is nil this will do nothing (noop)

func (*Client) SendValue

func (c *Client) SendValue(name string, value interface{}) error

SendValue creates a new graphigo.Metric with the metric timestamp set to now and sends it to graphite.

Use `Send(Metric)` if you want to split metric recording and sending. This will return an error if the client has not yet been connected or the metric name is empty.

If c is nil this will do nothing (noop)

type Metric

type Metric struct {
	// The Name of the metric.
	Name string

	// The Value of this metric. The client uses %v to format this.
	Value interface{}

	// Timestamp represents the time when this metric was recorded.
	// If this is the zero value the client will assume time.Now()
	Timestamp time.Time
}

Metric holds all information that is send to graphite. The value can be any go type but in practice graphite will probably only accept numeric values.

func CaptureMetric

func CaptureMetric(name string, value interface{}) Metric

CaptureMetric creates a new Metric with the Timestamp set to time.Now(). This is a handy utility function if you want to separate capturing metrics and sending them. to the graphite server.

If you want to capture a metric and immediately send it to graphite consider using Client.SendValue

func (Metric) String

func (m Metric) String() string

String returns a textual representation of a metric (used for debugging)

func (Metric) UnixTimestamp

func (m Metric) UnixTimestamp() int64

UnixTimestamp returns the the number of seconds elapsed since January 1, 1970 UTC. If the metrics timestamp is zero it will return time.Now().Unix()