Documentation ¶
Overview ¶
Package statsd provides a StatsD client implementation that is safe for concurrent use by multiple goroutines and for efficiency can be created and reused.
Example usage:
// First create a client config. Here is a simple config that sends one // stat per packet (for compatibility). config := &statsd.ClientConfig{ Address: "127.0.0.1:8125", Prefix: "test-client", } // Now create the client client, err := statsd.NewClientWithConfig(config) // and handle any initialization errors if err != nil { log.Fatal(err) } // make sure to clean up defer client.Close() // Send a stat err = client.Inc("stat1", 42, 1.0) // handle any errors if err != nil { log.Printf("Error sending metric: %+v", err) }
Index ¶
- Variables
- func CheckName(stat string) error
- func DefaultSampler(rate float32) bool
- type BufferedSender
- type Client
- func (s *Client) Close() error
- func (s *Client) Dec(stat string, value int64, rate float32, tags ...Tag) error
- func (s *Client) Gauge(stat string, value int64, rate float32, tags ...Tag) error
- func (s *Client) GaugeDelta(stat string, value int64, rate float32, tags ...Tag) error
- func (s *Client) GaugeFloat(stat string, value float64, rate float32, tags ...Tag) error
- func (s *Client) GaugeFloatDelta(stat string, value float64, rate float32, tags ...Tag) error
- func (s *Client) Inc(stat string, value int64, rate float32, tags ...Tag) error
- func (s *Client) NewSubStatter(prefix string) SubStatter
- func (s *Client) Raw(stat string, value string, rate float32, tags ...Tag) error
- func (s *Client) Set(stat string, value string, rate float32, tags ...Tag) error
- func (s *Client) SetFloat(stat string, value float64, rate float32, tags ...Tag) error
- func (s *Client) SetInt(stat string, value int64, rate float32, tags ...Tag) error
- func (s *Client) SetPrefix(prefix string)
- func (s *Client) SetSamplerFunc(sampler SamplerFunc)
- func (s *Client) Timing(stat string, delta int64, rate float32, tags ...Tag) error
- func (s *Client) TimingDuration(stat string, delta time.Duration, rate float32, tags ...Tag) error
- type ClientConfig
- type ExtendedStatSender
- type ResolvingSimpleSender
- type SamplerFunc
- type Sender
- func NewBufferedSender(addr string, flushInterval time.Duration, flushBytes int) (Sender, error)
- func NewBufferedSenderWithSender(sender Sender, flushInterval time.Duration, flushBytes int) (Sender, error)
- func NewResolvingSimpleSender(addr string, interval time.Duration) (Sender, error)
- func NewSimpleSender(addr string) (Sender, error)
- type SimpleSender
- type StatSender
- type Statter
- func NewBufferedClient(addr, prefix string, flushInterval time.Duration, flushBytes int) (Statter, error)deprecated
- func NewClient(addr, prefix string) (Statter, error)deprecated
- func NewClientWithConfig(config *ClientConfig) (Statter, error)
- func NewClientWithSender(sender Sender, prefix string, tagFormat TagFormat) (Statter, error)
- type SubStatter
- type Tag
- type TagFormat
- type ValidatorFunc
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var Dial = NewClient
Dial is a compatibility alias for NewClient
Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.
var New = NewClient
New is a compatibility alias for NewClient
Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.
Functions ¶
func CheckName ¶
CheckName may be used to validate whether a stat name contains invalid characters. If invalid characters are found, the function will return an error.
func DefaultSampler ¶
DefaultSampler is the default rate sampler function
Types ¶
type BufferedSender ¶
type BufferedSender struct {
// contains filtered or unexported fields
}
BufferedSender provides a buffered statsd udp, sending multiple metrics, where possible.
func (*BufferedSender) Close ¶
func (s *BufferedSender) Close() error
Close closes the Buffered Sender and cleans up.
func (*BufferedSender) Start ¶
func (s *BufferedSender) Start()
Start Buffered Sender Begins ticker and read loop
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
A Client is a statsd client.
Example ¶
// First create a client config. Here is a simple config that sends one // stat per packet (for compatibility). config := &ClientConfig{ Address: "127.0.0.1:8125", Prefix: "test-client", } // Now create the client client, err := NewClientWithConfig(config) // and handle any initialization errors if err != nil { log.Fatal(err) } // make sure to clean up defer client.Close() // Send a stat err = client.Inc("stat1", 42, 1.0) // handle any errors if err != nil { log.Printf("Error sending metric: %+v", err) }
Output:
Example (Buffered) ¶
// This one is for a buffered client, which sends multiple stats in one // packet, is recommended when your server supports it (better performance). config := &ClientConfig{ Address: "127.0.0.1:8125", Prefix: "test-client", UseBuffered: true, // interval to force flush buffer. full buffers will flush on their own, // but for data not frequently sent, a max threshold is useful FlushInterval: 300 * time.Millisecond, } // Now create the client client, err := NewClientWithConfig(config) // and handle any initialization errors if err != nil { log.Fatal(err) } // make sure to close to clean up when done, to avoid leaks. defer client.Close() // Send a stat err = client.Inc("stat1", 42, 1.0) // handle any errors if err != nil { log.Printf("Error sending metric: %+v", err) }
Output:
Example (LegacyBuffered) ¶
// first create a client client, err := NewBufferedClient("127.0.0.1:8125", "test-client", 10*time.Millisecond, 0) // handle any errors if err != nil { log.Fatal(err) } // make sure to close to clean up when done, to avoid leaks. defer client.Close() // Send a stat err = client.Inc("stat1", 42, 1.0) // handle any errors if err != nil { log.Printf("Error sending metric: %+v", err) }
Output:
Example (LegacySimple) ¶
// first create a client client, err := NewClient("127.0.0.1:8125", "test-client") // handle any errors if err != nil { log.Fatal(err) } // make sure to close to clean up when done, to avoid leaks. defer client.Close() // Send a stat err = client.Inc("stat1", 42, 1.0) // handle any errors if err != nil { log.Printf("Error sending metric: %+v", err) }
Output:
Example (Nil) ¶
// use interface so we can sub nil client if needed var client Statter var err error // First create a client config. Here is a simple config that sends one // stat per packet (for compatibility). config := &ClientConfig{ Address: "not-resolvable:8125", Prefix: "test-client", } // Now create the client client, err = NewClientWithConfig(config) // Let us say real client creation fails, but you don't care enough about // stats that you don't want your program to run. Just log an error and // make a nil instead if err != nil { log.Println("Remote endpoint did not resolve. Disabling stats", err) } // at this point, client is a nil *Client. This will work like a noop client. // It is ok to call close when client is nil. It will be a noop too. defer client.Close() // Sicne client is nil, this is a noop. err = client.Inc("stat1", 42, 1.0)
Output:
Example (Substatter) ¶
// First create a client config. Here is a simple config that sends one // stat per packet (for compatibility). config := &ClientConfig{ Address: "127.0.0.1:8125", Prefix: "test-client", } // Now create the client client, err := NewClientWithConfig(config) // handle any errors if err != nil { log.Fatal(err) } // make sure to close to clean up when done, to avoid leaks. defer client.Close() // create a substatter subclient := client.NewSubStatter("sub") // send a stat err = subclient.Inc("stat1", 42, 1.0) // handle any errors if err != nil { log.Printf("Error sending metric: %+v", err) }
Output:
func (*Client) Dec ¶
Dec decrements a statsd count type. stat is a string name for the metric. value is the integer value. rate is the sample rate (0.0 to 1.0).
func (*Client) Gauge ¶
Gauge submits/updates a statsd gauge type. stat is a string name for the metric. value is the integer value. rate is the sample rate (0.0 to 1.0).
func (*Client) GaugeDelta ¶
GaugeDelta submits a delta to a statsd gauge. stat is the string name for the metric. value is the (positive or negative) change. rate is the sample rate (0.0 to 1.0).
func (*Client) GaugeFloat ¶ added in v5.1.0
GaugeFloat submits/updates a float statsd gauge type. Note: May not be supported by all servers. stat is a string name for the metric. value is the float64 value. rate is the sample rate (0.0 to 1.0).
func (*Client) GaugeFloatDelta ¶ added in v5.1.0
GaugeFloatDelta submits a float delta to a statsd gauge. Note: May not be supported by all servers. stat is the string name for the metric. value is the (positive or negative) change. rate is the sample rate (0.0 to 1.0).
func (*Client) Inc ¶
Inc increments a statsd count type. stat is a string name for the metric. value is the integer value rate is the sample rate (0.0 to 1.0) tags is a []Tag
func (*Client) NewSubStatter ¶
func (s *Client) NewSubStatter(prefix string) SubStatter
NewSubStatter returns a SubStatter with appended prefix
func (*Client) Raw ¶
Raw submits a preformatted value. stat is the string name for the metric. value is a preformatted "raw" value string. rate is the sample rate (0.0 to 1.0).
func (*Client) Set ¶
Set submits a stats set type stat is a string name for the metric. value is the string value rate is the sample rate (0.0 to 1.0).
func (*Client) SetFloat ¶ added in v5.1.0
SetFloat submits a number as a stats set type. Note: May not be supported by all servers. stat is a string name for the metric. value is the integer value rate is the sample rate (0.0 to 1.0).
func (*Client) SetInt ¶
SetInt submits a number as a stats set type. stat is a string name for the metric. value is the integer value rate is the sample rate (0.0 to 1.0).
func (*Client) SetPrefix ¶
SetPrefix sets/updates the statsd client prefix. Note: Does not change the prefix of any SubStatters.
func (*Client) SetSamplerFunc ¶
func (s *Client) SetSamplerFunc(sampler SamplerFunc)
SetSamplerFunc sets a sampler function to something other than the default sampler is a function that determines whether the metric is to be accepted, or discarded. An example use case is for submitted pre-sampled metrics.
type ClientConfig ¶
type ClientConfig struct { // addr is a string of the format "hostname:port", and must be something // validly parsable by net.ResolveUDPAddr. Address string // prefix is the statsd client prefix. Can be "" if no prefix is desired. Prefix string // ResInterval is the interval over which the addr is re-resolved. // Do note that this /does/ add overhead! // If you need higher performance, leave unset (or set to 0), // in which case the address will not be re-resolved. // // Note that if Address is an {ip}:{port} and not a {hostname}:{port}, then // ResInterval will be ignored. ResInterval time.Duration // UseBuffered determines whether a buffered sender is used or not. // If a buffered sender is /not/ used, FlushInterval and FlushBytes values are // ignored. Default is false. UseBuffered bool // FlushInterval is a time.Duration, and specifies the maximum interval for // packet sending. Note that if you send lots of metrics, you will send more // often. This is just a maximal threshold. // If FlushInterval is 0, defaults to 300ms. FlushInterval time.Duration // If flushBytes is 0, defaults to 1432 bytes, which is considered safe // for local traffic. If sending over the public internet, 512 bytes is // the recommended value. FlushBytes int // The desired tag format to use for tags (note: statsd tag support varies) // Supported formats are one of: statsd.DataDog, statsd.Grahpite, statsd.Influx TagFormat TagFormat }
type ExtendedStatSender ¶ added in v5.1.0
type ExtendedStatSender interface { StatSender GaugeFloat(string, float64, float32, ...Tag) error GaugeFloatDelta(string, float64, float32, ...Tag) error SetFloat(string, float64, float32, ...Tag) error }
The ExtendedStatSender interface wraps a StatSender and adds some methods that may be unsupported by some servers.
type ResolvingSimpleSender ¶
type ResolvingSimpleSender struct {
// contains filtered or unexported fields
}
ResolvingSimpleSender provides a socket send interface that re-resolves and reconnects.
func (*ResolvingSimpleSender) Close ¶
func (s *ResolvingSimpleSender) Close() error
Close closes the ResolvingSender and cleans up
func (*ResolvingSimpleSender) Reconnect ¶
func (s *ResolvingSimpleSender) Reconnect()
func (*ResolvingSimpleSender) Send ¶
func (s *ResolvingSimpleSender) Send(data []byte) (int, error)
Send sends the data to the server endpoint.
func (*ResolvingSimpleSender) Start ¶
func (s *ResolvingSimpleSender) Start()
Start Resolving Simple Sender Begins ticker and read loop
type SamplerFunc ¶
The SamplerFunc type defines a function that can serve as a Client sampler function.
type Sender ¶
The Sender interface wraps a Send and Close
func NewBufferedSender ¶
NewBufferedSender returns a new BufferedSender
addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.
flushInterval is a time.Duration, and specifies the maximum interval for packet sending. Note that if you send lots of metrics, you will send more often. This is just a maximal threshold.
flushBytes specifies the maximum udp packet size you wish to send. If adding a metric would result in a larger packet than flushBytes, the packet will first be send, then the new data will be added to the next packet.
func NewBufferedSenderWithSender ¶
func NewBufferedSenderWithSender(sender Sender, flushInterval time.Duration, flushBytes int) (Sender, error)
NewBufferedSenderWithSender returns a new BufferedSender, wrapping the provided sender.
sender is an instance of a statsd.Sender interface. Sender is required.
flushInterval is a time.Duration, and specifies the maximum interval for packet sending. Note that if you send lots of metrics, you will send more often. This is just a maximal threshold.
flushBytes specifies the maximum udp packet size you wish to send. If adding a metric would result in a larger packet than flushBytes, the packet will first be send, then the new data will be added to the next packet.
func NewResolvingSimpleSender ¶
NewResolvingSimpleSender returns a new ResolvingSimpleSender for sending to the supplied addresss.
addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.
func NewSimpleSender ¶
NewSimpleSender returns a new SimpleSender for sending to the supplied addresss.
addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.
type SimpleSender ¶
type SimpleSender struct {
// contains filtered or unexported fields
}
SimpleSender provides a socket send interface.
func (*SimpleSender) Close ¶
func (s *SimpleSender) Close() error
Close closes the SimpleSender and cleans up.
type StatSender ¶
type StatSender interface { Inc(string, int64, float32, ...Tag) error Dec(string, int64, float32, ...Tag) error Gauge(string, int64, float32, ...Tag) error GaugeDelta(string, int64, float32, ...Tag) error Timing(string, int64, float32, ...Tag) error TimingDuration(string, time.Duration, float32, ...Tag) error Set(string, string, float32, ...Tag) error SetInt(string, int64, float32, ...Tag) error Raw(string, string, float32, ...Tag) error }
The StatSender interface wraps all the statsd metric methods
type Statter ¶
type Statter interface { StatSender NewSubStatter(string) SubStatter SetPrefix(string) Close() error }
The Statter interface defines the behavior of a stat client
func NewBufferedClient
deprecated
func NewBufferedClient(addr, prefix string, flushInterval time.Duration, flushBytes int) (Statter, error)
NewBufferedClient returns a new BufferedClient
addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.
prefix is the statsd client prefix. Can be "" if no prefix is desired.
flushInterval is a time.Duration, and specifies the maximum interval for packet sending. Note that if you send lots of metrics, you will send more often. This is just a maximal threshold.
If flushInterval is 0ms, defaults to 300ms.
flushBytes specifies the maximum udp packet size you wish to send. If adding a metric would result in a larger packet than flushBytes, the packet will first be send, then the new data will be added to the next packet.
If flushBytes is 0, defaults to 1432 bytes, which is considered safe for local traffic. If sending over the public internet, 512 bytes is the recommended value.
Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.
func NewClient
deprecated
NewClient returns a pointer to a new Client, and an error.
addr is a string of the format "hostname:port", and must be parsable by net.ResolveUDPAddr.
prefix is the statsd client prefix. Can be "" if no prefix is desired.
Deprecated: This interface is "legacy", and it is recommented to migrate to using NewClientWithConfig in the future.
func NewClientWithConfig ¶
func NewClientWithConfig(config *ClientConfig) (Statter, error)
NewClientWithConfig returns a new BufferedClient
config is a ClientConfig, which holds various configuration values.
func NewClientWithSender ¶
NewClientWithSender returns a pointer to a new Client and an error.
sender is an instance of a statsd.Sender interface and may not be nil
prefix is the stastd client prefix. Can be "" if no prefix is desired.
tagFormat is the desired tag format, if any. If you don't plan on using tags, use 0 to use the default.
type SubStatter ¶
type SubStatter interface { StatSender SetSamplerFunc(SamplerFunc) NewSubStatter(string) SubStatter }
The SubStatter interface defines the behavior of a stat child/subclient
type TagFormat ¶
type TagFormat uint8
const ( SuffixOctothorpe TagFormat = 1 << iota InfixSemicolon InfixComma AllInfix = InfixSemicolon | InfixComma AllSuffix = SuffixOctothorpe )
type ValidatorFunc ¶
The ValidatorFunc type defines a function that can serve as a stat name validation function.