stats

README

Stats - Go middleware to collect HTTP stats

Features

• Stats Middleware that can be plugged into your http stack
• Collects HTTP request and repsponse stats with default implementation.
• Support to provide your own implementation of stats collection to suit your application needs
• HttpHandler that serves "/stats" endpoint.
• build on top of coda-hale's metrics library - http://github.com/codahale/metrics
• Outputs metrics in Influxdb Line protocol, JSON, Graphite format. (Currently only supports influxdb line protocol: https://github.com/influxdata/influxdb/blob/master/tsdb/README.md)
• Examples to demonstrate application and request level metrics collection.
• github.com/supershal/stats/metrics package can be used to collect metrics for non-http apps. For example, Database stats can be collected using metrics package.

Installation

1. Install Go Version >=1.5.1
2. Make sure you have installed git, hg etc.
3. Your workspace is setup with GOPATH. http://golang.org/doc/code.html
4. Download it:

   go get github.com/supershal/stats
   

GoDoc

• stats
• metircs

Usage

HTTP middleware provided to collect stats. Currently it supports alice and Negroni(https://github.com/codegangsta/negroni) compatible middlewares. However, its very easy to create your own middleware function for your framework.(Checkout middleware.go)

1. Add HttpStats middleware in your HTTP app

Following example is using 'alice' middleware chaining. Checkout /example for more details.

		func middlewares() alice.Chain {
			host, _ := os.Hostname()
			tags := map[string]string{
			"host": host,
		}
		s := stats.NewHTTPStats(tags)
		return alice.New(s.HTTPStatsHandler)
		}

1. Serve metrics on separate HTTP server.

		stats.ServeMetrics(5555, "/metrics") 

A metric collector agent collectd or telegraf can invoke localhost:5555/metrics periodically and send metrics back to TSDB (influxdb or graphite).

Output Influxdb example

https://github.com/influxdata/influxdb/blob/master/tsdb/README.md

http_request,host=localhost,foo=bar GET=10
http_request,host=localhost,foo=bar POST=5 
http_response,host=localhost,foo=bar 200=5
http_response,host=localhost,foo=bar 503=2
http_response,host=localhost,foo=bar 403=3
http_response,host=localhost,foo=bar total=10
http_response,host=localhost,foo=bar latency.P50=10
http_response,host=localhost,foo=bar latency.P75=15
http_response,host=localhost,foo=bar latency.P90=20
http_response,host=localhost,foo=bar latency.P95=25
http_response,host=localhost,foo=bar latency.P99=40
http_response,host=localhost,foo=bar latency.P999=50

Create PR or new issue for any feature request or bugs.

Documentation

Index

• func HTTPMetricsSnapshotLines() string
• func ServeMetrics(port int, path string) error
• type HTTPRequestStatFunc
• type HTTPResponseStatCollector
• type HTTPResponseStatFunc
• type HTTPStats
  • func NewHTTPStats(tags map[string]string) *HTTPStats
  • func (s *HTTPStats) HTTPStatsHandler(next http.Handler) http.Handler
  • func (s *HTTPStats) ServeHTTP(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)
• type StatsWriter
  • func (l *StatsWriter) Header() http.Header
  • func (l *StatsWriter) Latency() time.Duration
  • func (l *StatsWriter) Size() int
  • func (l *StatsWriter) Status() int
  • func (l *StatsWriter) Write(b []byte) (int, error)
  • func (l *StatsWriter) WriteHeader(s int)

Functions

func HTTPMetricsSnapshotLines

func HTTPMetricsSnapshotLines() string

HTTPMetricsSnapshot returns all colleted metrics in metrics Line protocol format. https://github.com/influxdata/influxdb/blob/master/tsdb/README.md

func ServeMetrics

func ServeMetrics(port int, path string) error

ServeMetrics starts Http server to provide current metrics in influxdb line protocol format. It takes port number and path as input.: example ServeMetrics(8081, "/metrics").

Types

type HTTPRequestStatFunc

type HTTPRequestStatFunc func(r http.Request, tags map[string]string)

HTTPRequestStatFunc function type to collect HTTP request metrics. An application can implement this function to provide custom implementation of request metrics collection.

type HTTPResponseStatCollector

type HTTPResponseStatCollector interface {
	http.ResponseWriter
	Status() int
	Size() int
	Latency() time.Duration
}

HTTPResponseStatCollector interface provides methods to collect http response metrics.

type HTTPResponseStatFunc

type HTTPResponseStatFunc func(w http.ResponseWriter, tags map[string]string)

HTTPResponseStatFunc function type to collect HTTP response metrics. An application can implement this function to provide custom implementation of response metrics collection.

type HTTPStats

type HTTPStats struct {
	GlobalTags      map[string]string
	LogRequestStat  HTTPRequestStatFunc
	LogResponseStat HTTPResponseStatFunc
}

HTTPStats to provide global tags to each metrics and configure custom request and response stats functions.

func NewHTTPStats

func NewHTTPStats(tags map[string]string) *HTTPStats

NewHTTPStats provides new instance of HTTPStats

func (*HTTPStats) HTTPStatsHandler

func (s *HTTPStats) HTTPStatsHandler(next http.Handler) http.Handler

HTTPStatsHandler is a default provided HTTP middleware function to collect global http request and response stats.

func (*HTTPStats) ServeHTTP

func (s *HTTPStats) ServeHTTP(w http.ResponseWriter, r *http.Request, next http.HandlerFunc)

ServeHTTP is Negroni compatible interface for httpStats middleware

type StatsWriter

type StatsWriter struct {
	Writer    http.ResponseWriter
	StartTime time.Time
	// contains filtered or unexported fields
}

statsWriter implements HTTPResponseStatCollector and collects response code, size and latency.

func (*StatsWriter) Header

func (l *StatsWriter) Header() http.Header

Header returns the header map that will be sent by WriteHeader. Changing the header after a call to WriteHeader (or Write) has no effect unless the modified headers were declared as trailers by setting the "Trailer" header before the call to WriteHeader (see example). To suppress implicit response headers, set their value to nil.

func (*StatsWriter) Latency

func (l *StatsWriter) Latency() time.Duration

Latency provides response time.

func (*StatsWriter) Size

func (l *StatsWriter) Size() int

Size function return current response size in bytes

func (*StatsWriter) Status

func (l *StatsWriter) Status() int

Status function returns current http status code

func (*StatsWriter) Write

func (l *StatsWriter) Write(b []byte) (int, error)

Write writes the data to the connection as part of an HTTP reply. If WriteHeader has not yet been called, Write calls WriteHeader(http.StatusOK) before writing the data. If the Header does not contain a Content-Type line, Write adds a Content-Type set to the result of passing the initial 512 bytes of written data to DetectContentType.

func (*StatsWriter) WriteHeader

func (l *StatsWriter) WriteHeader(s int)

WriteHeader sends an HTTP response header with status code. If WriteHeader is not called explicitly, the first call to Write will trigger an implicit WriteHeader(http.StatusOK). Thus explicit calls to WriteHeader are mainly used to send error codes.