Code Monkey home page Code Monkey logo

go-statsd's Introduction

StatsD Client (Go)

statsd is a simple, efficient StatsD client written in Go.

build status report card release

Features

  • Works great with netdata
  • Supports Counting, Sampling, Timing, Gauges, Sets and Histograms out of the box
  • Extendable: Ability to send custom metric values and types
  • It is blazing fast and does not allocate unnecessary memory. Metrics are sent based on a customized packet size, manual flushing of buffered metrics is also an option
  • Beautiful, easy to learn API
  • Easy to test
  • Protocol-agnostic

Installation

The only requirement is the Go Programming Language.

$ go get -u github.com/netdata/statsd

Quick start

statsd is simple, it won't take more than 10 minutes of your time to read all of its documentation via godocs.

API

// NewClient returns a new StatsD client.
// The first input argument, "writeCloser", should be a value which implements  
// the `io.WriteCloser` interface.
// It can be a UDP connection or a string buffer or even STDOUT for testing.
// The second input argument, "prefix" can be empty
// but it is usually the app's name and a single dot.
NewClient(writeCloser io.WriteCloser, prefix string) *Client
Client {
    SetMaxPackageSize(maxPacketSize int)
    SetFormatter(fmt func(metricName string) string)
    FlushEvery(dur time.Duration)

    IsClosed() bool
    Close() error

    WriteMetric(metricName, value, typ string, rate float32) error
    Flush(n int) error

    Count(metricName string, value int) error
    Increment(metricName string) error

    Gauge(metricName string, value int) error

    Unique(metricName string, value int) error

    Time(metricName string, value time.Duration) error
    Record(metricName string, rate float32) func() error

    Histogram(metricName string, value int) error
}

Metric Value helpers

Duration(v time.Duration) string
Int(v int) string
Int8(v int8) string
Int16(v int16) string
Int32(v int32) string
Int64(v int64) string
Uint(v uint) string
Uint8(v uint8) string
Uint16(v uint16) string
Uint32(v uint32) string
Uint64(v uint64) string
Float32(v float32) string
Float64(v float64) string

Metric Type constants

const (
    // Count is the "c" Counting statsd metric type.
    Count string = "c"
    // Gauge is the "g" Gauges statsd metric type.
    Gauge string = "g"
    // Unique is the "s" Sets statsd metric type.
    Unique string = "s"
    // Set is an alias for "Unique"
    Set = Unique
    // Time is the "ms" Timing statsd metric type.
    Time string = "ms"
    // Histogram is the "h" metric type,
    // difference from `Time` metric type is that `Time` writes milleseconds.
    // Read more at: https://docs.netdata.cloud/collectors/statsd.plugin/
    Histogram string = "h"
)

Read more at: https://github.com/etsy/statsd/blob/master/docs/metric_types.md

Example

Assuming you have a statsd server running at :8125 (default port).

# assume the following codes in example.go file
$ cat example.go
package main

import (
	"fmt"
	"net/http"
	"strings"
	"time"

	"github.com/netdata/statsd"
)


// statusCodeReporter is a compatible `http.ResponseWriter`
// which stores the `statusCode` for further reporting.
type statusCodeReporter struct {
    http.ResponseWriter
    written    bool
    statusCode int
}

func (w *statusCodeReporter) WriteHeader(statusCode int) {
    if w.written {
        return
    }

    w.statusCode = statusCode
    w.ResponseWriter.WriteHeader(statusCode)
}

func (w *statusCodeReporter) Write(b []byte) (int, error) {
    w.written = true
    return w.ResponseWriter.Write(b)
}

func main() {
    statsWriter, err := statsd.UDP(":8125")
    if err != nil {
        panic(err)
    }

    statsD := statsd.NewClient(statsWriter, "prefix.")
    statsD.FlushEvery(5 * time.Second)

    statsDMiddleware := func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            path := r.URL.Path
            if len(path) == 1 {
                path = "index" // for root.
            } else if path == "/favicon.ico" {
                next.ServeHTTP(w, r)
                return
            } else {
                path = path[1:]
                path = strings.Replace(path, "/", ".", -1)
            }

            statsD.Increment(fmt.Sprintf("%s.request", path))

            newResponseWriter := &statusCodeReporter{ResponseWriter: w, statusCode: http.StatusOK}

            stop := statsD.Record(fmt.Sprintf("%s.time", path), 1)
            next.ServeHTTP(newResponseWriter, r)
            stop()

            statsD.Increment(fmt.Sprintf("%s.response.%d", path, newResponseWriter.statusCode))
        })
    }

    mux := http.DefaultServeMux

    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Fprintln(w, "Hello from index")
    })

    mux.HandleFunc("/other", func(w http.ResponseWriter, r *http.Request) {
        statsD.Unique("other.unique", 1)
        fmt.Fprintln(w, "Hello from other page")
    })

    http.ListenAndServe(":8080", statsDMiddleware(mux))
}
# run example.go and visit http://localhost:8080/other
$ go run example.go

Navigate here to see more examples.

License

The go-statsd library is licensed under the MIT License.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.