kubismus

README

kubismus

Kubismus is a go package that makes it easy to display status metrics using Cubism.js. ("Kubismus" is the German word for "cubism".)

Checkout the sample code: ktest.go

Screen Shot

Defining the HTTP Handler

To get started with all defaults, simply register the HTTP handler and serve HTTP:

kubismus.HandleHTTP()
go http.ListenAndServe(":8080", nil)

This creates an endpoint at http://localhost:8080/kubismus that will register information you log.

If you need a custom endpoint, use kubismus.ServeHTTP directly:

http.Handle("/", http.HandlerFunc(kubismus.ServeHTTP))

Adding Data

Kubismus shows graphs and a table of data. You can add entries to these at any time. To add an entry to the table that shows the number of goroutines:

kubismus.Note("Goroutines", fmt.Sprintf("%d", runtime.NumGoroutine()))

To add an entry to a graph:

kubismus.Metric("Metric Name", count, value)

By default, each metric has a count, average, and sum graph. To configure which graphs to show, use the Define method:

kubismus.Define("Posts", kubismus.COUNT, "HTTP Posts")
kubismus.Define("Posts", kubismus.SUM, "Bytes Posted")

Adding metrics and table entries use channels and are thread-safe. Graphs for new metrics may not appear until a browser refresh.

Customizing the Title

You can configure the status page's icon and title:

kubismus.Setup("My Cool Utility", "/web/kubismus36.png")

Documentation

Overview

Package kubismus makes it simple to embed a status page in your web service. Using D3 and Cubism, events are stored and then rendered on a dynamic display.

Index

• Constants
• func Define(reading string, op Op, DisplayName string)
• func GetMetrics(name string, op Op) []float64
• func GetNotes() []note
• func HandleHTTP()
• func HttpRequestMetric(reading string, h http.Handler) http.Handler
• func HttpResponseMetric(reading string, h http.Handler) http.Handler
• func Metric(reading string, count int32, value float64)
• func Note(name, value string)
• func ReleaseMetrics(m []float64)
• func ReleaseNotes(n []note)
• func ServeHTTP(w http.ResponseWriter, r *http.Request)
• func Setup(title, image string)
• type Op
  • func (op Op) String() string

Constants

const (
	// DefaultPath is the default path on the URL to get to the Kubismus display.
	DefaultPath = "/kubismus/"
)

Functions

func Define

func Define(reading string, op Op, DisplayName string)

Define defines a metric with a given operation and display name. This allows you to provide a different name for the count, average, or sum - and control which are displayed.

func GetMetrics

func GetMetrics(name string, op Op) []float64

GetMetrics returns a list of values for a metric.

func GetNotes

func GetNotes() []note

GetNotes returns the currently defined notes.

func HandleHTTP

func HandleHTTP()

HandleHTTP registers an HTTP handler for kubismus on the default path. It is still necessary to invoke http.Serve(), typically in a go statement.

func HttpRequestMetric

func HttpRequestMetric(reading string, h http.Handler) http.Handler

HttpRequestMetric returns a handler that logs a metric for the incoming content length after invoking the handler h.

func HttpResponseMetric

func HttpResponseMetric(reading string, h http.Handler) http.Handler

HttpResponseMetric returns a handler that logs a metric for the response content length after invoking the handler h

func Metric

func Metric(reading string, count int32, value float64)

Metric records a count and total value for a given reading. count should be 1 unless you are providing summed data for multiple events as the value. For instance, you can send the total bytes read for 3 files at one time.

func Note

func Note(name, value string)

Note logs a specific value to show in a table.

func ReleaseMetrics

func ReleaseMetrics(m []float64)

ReleaseMetrics returns the slice of values to the leaky buffer, if possible. While not required, using it reduces work for the garbage collector.

func ReleaseNotes

func ReleaseNotes(n []note)

ReleaseNotes returns the slice to the leaky buffer, if possible.

func ServeHTTP

func ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP servers HTTP requests for kubismus.

func Setup

func Setup(title, image string)

Setup sets the basic parameters for the graph page.

Types

type Op

type Op int

Op specifies the operation for the metric - count, average, or sum.

const (
	COUNT Op = 1 << iota
	AVERAGE
	SUM
)

Op types

func (Op) String

func (op Op) String() string

String converts an Op to a string value.