graphite

README

graphite-golang

This is a lightweight Graphite API client written in Go that implements Carbon submission functionality. I wrote this a long time ago as a dependency for a side project a long time ago. You shouldn't rely on this for any production use-case.

Installation

Use go-get to install graphite-golang

go get github.com/marpaia/graphite-golang

External dependencies

This project has no external dependencies other than the Go standard library.

Documentation

Like most every other Golang project, this projects documentation can be found on godoc at godoc.org/github.com/marpaia/graphite-golang.

Examples

package mylib

import (
    "github.com/marpaia/graphite-golang"
    "log"
)

func init() {

    // load your configuration file / mechanism
    config := newConfig()

    // try to connect a graphite server
    if config.GraphiteEnabled {
        Graphite, err = graphite.NewGraphite(config.Graphite.Host, config.Graphite.Port)
    } else {
        Graphite = graphite.NewGraphiteNop(config.Graphite.Host, config.Graphite.Port)
    }
    // if you couldn't connect to graphite, use a nop
    if err != nil {
        Graphite = graphite.NewGraphiteNop(config.Graphite.Host, config.Graphite.Port)
    }

    log.Printf("Loaded Graphite connection: %#v", Graphite)
    Graphite.SimpleSend("stats.graphite_loaded", "1")
}

func doWork() {
    // this will work just fine, regardless of if you're working with a graphite
    // nop or not
    Graphite.SimpleSend("stats.doing_work", "1")
}

Documentation

Overview

Example of using the graphiteNop feature in action:

package mylib

import (
    "github.com/marpaia/graphite-golang"
    "log"
)

func init() {

    // load your configuration file / mechanism
    config := newConfig()

    // try to connect a graphite server
    if config.GraphiteEnabled {
        Graphite, err = graphite.NewGraphite(config.Graphite.Host, config.Graphite.Port)
    } else {
        Graphite = graphite.NewGraphiteNop(config.Graphite.Host, config.Graphite.Port)
    }
    // if you couldn't connect to graphite, use a nop
    if err != nil {
        Graphite = graphite.NewGraphiteNop(config.Graphite.Host, config.Graphite.Port)
    }

    log.Printf("Loaded Graphite connection: %#v", Graphite)
    Graphite.SimpleSend("stats.graphite_loaded", 1)
}

func doWork() {
    // this will work just fine, regardless of if you're working with a graphite
    // nop or not
    Graphite.SimpleSend("stats.doing_work", 1)
}

Index

• type Graphite
  • func GraphiteFactory(protocol string, host string, port int, prefix string) (*Graphite, error)
  • func NewGraphite(host string, port int) (*Graphite, error)
  • func NewGraphiteNop(host string, port int) *Graphite
  • func NewGraphiteUDP(host string, port int) (*Graphite, error)
  • func NewGraphiteWithMetricPrefix(host string, port int, prefix string) (*Graphite, error)
  • func (graphite *Graphite) Connect() error
  • func (graphite *Graphite) Disconnect() error
  • func (graphite *Graphite) IsNop() bool
  • func (graphite *Graphite) SendMetric(metric Metric) error
  • func (graphite *Graphite) SendMetrics(metrics []Metric) error
  • func (graphite *Graphite) SimpleSend(stat string, value string) error
• type Metric
  • func NewMetric(name, value string, timestamp int64) Metric
  • func (metric Metric) String() string

Types

type Graphite

type Graphite struct {
	Host     string
	Port     int
	Protocol string
	Timeout  time.Duration
	Prefix   string

	DisableLog bool
	// contains filtered or unexported fields
}

Graphite is a struct that defines the relevant properties of a graphite connection

func GraphiteFactory

func GraphiteFactory(protocol string, host string, port int, prefix string) (*Graphite, error)

func NewGraphite

func NewGraphite(host string, port int) (*Graphite, error)

NewGraphite is a factory method that's used to create a new Graphite

func NewGraphiteNop

func NewGraphiteNop(host string, port int) *Graphite

NewGraphiteNop is a factory method that returns a Graphite struct but will not actually try to send any packets to a remote host and, instead, will just log. This is useful if you want to use Graphite in a project but don't want to make Graphite a requirement for the project.

func NewGraphiteUDP

func NewGraphiteUDP(host string, port int) (*Graphite, error)

When a UDP connection to Graphite is required

func NewGraphiteWithMetricPrefix

func NewGraphiteWithMetricPrefix(host string, port int, prefix string) (*Graphite, error)

NewGraphiteWithMetricPrefix is a factory method that's used to create a new Graphite with a metric prefix

func (*Graphite) Connect

func (graphite *Graphite) Connect() error

Given a Graphite struct, Connect populates the Graphite.conn field with an appropriate TCP connection

func (*Graphite) Disconnect

func (graphite *Graphite) Disconnect() error

Given a Graphite struct, Disconnect closes the Graphite.conn field

func (*Graphite) IsNop

func (graphite *Graphite) IsNop() bool

IsNop is a getter for *graphite.Graphite.nop

func (*Graphite) SendMetric

func (graphite *Graphite) SendMetric(metric Metric) error

Given a Metric struct, the SendMetric method sends the supplied metric to the Graphite connection that the method is called upon

func (*Graphite) SendMetrics

func (graphite *Graphite) SendMetrics(metrics []Metric) error

Given a slice of Metrics, the SendMetrics method sends the metrics, as a batch, to the Graphite connection that the method is called upon

func (*Graphite) SimpleSend

func (graphite *Graphite) SimpleSend(stat string, value string) error

The SimpleSend method can be used to just pass a metric name and value and have it be sent to the Graphite host with the current timestamp

type Metric

type Metric struct {
	Name      string
	Value     string
	Timestamp int64
}

Metric is a struct that defines the relevant properties of a graphite metric

func NewMetric

func NewMetric(name, value string, timestamp int64) Metric

func (Metric) String

func (metric Metric) String() string