cdclient

package module
v0.0.0-...-1c2500b Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2021 License: ISC Imports: 19 Imported by: 2

README

go-cdclient

godocs.io

A fast, dependency free implementation of the collectd binary network protocol and the collectd exec plugin format.

How fast?

This package can form an encrypted metric packet in less than 1 microsecond, and we can then publish it with a single syscall.

This package has also been optimized such that there are no memory allocations in any of the public facing apis when used in a loop, so adds negligible garbage collection overhead to your program.

Benchmark

go-fast-collectd

BenchmarkFormatEncryptedUdpPacket-32   1343607   904.0 ns/op   0 B/op   0 allocs/op

Compared to the official collectd go library:

BenchmarkFormatEncryptedUdpPacket-32   244285   4643 ns/op   1736 B/op   37 allocs/op

We have more than a 4x speedup at writing encrypted metrics at the time of writing.

benchmark source

Example

See the example directory for basic usage.

For a higher level library wrapping cdclient see cdmetrics

Documentation

Overview

A fast package for sending metrics to collectd.

Index

Constants

View Source
const (
	COUNTER  = 0
	GAUGE    = 1
	DERIVE   = 2
	ABSOLUTE = 3
)
View Source
const DefaultBufferSize = 1452

DefaultBufferSize is the default size of "Buffer". This is based on the maximum bytes that fit into an Ethernet frame without fragmentation:

<Ethernet frame> - (<IPv6 header> + <UDP header>) = 1500 - (40 + 8) = 1452
View Source
const MinimumBufferSize = 256

Variables

View Source
var ErrPacketFull = errors.New("not enough space")

Functions

This section is empty.

Types

type AuthFile

type AuthFile struct {
	// contains filtered or unexported fields
}

AuthFile implements the collectd password file format.. The file has a very simple syntax with one username / password mapping per line, separated by a colon. For example:

alice: w0nderl4nd
bob:   bu1|der

func NewAuthFile

func NewAuthFile(path string) (*AuthFile, error)

NewAuthFile initializes and returns a new AuthFile. A valid (but empty) authfile is still returned even if there is an error.

func (*AuthFile) Password

func (a *AuthFile) Password(user string) (string, bool)

Password looks up a user in the file and returns the associated password.

func (*AuthFile) Refresh

func (a *AuthFile) Refresh() (bool, error)

Reload the auth file, returns (true, nil) when there was no error.

type DSType

type DSType byte

type EncryptedPacket

type EncryptedPacket struct {
	PlainTextPacket
	// contains filtered or unexported fields
}

func NewEncryptedPacket

func NewEncryptedPacket(username, password string) (*EncryptedPacket, error)

func NewEncryptedPacketSize

func NewEncryptedPacketSize(username, password string, size int) (*EncryptedPacket, error)

func (*EncryptedPacket) Finalize

func (b *EncryptedPacket) Finalize() []byte

type ExecFormatter

type ExecFormatter struct {
	NoInterval bool
	// contains filtered or unexported fields
}

func (*ExecFormatter) AddValueList

func (ef *ExecFormatter) AddValueList(vl ValueList) error

func (*ExecFormatter) AddValues

func (ef *ExecFormatter) AddValues(m *Metric, t time.Time, values ...float64) error

func (*ExecFormatter) Finalize

func (ef *ExecFormatter) Finalize() []byte

func (*ExecFormatter) Reset

func (ef *ExecFormatter) Reset()

type Metric

type Metric struct {
	Host           string
	Plugin         string
	PluginInstance string
	Type           string
	TypeInstance   string
	DSTypes        []DSType
	Interval       time.Duration
}

func (*Metric) Validate

func (m *Metric) Validate() error

type MetricSink

type MetricSink interface {
	AddValues(*Metric, time.Time, ...float64) error
	AddValueList(ValueList) error
}

type Packet

type Packet interface {
	MetricSink
	Finalize() []byte
	Reset()
}

type PlainTextPacket

type PlainTextPacket struct {
	// contains filtered or unexported fields
}

func NewPlainTextPacket

func NewPlainTextPacket() *PlainTextPacket

func NewPlainTextPacketSize

func NewPlainTextPacketSize(size int) *PlainTextPacket

NewBuffer initializes a new metric buffer, panics if the size is smaller than MinimumBufferSize.

func (*PlainTextPacket) AddValueList

func (b *PlainTextPacket) AddValueList(v ValueList) error

func (*PlainTextPacket) AddValues

func (b *PlainTextPacket) AddValues(m *Metric, t time.Time, values ...float64) error

func (*PlainTextPacket) Finalize

func (b *PlainTextPacket) Finalize() []byte

func (*PlainTextPacket) Reset

func (b *PlainTextPacket) Reset()

type SignedPacket

type SignedPacket struct {
	PlainTextPacket
	// contains filtered or unexported fields
}

func NewSignedPacket

func NewSignedPacket(username, password string) (*SignedPacket, error)

func NewSignedPacketSize

func NewSignedPacketSize(username, password string, size int) (*SignedPacket, error)

func (*SignedPacket) Finalize

func (b *SignedPacket) Finalize() []byte

type UDPClient

type UDPClient struct {
	// contains filtered or unexported fields
}

A udp client that buffers metrics to write complete udp packets. The client is safe to use from multiple goroutines concurrently.

func DialUDP

func DialUDP(address string, opts UDPClientOptions) (*UDPClient, error)

Dial connects to the collectd server at address. "address" must be a network address accepted by net.Dial().

func (*UDPClient) AddValueList

func (c *UDPClient) AddValueList(v ValueList) error

func (*UDPClient) AddValues

func (c *UDPClient) AddValues(m *Metric, t time.Time, values ...float64) error

func (*UDPClient) Close

func (c *UDPClient) Close() error

func (*UDPClient) Flush

func (c *UDPClient) Flush() error

func (*UDPClient) Reconnect

func (c *UDPClient) Reconnect(address string, opts UDPClientOptions) error

type UDPClientOptions

type UDPClientOptions struct {
	// Mode determines whether data is signed, encrypted or sent
	// in plain text. When zero no encryption is used.
	Mode UDPMode
	// Username and password for the "Sign" and "Encrypt" modes.
	Username, Password string
	// Size of the send buffer. When zero, DefaultBufferSize is used.
	BufferSize int
}

type UDPMode

type UDPMode byte
const (
	UDPPlainText UDPMode = iota
	UDPSign
	UDPEncrypt
)

type ValueList

type ValueList struct {
	Metric *Metric
	Time   time.Time
	Values []float64
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL