Documentation ¶
Overview ¶
Package godspeed is a statsd client for the Datadog extension of statsd (DogStatsD). It is used to emit statsd stats as well as the Datadog-specific events. This client also has the ability to tag all outgoing statsd metrics. Godspeed is meant for synchronous calls, while AsyncGodspeed is used for what it says on the tin.
The name godspeed is a bit of a rhyming slang twist on DogStatsD. It's also a poke at the fact that the statsd protocol's transport mechanism is UDP...
DogStatsD is a copyright of Datadog <info@datadoghq.com>
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { // this uses the default host and port (127.0.0.1:8125) g, err := godspeed.NewDefault() if err != nil { // handle error } // defer closing the connection defer g.Conn.Close() g.AddTags([]string{"example", "example2"}) err = g.Incr("example.run_count", nil) // all emission method calls should return an error object // you should probably check it if err != nil { // handle error } // this returns an error object too, just omitting for brevity g.Gauge("example.gauge", 42, nil) }
Output:
Index ¶
- Constants
- type AsyncGodspeed
- func (a *AsyncGodspeed) AddTag(tag string) []string
- func (a *AsyncGodspeed) AddTags(tags []string) []string
- func (a *AsyncGodspeed) Count(stat string, count float64, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) Decr(stat string, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) Event(title, body string, keys map[string]string, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) Gauge(stat string, value float64, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) Histogram(stat string, value float64, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) Incr(stat string, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) Send(stat, kind string, delta, sampleRate float64, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) ServiceCheck(name string, status int, fields map[string]string, tags []string, ...)
- func (a *AsyncGodspeed) Set(stat string, value float64, tags []string, y *sync.WaitGroup)
- func (a *AsyncGodspeed) SetNamespace(ns string)
- func (a *AsyncGodspeed) Timing(stat string, value float64, tags []string, y *sync.WaitGroup)
- type Godspeed
- func (g *Godspeed) AddTag(tag string) []string
- func (g *Godspeed) AddTags(tags []string) []string
- func (g *Godspeed) Count(stat string, count float64, tags []string) error
- func (g *Godspeed) Decr(stat string, tags []string) error
- func (g *Godspeed) Event(title, text string, fields map[string]string, tags []string) error
- func (g *Godspeed) Gauge(stat string, value float64, tags []string) error
- func (g *Godspeed) Histogram(stat string, value float64, tags []string) error
- func (g *Godspeed) Incr(stat string, tags []string) error
- func (g *Godspeed) Send(stat, kind string, delta, sampleRate float64, tags []string) (err error)
- func (g *Godspeed) ServiceCheck(name string, status int, fields map[string]string, tags []string) error
- func (g *Godspeed) Set(stat string, value float64, tags []string) error
- func (g *Godspeed) SetNamespace(ns string)
- func (g *Godspeed) Timing(stat string, value float64, tags []string) error
Examples ¶
Constants ¶
const ( // DefaultHost is 127.0.0.1 (localhost) DefaultHost = "127.0.0.1" // DefaultPort is 8125 DefaultPort = 8125 // MaxBytes is the largest UDP datagram we will try to send MaxBytes = 8192 )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AsyncGodspeed ¶
type AsyncGodspeed struct { // Godspeed is an instance of Godspeed Godspeed *Godspeed // W is a *sync.WaitGroup used for blocking application execution // when you want to wait for stats to be emitted. // This is here as a convenience, and you can use your own WaitGroup // in any AsyncGodspeed method calls. W *sync.WaitGroup }
AsyncGodspeed is used for asynchronous Godspeed calls. The AsyncGodspeed emission methods have an additional argument for a *sync.WaitGroup to have the method indicate when finished.
func NewAsync ¶
func NewAsync(host string, port int, autoTruncate bool) (a *AsyncGodspeed, err error)
NewAsync returns an instance of AsyncGodspeed. This is the more async-friendly version of Godspeed autoTruncate dictactes whether long stats emissions get auto-truncated or dropped. Unfortunately, Events will always be dropped. If you need monitor your events, you can access the Godspeed instance directly.
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { a, err := godspeed.NewAsync(godspeed.DefaultHost, godspeed.DefaultPort, false) if err != nil { // handle error } defer a.Godspeed.Conn.Close() // add to the WaitGroup to make sure we are able to wait below a.W.Add(1) go a.Gauge("example.gauge", 1, nil, a.W) a.W.Wait() }
Output:
func NewDefaultAsync ¶
func NewDefaultAsync() (a *AsyncGodspeed, err error)
NewDefaultAsync is just like NewAsync except it uses the DefaultHost and DefaultPort
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { a, err := godspeed.NewDefaultAsync() if err != nil { // handle error } defer a.Godspeed.Conn.Close() a.W.Add(1) go a.Gauge("example.gauge", 1, nil, a.W) a.W.Wait() }
Output:
func (*AsyncGodspeed) AddTag ¶
func (a *AsyncGodspeed) AddTag(tag string) []string
AddTag is identical to that within the Godspeed client
func (*AsyncGodspeed) AddTags ¶
func (a *AsyncGodspeed) AddTags(tags []string) []string
AddTags is identical to that within the Godspeed client
func (*AsyncGodspeed) Count ¶
Count is almost identical to that within the Godspeed client As with the other AsyncGodpseed functions it omits a return value and takes a *sync.WaitGroup instance
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { a, _ := godspeed.NewDefaultAsync() defer a.Godspeed.Conn.Close() a.W.Add(1) go a.Count("example.count", 42, nil, a.W) a.W.Wait() }
Output:
func (*AsyncGodspeed) Decr ¶
func (a *AsyncGodspeed) Decr(stat string, tags []string, y *sync.WaitGroup)
Decr is almost identical to that within the Godspeed client. It has no return value and takes a *sync.WaitGroup argument.
Also, I've gotten tired of typing "Xxx is almost identical to that within..." so congrats on making it this far in to the docs.
func (*AsyncGodspeed) Event ¶
func (a *AsyncGodspeed) Event(title, body string, keys map[string]string, tags []string, y *sync.WaitGroup)
Event is almost identical to that within the Godspeed client The only chnage is that it has no return value, and takes a (sync.WaitGroup) argument
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { a, _ := godspeed.NewDefaultAsync() defer a.Godspeed.Conn.Close() a.W.Add(1) go a.Event("example event", "something happened", nil, nil, a.W) a.W.Wait() }
Output:
func (*AsyncGodspeed) Gauge ¶
Gauge is almost identical to that within the Godspeed client. Here it has no return value, and takes a *sync.WaitGroup argument
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { a, _ := godspeed.NewDefaultAsync() defer a.Godspeed.Conn.Close() a.W.Add(1) go a.Gauge("example.gauge", 1, nil, a.W) a.W.Wait() }
Output:
func (*AsyncGodspeed) Histogram ¶
Histogram is almost identical to that within the Godspeed client. Within AsyncGodspeed it has no return value, and also takes a *sync.WaitGroup argument
func (*AsyncGodspeed) Incr ¶
func (a *AsyncGodspeed) Incr(stat string, tags []string, y *sync.WaitGroup)
Incr is almost identical to that within the Godspeed client, except it has no return value and takes a *sync.WaitGroup argument.
func (*AsyncGodspeed) Send ¶
func (a *AsyncGodspeed) Send(stat, kind string, delta, sampleRate float64, tags []string, y *sync.WaitGroup)
Send is almost identical to that within the Godspeed client with the addition of an argument and removal of the return value
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { a, _ := godspeed.NewDefaultAsync() defer a.Godspeed.Conn.Close() a.W.Add(1) go a.Send("example.stat", "g", 1, 1, nil, a.W) a.W.Wait() }
Output:
func (*AsyncGodspeed) ServiceCheck ¶
func (a *AsyncGodspeed) ServiceCheck(name string, status int, fields map[string]string, tags []string, y *sync.WaitGroup)
ServiceCheck is almost identical to that within the Godspeed client with the addition of an argument and removal of the return value
func (*AsyncGodspeed) SetNamespace ¶
func (a *AsyncGodspeed) SetNamespace(ns string)
SetNamespace is identical to that within the Godspeed client
type Godspeed ¶
type Godspeed struct { // Conn is the UDP connection used for sending the statsd emissions Conn *net.UDPConn // Namespace is the namespace all stats emissions are prefixed with: // <namespace>.<statname> Namespace string // Tags is the slice of tags to append to each stat emission Tags []string // AutoTruncate specifies whether or not we will try to truncate a stat // before emitting it or just return an error. This is most helpful when // using AsyncGodspeed. However, it can result in invalid stat being emitted // due to the body being truncated. Meant for when a single emission would // be greater than 8192 bytes. AutoTruncate bool }
Godspeed is an unbuffered Statsd client with compatability geared towards the Datadog statsd format It consists of Conn (*net.UDPConn) object for sending metrics over UDP, Namespace (string) for namespacing metrics, and Tags ([]string) for tags to send with stats
func New ¶
New returns a new instance of a Godspeed statsd client. This method takes the host as a string, and port as an int. There is also the ability for autoTruncate. If your metric is longer than MaxBytes autoTruncate can be used to truncate the message instead of erroring. This doesn't work on events and will always return an error.
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { g, err := godspeed.New(godspeed.DefaultHost, godspeed.DefaultPort, false) if err != nil { // handle error } defer g.Conn.Close() err = g.Gauge("example.stat", 1, nil) if err != nil { // handle error } }
Output:
func NewDefault ¶
NewDefault is the same as New() except it uses DefaultHost and DefaultPort for the connection.
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { g, err := godspeed.NewDefault() if err != nil { // handle error } defer g.Conn.Close() g.Gauge("example.stat", 1, nil) }
Output:
func (*Godspeed) AddTag ¶
AddTag allows you to add a tag for all future emitted stats. It takes the tag as a string, and returns a []string containing all Godspeed tags
Example ¶
package main import ( "fmt" "github.com/PagerDuty/godspeed" ) func main() { // be sure to handle the error g, _ := godspeed.NewDefault() defer g.Conn.Close() g.AddTag("example1") tags := g.AddTag("example2") fmt.Println(tags) }
Output: [example1 example2]
func (*Godspeed) AddTags ¶
AddTags is like AddTag(), except it tages a []string and adds each contained string This also returns a []string containing the current tags
Example ¶
package main import ( "fmt" "github.com/PagerDuty/godspeed" ) func main() { g, _ := godspeed.NewDefault() defer g.Conn.Close() newTags := []string{"production", "example"} tags := g.AddTags(newTags) fmt.Println(tags) }
Output: [production example]
func (*Godspeed) Count ¶
Count wraps Send() and simplifies the interface for Count stats
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { g, err := godspeed.NewDefault() if err != nil { // handle error } defer g.Conn.Close() err = g.Count("example.count", 1, nil) if err != nil { // handle error } }
Output:
func (*Godspeed) Decr ¶
Decr wraps Send() and simplifies the interface for decrementing a counter It only takes the name of the stat, and tags
func (*Godspeed) Event ¶
Event is the function for submitting a Datadog event. This is a Datadog-specific emission and most likely will not work on other statsd implementations. title and body are both strings, and are the title and body of the event respectively. field can be used to send the optional keys.
Example ¶
package main import ( "fmt" "github.com/PagerDuty/godspeed" ) func main() { // make sure to handle the error g, _ := godspeed.NewDefault() defer g.Conn.Close() title := "Nginx service restart" text := "The Nginx service has been restarted" // the optionals are for the optional arguments available for an event // http://docs.datadoghq.com/guides/dogstatsd/#fields optionals := make(map[string]string) optionals["alert_type"] = "info" optionals["source_type_name"] = "nginx" addlTags := []string{"source_type:nginx"} err := g.Event(title, text, optionals, addlTags) if err != nil { fmt.Println("err:", err) } }
Output:
func (*Godspeed) Gauge ¶
Gauge wraps Send() and simplifies the interface for Gauge stats
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { g, err := godspeed.NewDefault() if err != nil { // handle error } defer g.Conn.Close() err = g.Gauge("example.gauge", 1, nil) if err != nil { // handle error } }
Output:
func (*Godspeed) Histogram ¶
Histogram wraps Send() and simplifies the interface for Histogram stats
func (*Godspeed) Incr ¶
Incr wraps Send() and simplifies the interface for incrementing a counter It only takes the name of the stat, and tags
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { g, _ := godspeed.NewDefault() defer g.Conn.Close() err := g.Incr("example.counter", nil) if err != nil { // handle error } }
Output:
func (*Godspeed) Send ¶
Send is the function for emitting the metrics to statsd It takes the name of the stat as a string, as well as the kind. The kind is "g" for gauge, "c" for count, "ms" for timing, etc. This returns any error hit during the flushing of the stat
Example ¶
package main import ( "github.com/PagerDuty/godspeed" ) func main() { g, err := godspeed.NewDefault() if err != nil { // handle error } defer g.Conn.Close() tags := []string{"example"} err = g.Send("example.stat", "g", 1, 1, tags) if err != nil { // handle error } }
Output:
func (*Godspeed) ServiceCheck ¶
func (g *Godspeed) ServiceCheck(name string, status int, fields map[string]string, tags []string) error
ServiceCheck is a function to emit DogStatsD service checks to the local DD agent. It takes the name of the service, which must NOT contain a pipe (|) character, and the numeric status for the service. The status values are the same as Nagios:
OK = 0, WARNING = 1, CRITICAL = 2, UNKNOWN = 3
This functionality is an extension to the statsd protocol by Datadog (DogStatsD):
http://docs.datadoghq.com/guides/dogstatsd/#service-checks
Example ¶
package main import ( "fmt" "os" "github.com/PagerDuty/godspeed" ) func main() { // check the error g, _ := godspeed.NewDefault() defer g.Conn.Close() service := "Nagios Service" status := 0 // OK // if you don't want these, pass nil to the function instead optionals := make(map[string]string) optionals["service_check_message"] = "down" optionals["timestamp"] = "1431484263" // if you don't want these, pass nil to the function instead tags := []string{"some:tag"} err := g.ServiceCheck(service, status, optionals, tags) if err != nil { fmt.Fprintf(os.Stderr, err.Error()) } }
Output:
func (*Godspeed) SetNamespace ¶
SetNamespace allows you to prefix all of your metrics with a certain namespace
Example ¶
package main import ( "fmt" "github.com/PagerDuty/godspeed" ) func main() { g, _ := godspeed.NewDefault() defer g.Conn.Close() namespace := "example" g.SetNamespace(namespace) fmt.Println(g.Namespace) }
Output: example