statsd

package module
v0.0.0-...-3d6a556 Latest Latest
Warning

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

 Go to latest Published: Jan 18, 2018 License: MIT Imports: 9 Imported by: 78

README

StatsD client (Golang)

Build Status GoDoc

Introduction

Go Client library for StatsD. Contains a direct and a buffered client. The buffered version will hold and aggregate values for the same key in memory before flushing them at the defined frequency.

This client library was inspired by the one embedded in the Bit.ly NSQ project, and extended to support some extra custom events used at DataSift.

Installation

go get github.com/quipo/statsd

Supported event types

  • Increment - Count occurrences per second/minute of a specific event
  • Decrement - Count occurrences per second/minute of a specific event
  • Timing - To track a duration event
  • PrecisionTiming - To track a duration event
  • Gauge (int) / FGauge (float) - Gauges are a constant data type. They are not subject to averaging, and they don’t change unless you change them. That is, once you set a gauge value, it will be a flat line on the graph until you change it again
  • GaugeDelta (int) / FGaugeDelta (float) - Same as above, but as a delta change to the previous value rather than a new absolute value
  • Absolute (int) / FAbsolute (float) - Absolute-valued metric (not averaged/aggregated)
  • Total - Continously increasing value, e.g. read operations since boot

Sample usage

package main

import (
	"log"
	"os"
	"time"

	"github.com/quipo/statsd"
)

func main() {
	// init
	prefix := "myproject."
	statsdclient := statsd.NewStatsdClient("localhost:8125", prefix)
	err := statsdclient.CreateSocket()
	if nil != err {
		log.Println(err)
		os.Exit(1)
	}
	interval := time.Second * 2 // aggregate stats and flush every 2 seconds
	stats := statsd.NewStatsdBuffer(interval, statsdclient)
	defer stats.Close()

	// not buffered: send immediately
	statsdclient.Incr("mymetric", 4)

	// buffered: aggregate in memory before flushing
	stats.Incr("mymetric", 1)
	stats.Incr("mymetric", 3)
	stats.Incr("mymetric", 1)
	stats.Incr("mymetric", 1)
}

The string %HOST% in the metric name will automatically be replaced with the hostname of the server the event is sent from.

Changelog

  • HEAD:

  • v.1.4.0

    • Fixed behaviour of Gauge with positive numbers: the previous behaviour was the same as GaugeDelta (FGauge already had the correct behaviour)
    • Added more tests
    • Small optimisation: replace string formatting with concatenation (thanks to @agnivade)

  • v.1.3.0:

    • Added stdout client ("echo" service for debugging)
    • Fixed issue #23: GaugeDelta event Stats() should not send an absolute value of 0
    • Fixed FGauge's collation in the buffered client to only preserve the last value in the batch (it mistakenly had the same implementation of FGaugeDelta's collation)
    • Fixed FGaugeDelta with negative value not to send a 0 value first (it mistakenly had the same implementation of FGauge)
    • Added many tests
    • Added compile-time checks that the default events implement the Event interface

  • v.1.2.0: Sample rate support (thanks to Hongjian Zhu)

  • v.1.1.0:

    • Added SendEvents function to Statsd interface;
    • Using interface in buffered client constructor;
    • Added/Fixed tests

  • v.1.0.0: First stable release

  • v.0.0.9: Added memoization to reduce memory allocations

  • v.0.0.8: Pre-release

Author

Lorenzo Alberton

See LICENSE document

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidCount      = errors.New("count is less than 0")
	ErrInvalidSampleRate = errors.New("sample rate is larger than 1 or less then 0")
)

errors

View Source 
var Hostname string

Hostname is exported so clients can set it to something different than the default

View Source 
var UDPPayloadSize = 512

UDPPayloadSize is the number of bytes to send at one go through the udp socket. SendEvents will try to pack as many events into one udp packet. Change this value as per network capabilities For example to change to 16KB 

import "github.com/quipo/statsd"
func init() {
 statsd.UDPPayloadSize = 16 * 1024
}

Functions

This section is empty.

Types

type Logger 

type Logger interface {
	Println(v ...interface{})
}

Logger interface compatible with log.Logger

type NoopClient 

type NoopClient struct{}

NoopClient implements a "no-op" statsd in case there is no statsd server

func (NoopClient) Absolute 

func (s NoopClient) Absolute(stat string, value int64) error

Absolute does nothing

func (NoopClient) Close 

func (s NoopClient) Close() error

Close does nothing

func (NoopClient) CreateSocket 

func (s NoopClient) CreateSocket() error

CreateSocket does nothing

func (NoopClient) CreateTCPSocket 

func (s NoopClient) CreateTCPSocket() error

CreateTCPSocket does nothing

func (NoopClient) Decr 

func (s NoopClient) Decr(stat string, count int64) error

Decr does nothing

func (NoopClient) FAbsolute 

func (s NoopClient) FAbsolute(stat string, value float64) error

FAbsolute does nothing

func (NoopClient) FGauge 

func (s NoopClient) FGauge(stat string, value float64) error

FGauge does nothing

func (NoopClient) FGaugeDelta 

func (s NoopClient) FGaugeDelta(stat string, value float64) error

FGaugeDelta does nothing

func (NoopClient) Gauge 

func (s NoopClient) Gauge(stat string, value int64) error

Gauge does nothing

func (NoopClient) GaugeDelta 

func (s NoopClient) GaugeDelta(stat string, value int64) error

GaugeDelta does nothing

func (NoopClient) Incr 

func (s NoopClient) Incr(stat string, count int64) error

Incr does nothing

func (NoopClient) PrecisionTiming 

func (s NoopClient) PrecisionTiming(stat string, delta time.Duration) error

PrecisionTiming does nothing

func (NoopClient) SendEvents 

func (s NoopClient) SendEvents(events map[string]event.Event) error

SendEvents does nothing

func (NoopClient) Timing 

func (s NoopClient) Timing(stat string, count int64) error

Timing does nothing

func (NoopClient) Total 

func (s NoopClient) Total(stat string, value int64) error

Total does nothing

type Statsd 

type Statsd interface {
	CreateSocket() error
	CreateTCPSocket() error
	Close() error
	Incr(stat string, count int64) error
	Decr(stat string, count int64) error
	Timing(stat string, delta int64) error
	PrecisionTiming(stat string, delta time.Duration) error
	Gauge(stat string, value int64) error
	GaugeDelta(stat string, value int64) error
	Absolute(stat string, value int64) error
	Total(stat string, value int64) error

	FGauge(stat string, value float64) error
	FGaugeDelta(stat string, value float64) error
	FAbsolute(stat string, value float64) error

	SendEvents(events map[string]event.Event) error
}

Statsd is an interface to a StatsD client (buffered/unbuffered)

type StatsdBuffer 

type StatsdBuffer struct {
	Logger  Logger
	Verbose bool
	// contains filtered or unexported fields
}

StatsdBuffer is a client library to aggregate events in memory before flushing aggregates to StatsD, useful if the frequency of events is extremely high and sampling is not desirable

func NewStatsdBuffer 

func NewStatsdBuffer(interval time.Duration, client Statsd) *StatsdBuffer

NewStatsdBuffer Factory

func (*StatsdBuffer) Absolute 

func (sb *StatsdBuffer) Absolute(stat string, value int64) error

Absolute - Send absolute-valued metric (not averaged/aggregated)

func (*StatsdBuffer) Close 

func (sb *StatsdBuffer) Close() (err error)

Close sends a close event to the collector asking to stop & flush pending stats and closes the statsd client

func (*StatsdBuffer) CreateSocket 

func (sb *StatsdBuffer) CreateSocket() error

CreateSocket creates a UDP connection to a StatsD server

func (*StatsdBuffer) CreateTCPSocket 

func (sb *StatsdBuffer) CreateTCPSocket() error

CreateTCPSocket creates a TCP connection to a StatsD server

func (*StatsdBuffer) Decr 

func (sb *StatsdBuffer) Decr(stat string, count int64) error

Decr - Decrement a counter metric. Often used to note a particular event

func (*StatsdBuffer) FAbsolute 

func (sb *StatsdBuffer) FAbsolute(stat string, value float64) error

FAbsolute - Send absolute-valued metric (not averaged/aggregated)

func (*StatsdBuffer) FGauge 

func (sb *StatsdBuffer) FGauge(stat string, value float64) error

FGauge is a Gauge working with float64 values

func (*StatsdBuffer) FGaugeDelta 

func (sb *StatsdBuffer) FGaugeDelta(stat string, value float64) error

FGaugeDelta records a delta from the previous value (as float64)

func (*StatsdBuffer) Gauge 

func (sb *StatsdBuffer) Gauge(stat string, value int64) error

Gauge - Gauges are a constant data type. They are not subject to averaging, and they don’t change unless you change them. That is, once you set a gauge value, it will be a flat line on the graph until you change it again

func (*StatsdBuffer) GaugeDelta 

func (sb *StatsdBuffer) GaugeDelta(stat string, value int64) error

GaugeDelta records a delta from the previous value (as int64)

func (*StatsdBuffer) Incr 

func (sb *StatsdBuffer) Incr(stat string, count int64) error

Incr - Increment a counter metric. Often used to note a particular event

func (*StatsdBuffer) PrecisionTiming 

func (sb *StatsdBuffer) PrecisionTiming(stat string, delta time.Duration) error

PrecisionTiming - Track a duration event the time delta has to be a duration

func (*StatsdBuffer) SendEvents 

func (sb *StatsdBuffer) SendEvents(events map[string]event.Event) error

SendEvents - Sends stats from all the event objects.

func (*StatsdBuffer) Timing 

func (sb *StatsdBuffer) Timing(stat string, delta int64) error

Timing - Track a duration event

func (*StatsdBuffer) Total 

func (sb *StatsdBuffer) Total(stat string, value int64) error

Total - Send a metric that is continously increasing, e.g. read operations since boot

type StatsdClient 

type StatsdClient struct {
	Logger Logger
	// contains filtered or unexported fields
}

StatsdClient is a client library to send events to StatsD

func NewStatsdClient 

func NewStatsdClient(addr string, prefix string) *StatsdClient

NewStatsdClient - Factory

func (*StatsdClient) Absolute 

func (c *StatsdClient) Absolute(stat string, value int64) error

Absolute - Send absolute-valued metric (not averaged/aggregated)

func (*StatsdClient) Close 

func (c *StatsdClient) Close() error

Close the UDP connection

func (*StatsdClient) CreateSocket 

func (c *StatsdClient) CreateSocket() error

CreateSocket creates a UDP connection to a StatsD server

func (*StatsdClient) CreateTCPSocket 

func (c *StatsdClient) CreateTCPSocket() error

CreateTCPSocket creates a TCP connection to a StatsD server

func (*StatsdClient) Decr 

func (c *StatsdClient) Decr(stat string, count int64) error

Decr - Decrement a counter metric. Often used to note a particular event

func (*StatsdClient) DecrWithSampling 

func (c *StatsdClient) DecrWithSampling(stat string, count int64, sampleRate float32) error

DecrWithSampling - Decrement a counter metric with sampling between 0 and 1

func (*StatsdClient) FAbsolute 

func (c *StatsdClient) FAbsolute(stat string, value float64) error

FAbsolute - Send absolute-valued floating point metric (not averaged/aggregated)

func (*StatsdClient) FGauge 

func (c *StatsdClient) FGauge(stat string, value float64) error

FGauge -- Send a floating point value for a gauge

func (*StatsdClient) FGaugeDelta 

func (c *StatsdClient) FGaugeDelta(stat string, value float64) error

FGaugeDelta -- Send a floating point change for a gauge

func (*StatsdClient) FGaugeWithSampling 

func (c *StatsdClient) FGaugeWithSampling(stat string, value float64, sampleRate float32) error

FGaugeWithSampling - Gauges are a constant data type.

func (*StatsdClient) Gauge 

func (c *StatsdClient) Gauge(stat string, value int64) error

Gauge - Gauges are a constant data type. They are not subject to averaging, and they don’t change unless you change them. That is, once you set a gauge value, it will be a flat line on the graph until you change it again. If you specify delta to be true, that specifies that the gauge should be updated, not set. Due to the underlying protocol, you can't explicitly set a gauge to a negative number without first setting it to zero.

func (*StatsdClient) GaugeDelta 

func (c *StatsdClient) GaugeDelta(stat string, value int64) error

GaugeDelta -- Send a change for a gauge

func (*StatsdClient) GaugeWithSampling 

func (c *StatsdClient) GaugeWithSampling(stat string, value int64, sampleRate float32) error

GaugeWithSampling - Gauges are a constant data type.

func (*StatsdClient) Incr 

func (c *StatsdClient) Incr(stat string, count int64) error

Incr - Increment a counter metric. Often used to note a particular event

func (*StatsdClient) IncrWithSampling 

func (c *StatsdClient) IncrWithSampling(stat string, count int64, sampleRate float32) error

IncrWithSampling - Increment a counter metric with sampling between 0 and 1

func (*StatsdClient) PrecisionTiming 

func (c *StatsdClient) PrecisionTiming(stat string, delta time.Duration) error

PrecisionTiming - Track a duration event the time delta has to be a duration

func (*StatsdClient) SendEvent 

func (c *StatsdClient) SendEvent(e event.Event) error

SendEvent - Sends stats from an event object

func (*StatsdClient) SendEvents 

func (c *StatsdClient) SendEvents(events map[string]event.Event) error

SendEvents - Sends stats from all the event objects. Tries to bundle many together into one fmt.Fprintf based on UDPPayloadSize.

func (*StatsdClient) String 

func (c *StatsdClient) String() string

String returns the StatsD server address

func (*StatsdClient) Timing 

func (c *StatsdClient) Timing(stat string, delta int64) error

Timing - Track a duration event the time delta must be given in milliseconds

func (*StatsdClient) TimingWithSampling 

func (c *StatsdClient) TimingWithSampling(stat string, delta int64, sampleRate float32) error

TimingWithSampling - Track a duration event

func (*StatsdClient) Total 

func (c *StatsdClient) Total(stat string, value int64) error

Total - Send a metric that is continously increasing, e.g. read operations since boot

type StdoutClient 

type StdoutClient struct {
	FD *os.File

	Logger Logger
	// contains filtered or unexported fields
}

StdoutClient implements a "no-op" statsd in case there is no statsd server

func NewStdoutClient 

func NewStdoutClient(filename string, prefix string) *StdoutClient

NewStdoutClient - Factory

func (*StdoutClient) Absolute 

func (s *StdoutClient) Absolute(stat string, value int64) error

Absolute - Send absolute-valued metric (not averaged/aggregated)

func (*StdoutClient) Close 

func (s *StdoutClient) Close() error

Close does nothing

func (*StdoutClient) CreateSocket 

func (s *StdoutClient) CreateSocket() error

CreateSocket does nothing

func (*StdoutClient) CreateTCPSocket 

func (s *StdoutClient) CreateTCPSocket() error

CreateTCPSocket does nothing

func (*StdoutClient) Decr 

func (s *StdoutClient) Decr(stat string, count int64) error

Decr - Decrement a counter metric. Often used to note a particular event

func (*StdoutClient) FAbsolute 

func (s *StdoutClient) FAbsolute(stat string, value float64) error

FAbsolute - Send absolute-valued floating point metric (not averaged/aggregated)

func (*StdoutClient) FGauge 

func (s *StdoutClient) FGauge(stat string, value float64) error

FGauge -- Send a floating point value for a gauge

func (*StdoutClient) FGaugeDelta 

func (s *StdoutClient) FGaugeDelta(stat string, value float64) error

FGaugeDelta -- Send a floating point change for a gauge

func (*StdoutClient) Gauge 

func (s *StdoutClient) Gauge(stat string, value int64) error

Gauge - Gauges are a constant data type. They are not subject to averaging, and they don’t change unless you change them. That is, once you set a gauge value, it will be a flat line on the graph until you change it again. If you specify delta to be true, that specifies that the gauge should be updated, not set. Due to the underlying protocol, you can't explicitly set a gauge to a negative number without first setting it to zero.

func (*StdoutClient) GaugeDelta 

func (s *StdoutClient) GaugeDelta(stat string, value int64) error

GaugeDelta -- Send a change for a gauge

func (*StdoutClient) Incr 

func (s *StdoutClient) Incr(stat string, count int64) error

Incr - Increment a counter metric. Often used to note a particular event

func (*StdoutClient) PrecisionTiming 

func (s *StdoutClient) PrecisionTiming(stat string, delta time.Duration) error

PrecisionTiming - Track a duration event the time delta has to be a duration

func (*StdoutClient) SendEvent 

func (s *StdoutClient) SendEvent(e event.Event) error

SendEvent - Sends stats from an event object

func (*StdoutClient) SendEvents 

func (s *StdoutClient) SendEvents(events map[string]event.Event) error

SendEvents - Sends stats from all the event objects. Tries to bundle many together into one fmt.Fprintf based on UDPPayloadSize.

func (*StdoutClient) Timing 

func (s *StdoutClient) Timing(stat string, delta int64) error

Timing - Track a duration event the time delta must be given in milliseconds

func (*StdoutClient) Total 

func (s *StdoutClient) Total(stat string, value int64) error

Total - Send a metric that is continously increasing, e.g. read operations since boot

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.