rrdcached

README

Go (golang) Bindings for rrdcached

This package implements Go (golang) bindings for the rrdcached daemon.

Install

go get github.com/dreadpirateshawn/rrdcached

Requirements

rrdcached was developed against RRDCacheD 1.5.0-rc2 and expects CREATE support. Technically the pre-1.5 methods work with older libraries -- UPDATE, FLUSH, etc -- but the test suite leverages CREATE, so it's easiest to use out-of-the-box with the newer library.

RRDTool / RRDCacheD can be found here: https://github.com/oetiker/rrdtool-1.x

Basic RRDCacheD test

Unit tests

go test -v ./...

The go-rrdcached test suite starts and stops rrdcached daemon instances of its own, so you don't need to leave rrdcached running during development.

Integration tests

rrdcached -p /tmp/go-rrdached-test.pid -B -b /tmp -l /tmp/go-rrdcached-test.sock -l 0.0.0.0:50081
go test -v ./... -tags=integration

Manual validation

Verify socket connection using nc:

$ echo "STATS" | sudo nc -U /tmp/go-rrdcached-test.sock
9 Statistics follow
QueueLength: 0
UpdatesReceived: 0
... etc ...

Verify TCP connection using telnet:

$ telnet 0.0.0.0 50081
Trying 0.0.0.0...
Connected to 0.0.0.0.
Escape character is '^]'.
STATS
9 Statistics follow
QueueLength: 0
UpdatesReceived: 0
... etc ...
^]
telnet> quit
Connection closed.

Btw: Telnet doesn't work for unix:socket.

Troubleshooting

If you encounter permission problems accessing the socket from your Go program, here's what I've done to work around this. (TODO: Shouldn't this library be usable without doing this?)

• Change the default socket location. Add OPTS="-l unix:/socks/rrdcached.sock" to /etc/default/rrdcached
• Start the rrdcached daemon. sudo /etc/init.d/rrdcached start
• Ensure permissions. sudo chmod -R 777 /socks/
• View syslogs. tail /var/log/syslog

Open Questions

• RRD requires timestamp to increase by at least one second for each update value... does this library do enough to bubble up this error when it happens?

• What if filenames with spaces are used?

• What if Update is called with empty values? no-op or panic?

• Tests cover one RRD with multiple dimensions, should they also cover multiple RRDs with one dimension each? https://kb.op5.com/display/HOWTOs/Use+RRD+in+MULTIPLE+mode+for+separate+check+commands

Documentation

Index

• func NowString() string
• type BatchResponse
• type ConnectionError
  • func (f *ConnectionError) Error() string
• type FileDoesNotExistError
  • func (f *FileDoesNotExistError) Error() string
• type PanicError
  • func (f *PanicError) Error() string
• type RRDIO
• type Response
  • func (r *Response) Filename() (string, error)
  • func (r *Response) IsMissing() bool
• type Rrdcached
  • func ConnectToIP(ip string, port int64) (*Rrdcached, error)
  • func ConnectToSocket(socket string) (*Rrdcached, error)
  • func (r *Rrdcached) BatchFinalize() (*BatchResponse, error)
  • func (r *Rrdcached) BatchStart() (*Response, error)
  • func (r *Rrdcached) BatchUpdate(filename string, values ...string) (*Response, error)
  • func (r *Rrdcached) Create(filename string, start int64, step int64, overwrite bool, ds []string, ...) (*Response, error)
  • func (r *Rrdcached) CreateFromBatchResponses(batchResponse *BatchResponse, start int64, step int64, overwrite bool, ...) (*Response, error)
  • func (r *Rrdcached) First(filename string, rraIndex int) (*Response, error)
  • func (r *Rrdcached) Flush(filename string) (*Response, error)
  • func (r *Rrdcached) FlushAll() (*Response, error)
  • func (r *Rrdcached) Forget(filename string) (*Response, error)
  • func (r *Rrdcached) GetStats() (*Stats, error)
  • func (r *Rrdcached) Last(filename string) (*Response, error)
  • func (r *Rrdcached) Pending(filename string) (*Response, error)
  • func (r *Rrdcached) Quit()
  • func (r *Rrdcached) Update(filename string, values ...string) (*Response, error)
• type Stats
• type UnknownCommandError
  • func (f *UnknownCommandError) Error() string
• type UnrecognizedArgumentError
  • func (f *UnrecognizedArgumentError) BadArgument() string
  • func (f *UnrecognizedArgumentError) Error() string

Functions

func NowString

func NowString() string

Types

type BatchResponse

type BatchResponse struct {
	Responses []*Response
}

type ConnectionError

type ConnectionError struct {
	Err error
}

func (*ConnectionError) Error

func (f *ConnectionError) Error() string

type FileDoesNotExistError

type FileDoesNotExistError struct {
	Err error
}

func (*FileDoesNotExistError) Error

func (f *FileDoesNotExistError) Error() string

type PanicError

type PanicError struct {
	Err error
}

func (*PanicError) Error

func (f *PanicError) Error() string

type RRDIO

type RRDIO interface {
	ReadData(r io.Reader) (string, error)
	WriteData(conn net.Conn, data string) error
}

type Response

type Response struct {
	Status  int
	Message string
	Raw     string
	Error   error
}

func (*Response) Filename

func (r *Response) Filename() (string, error)

func (*Response) IsMissing

func (r *Response) IsMissing() bool

type Rrdcached

type Rrdcached struct {
	Protocol string
	Socket   string
	Ip       string
	Port     int64
	Batch    bool
	Conn     net.Conn
	Rrdio    RRDIO
}

func ConnectToIP

func ConnectToIP(ip string, port int64) (*Rrdcached, error)

func ConnectToSocket

func ConnectToSocket(socket string) (*Rrdcached, error)

func (*Rrdcached) BatchFinalize

func (r *Rrdcached) BatchFinalize() (*BatchResponse, error)

func (*Rrdcached) BatchStart

func (r *Rrdcached) BatchStart() (*Response, error)

func (*Rrdcached) BatchUpdate

func (r *Rrdcached) BatchUpdate(filename string, values ...string) (*Response, error)

func (*Rrdcached) Create

func (r *Rrdcached) Create(filename string, start int64, step int64, overwrite bool, ds []string, rra []string) (*Response, error)

func (*Rrdcached) CreateFromBatchResponses

func (r *Rrdcached) CreateFromBatchResponses(batchResponse *BatchResponse, start int64, step int64, overwrite bool, ds []string, rra []string) (*Response, error)

func (*Rrdcached) First

func (r *Rrdcached) First(filename string, rraIndex int) (*Response, error)

func (*Rrdcached) Flush

func (r *Rrdcached) Flush(filename string) (*Response, error)

func (*Rrdcached) FlushAll

func (r *Rrdcached) FlushAll() (*Response, error)

func (*Rrdcached) Forget

func (r *Rrdcached) Forget(filename string) (*Response, error)

func (*Rrdcached) GetStats

func (r *Rrdcached) GetStats() (*Stats, error)

func (*Rrdcached) Last

func (r *Rrdcached) Last(filename string) (*Response, error)

func (*Rrdcached) Pending

func (r *Rrdcached) Pending(filename string) (*Response, error)

func (*Rrdcached) Quit

func (r *Rrdcached) Quit()

func (*Rrdcached) Update

func (r *Rrdcached) Update(filename string, values ...string) (*Response, error)

type Stats

type Stats struct {
	QueueLength     uint64
	CreatesReceived uint64
	UpdatesReceived uint64
	FlushesReceived uint64
	UpdatesWritten  uint64
	DataSetsWritten uint64
	TreeNodesNumber uint64
	TreeDepth       uint64
	JournalBytes    uint64
	JournalRotate   uint64
}

type UnknownCommandError

type UnknownCommandError struct {
	Err error
}

func (*UnknownCommandError) Error

func (f *UnknownCommandError) Error() string

type UnrecognizedArgumentError

type UnrecognizedArgumentError struct {
	Err error
}

func (*UnrecognizedArgumentError) BadArgument

func (f *UnrecognizedArgumentError) BadArgument() string

func (*UnrecognizedArgumentError) Error

func (f *UnrecognizedArgumentError) Error() string