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
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 ¶
Examples ¶
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 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
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 ¶
Close implements the io.Closer interface by closing the clients Connection. If c is nil this will do nothing (noop)
func (*Client) Connect ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) UnixTimestamp ¶
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()
Source Files