README
¶
graphite-client
Graphite client written in Go, focused in thread-safe and automatic aggregations.
Installation
Use go get or your favourite dependency manager to install it from github:
go get github.com/gguridi/graphite-client
Dependencies
This library doesn't have external dependencies by itself, only for testing purposes we need Gingko and Gomega.
Configuration
The different options to configure the client can be found here.
Protocols
Currently we support two protocols to connect with graphite.
- TCP: using the
NewGraphiteTCPconstructor. - UDP: using the
NewGraphiteUDPconstructor.
Simple client
We can initialise a simple client with one of the constructors:
import (
graphite "github.com/gguridi/graphite-client"
"fmt"
)
client := graphite.NewGraphiteTCP(graphite.Config{
Host: "example.com",
Port: 2003,
})
and then send one metric to graphite:
if _, err:= client.Send("metric.name.count", 55); err != nil {
fmt.Println("Unable to send metrics to graphite")
}
or if we don't mind if we could send or not the metric to graphite:
client.Send("metric.name.count", 55)
Aggregator
We can use an aggregator to send more than one metric at a time, for systems that collect a lot of data and we don't want to overload graphite with requests.
We can initialise an aggregator from any of the supported clients:
import (
graphite "github.com/gguridi/graphite-client"
"fmt"
)
aggregator := graphite.NewGraphiteTCP(graphite.Config{
Host: "example.com",
Port: 2003,
}).NewAggregator()
and then send several metric to graphite:
aggregator.AddSum("metric.received.count", 15)
aggregator.AddSum("metric.received.count", 10)
aggregator.AddSum("metric.sent.count", 5)
aggregator.Flush()
This will send two metrics at once, one for metric.received.count with a value of 25, and
another one for metric.sent.count with a value of 5.
Metric types
There are several kind of metrics built-in in the system, that can be automatically used
with the method of the Aggregator interface.
AddSum: Will initialise a metric where the final value sent to graphite will be the addition of all the values passed to the aggregator. So if we callAddSumwith a specific metric path and values 5, 10, 15 and then weFlush, we will be sending a final value of 30 to graphite.Increase: Used as an alias ofAddSumwhere the value incremented is always 1. Useful for giving a comprehensive behaviour to the metric.AddAverage: Will initialise a metric where the final value sent to graphite will be the average of all the values passed to the aggregator. So if we callAddAveragewith a specific metric path and values 2, 10, 10 and then weFlush, we will be sending a final value of 7.333333 to graphite. The maximum decimals allowed is 6.SetActive/SetInactive: Will initialise a metric where the final value sent to graphite will be 1 (SetActive) or 0 (SetInactive). This way we can send metrics such service status, etc.
Automatic flush
It's possible to configure the aggregator to periodically flush the values to graphite without having to worry about doing it manually. To make it possible we can initialise the aggregator with:
aggregator := graphite.NewGraphiteTCP(graphite.Config{
Host: "example.com",
Port: 2003,
}).NewAggregator().Run(30 * time.Second, nil)
The second parameter that method accepts is a chan bool that we can use to stop the loop whenever we want.
stop := make(chan bool)
aggregator := graphite.NewGraphiteTCP(graphite.Config{
Host: "example.com",
Port: 2003,
}).NewAggregator().Run(30 * time.Second, stop)
time.Sleep(600)
stop <- true
Documentation
¶
Index ¶
Constants ¶
const ( // ProtocolTCP is a constant to specify the protocol TCP ProtocolTCP = "tcp" // ProtocolUDP is a constant to specify the protocol UDP ProtocolUDP = "udp" )
const ( // DefaultTimeout specifies the default timeout to use when connecting to graphite. DefaultTimeout = 1 * time.Second )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Aggregator ¶
type Aggregator interface {
AddSum(string, interface{})
Increase(string)
AddAverage(string, interface{})
SetActive(string)
SetInactive(string)
Run(time.Duration, chan bool) Aggregator
Flush() (int, error)
Retry() (int, error)
}
Aggregator is an interface exposing the methods that we can use to work with different kinds of metrics in a transparent way for the user.
type Config ¶
type Config struct {
// Host is a string specifying the address where graphite is listening. It can be
// a host name "example.com" or an IP address "219.123.43.21". This field is required.
Host string
// Port is an integer specifying the port where graphite is listening. This field is required.
Port int
// Namespace specifies a prefix to use for all the metrics, so we don't need to set it
// every time we want to send something.
Namespace string
// Timeout specifies a new timeout in time.Duration format in case we want to increase/decrease
// the default one. Defaults to 1 second.
Timeout time.Duration
// ForceReconnect is a boolean specifying if we want to force a reconnection every time we send metrics
// to graphite. This is useful when working with AWS ELB or any other network components that might
// be tampering with the connections.
ForceReconnect bool
}
Config stores the configuration to pass to the graphite client.
type Graphite ¶
type Graphite interface {
Send(string, string) (int, error)
SendBuffer(*bytes.Buffer) (int, error)
NewAggregator() Aggregator
Connect() error
Reconnect() error
Disconnect() error
}
Graphite is an interface for a graphite client
func NewGraphiteTCP ¶
NewGraphiteTCP creates a new graphite client based on TCP.
func NewGraphiteUDP ¶
NewGraphiteUDP creates a new graphite client based on UDP.
type Metric ¶
type Metric interface {
// Update receives a generic value through interface{} to update its internal value.
Update(interface{})
// Clear is used to reset the metric to the initial value.
Clear()
// Calculate is used to perform the necessary operations to retrieve the final value
// that will be sent to graphite, standarised as a string.
Calculate() string
}
Metric is an interface to be able to create new metric types easily. Each metric must have some methods to be able to be used by the Aggregator.
type MetricActive ¶
type MetricActive struct {
State bool
}
MetricActive creates a metric to set a boolean status in graphite.
func (*MetricActive) Calculate ¶
func (metric *MetricActive) Calculate() string
Calculate calculates the value to send.
func (*MetricActive) Clear ¶
func (metric *MetricActive) Clear()
Clear reinitiales the value to inactive.
func (*MetricActive) Update ¶
func (metric *MetricActive) Update(value interface{})
Update sets the active/inactive status through a boolean.
type MetricAverage ¶
MetricAverage creates a metric to store the average value between several values.
func (*MetricAverage) Calculate ¶
func (metric *MetricAverage) Calculate() string
Calculate calculates the value to send.
func (*MetricAverage) Clear ¶
func (metric *MetricAverage) Clear()
Clear reinitiales the average value and counter.
func (*MetricAverage) Update ¶
func (metric *MetricAverage) Update(value interface{})
Update increases the components necessary to calculate afterwards the average value. Each time the metric is updated, the result of Calculate will change.
Source Files