godspeed

package
v0.0.0-...-c1cbbd5 Latest Latest
Warning

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

 Go to latest Published: Jun 8, 2015 License: BSD-3-Clause, MPL-2.0 Imports: 7 Imported by: 0

README

Godspeed

TravisCI Build Status GoDoc

Godspeed is a statsd client for the Datadog extension of statsd (DogStatsD). 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...

Check out GoDoc for the docs as well as some examples.

DogStatsD is a copyright of Datadog <info@datadoghq.com>.

License

Godspeed is released under the BSD 3-Clause License. See the LICENSE file for the full contents of the license.

Installation

go get -u github.com/PagerDuty/godspeed

Usage

For more details either look at the _example_test.go files directly or view the examples on GoDoc.

Emitting a gauge
g, err := godspeed.NewDefault()

if err != nil {
    // handle error
}

defer g.Conn.Close()

err = g.Gauge("example.stat", 1, nil)

if err != nil {
	// handle error
}
Emitting an event
// 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)
}

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

Examples

Constants

View Source 
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 

func (a *AsyncGodspeed) Count(stat string, count float64, tags []string, y *sync.WaitGroup)

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 

func (a *AsyncGodspeed) Gauge(stat string, value float64, tags []string, y *sync.WaitGroup)

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 

func (a *AsyncGodspeed) Histogram(stat string, value float64, tags []string, y *sync.WaitGroup)

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) Set 

func (a *AsyncGodspeed) Set(stat string, value float64, tags []string, y *sync.WaitGroup)

Set is almost identical to that within the Godspeed client

func (*AsyncGodspeed) SetNamespace 

func (a *AsyncGodspeed) SetNamespace(ns string)

SetNamespace is identical to that within the Godspeed client

func (*AsyncGodspeed) Timing 

func (a *AsyncGodspeed) Timing(stat string, value float64, tags []string, y *sync.WaitGroup)

Timing is almost identical to that within the Godspeed client. The return value is removed, and it takes a *sync.WaitGroup argument here

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 

func New(host string, port int, autoTruncate bool) (g *Godspeed, err error)

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 

func NewDefault() (g *Godspeed, err error)

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 

func (g *Godspeed) AddTag(tag string) []string

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 

func (g *Godspeed) AddTags(tags []string) []string

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 

func (g *Godspeed) Count(stat string, count float64, tags []string) error

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 

func (g *Godspeed) Decr(stat string, tags []string) error

Decr wraps Send() and simplifies the interface for decrementing a counter It only takes the name of the stat, and tags

func (*Godspeed) Event 

func (g *Godspeed) Event(title, text string, fields map[string]string, tags []string) error

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 

func (g *Godspeed) Gauge(stat string, value float64, tags []string) error

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 

func (g *Godspeed) Histogram(stat string, value float64, tags []string) error

Histogram wraps Send() and simplifies the interface for Histogram stats

func (*Godspeed) Incr 

func (g *Godspeed) Incr(stat string, tags []string) error

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 

func (g *Godspeed) Send(stat, kind string, delta, sampleRate float64, tags []string) (err error)

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) Set 

func (g *Godspeed) Set(stat string, value float64, tags []string) error

Set wraps Send() and simplifies the interface for Timing stats

func (*Godspeed) SetNamespace 

func (g *Godspeed) SetNamespace(ns string)

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

func (*Godspeed) Timing 

func (g *Godspeed) Timing(stat string, value float64, tags []string) error

Timing wraps Send() and simplifies the interface for Timing stats

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.