gomon

README

gomon

gomon is a package that simplifies the process of sending metrics to AWS CloudWatch. It provides a few things:

• A registry and event loop that collects monitoring data as frequently as you like, then batches them up to be periodically delivered to AWS, minimizing API calls and cost, while preserving granularity.
• Helper functions to aggregate and transform metric data in useful ways.
• A few prepackaged monitors to collect basic system data like disk and memory statistics, so that you don't need to set up redundant monitoring scripts to get OS metrics in addition to application-specific ones.

How To Use

Prerequisites

You must have a set of AWS credentials that allow the PutMetricData API call on the resources you want to create. The following IAM policy should work:

{
  "Statement" : [
    {
      "Effect" : "Allow",
      "Action" : "cloudwatch:PutMetricData",
      "Resource" : "*"
    }
  ]
}

Make sure these credentials are exported as environment variables at AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

Register Emitters

Choose some metrics you want to watch, and call one of the Register* functions, passing it a method value or anonymous function that when called, returns the current value of the metric. Given a function in myapp called ConnectionCount(), to track its value 60 times per second, you would register as:

gomon.RegisterInt("CurrentConnections", 60, "Count", myapp.ConnectionCount)

or, to report on something more complicated:

currentRegisteredUsers := func() int { return currentUsers() - currentGuests() }
gomon.RegisterInt("CurrentRegisteredUsers", 60, "Count", currentRegisteredUsers)

If you have a metric which represents some sort of accumulating total, you can use DeltaSinceLastCall() to track its rate of change. For example:

processedSinceLastCall = DeltaSinceLastCall(myapp.TotalJobsProcessed)
gomon.Register("JobsProcessedPerMinute", 1, "Count", ProcessedSinceLastCall)

There's an equivalent shorthand for the above common pattern:

gomon.RegisterDelta("JobsProcessedPerMinute", 1, "Count", myapp.TotalJobsProcessed)

Enable Dimensions

Cloudwatch datapoints frequently have Dimensions attached to them to characterize the data, e.g. marking which server it came from or what application produced it. You can add dimensions that will be present in all transmitted data:

gomon.AddDimension("InstanceId", "i-31a74258")
gomon.AddDimension("ApplicationName", "MyApp")

Start Sending

After all emitters are registered, start the loop with gomon.Start().

Documentation

Overview

Package gomon adds functionality to aggregate and batch groups of metrics for delivery to AWS Cloudwatch.

Index

• Constants
• Variables
• func AddDimension(name, value string)
• func DeltaSinceLastCall(getter func() float64) (generator func() float64)
• func MbFreeAtMount(mountpoint string) int
• func MemoryFree() float64
• func Register(name string, interval time.Duration, unit string, floatEmitter func() float64)
• func RegisterDelta(name string, interval time.Duration, unit string, floatEmitter func() float64)
• func RegisterDeltaInt(name string, interval time.Duration, unit string, intEmitter func() int)
• func RegisterInt(name string, interval time.Duration, unit string, intEmitter func() int)
• func RootPartitionFree() float64
• func Start()
• type Aggregator
  • func (m *Aggregator) StartLoop()
  • func (a *Aggregator) String() string

Constants

const ShouldTransmitZero = true

If this is false, periods in which a given metric is always zero will not result in an API transmission. This will save money and bandwidth, but any alarms that depend on a quiescent system (such as a a scale-down event when a metric is low) might not fire, since the alarm will go into INSUFFICENT_DATA without any metrics.

Variables

var Dimensions = []cloudwatch.Dimension{}

A set of AWS Dimensions that are added to all sent metrics.

var Namespace string

A common prefix for the metrics gathered by this app.

var Region = aws.USEast

The Cloudwatch region to use.

Functions

func AddDimension

func AddDimension(name, value string)

AddDimension adds a dimension to all delivered metrics. A good thing to use would be something like StackName or InstanceId.

func DeltaSinceLastCall

func DeltaSinceLastCall(getter func() float64) (generator func() float64)

DeltaSinceLastCall transforms a function returning a metric count into a function that returns the difference since the last time that function was called.

func MbFreeAtMount

func MbFreeAtMount(mountpoint string) int

MbFreeAtMount parses `df -m` for the given mount and returns the MB free in that directory.

func MemoryFree

func MemoryFree() float64

MemoryFree returns the number of MB reported as 'available' by the unix `free` command.

func Register

func Register(name string, interval time.Duration, unit string, floatEmitter func() float64)

Register builds an Aggregator instance and adds it to the registry.

func RegisterDelta

func RegisterDelta(name string, interval time.Duration, unit string, floatEmitter func() float64)

RegisterDelta wraps an emitter with DeltaSinceLastCall to turn it into a rate measurement instead of a point in time metric.

func RegisterDeltaInt

func RegisterDeltaInt(name string, interval time.Duration, unit string, intEmitter func() int)

RegisterDeltaInt is RegisterDelta for ints.

func RegisterInt

func RegisterInt(name string, interval time.Duration, unit string, intEmitter func() int)

RegisterInt is a convenience function that wraps int emitters with a float cast.

func RootPartitionFree

func RootPartitionFree() float64

RootPartitionFree returns the space in MB available on '/'.

func Start

func Start()

Start begins collecting and batching metrics from all aggregators.

Types

type Aggregator

type Aggregator struct {
	// contains filtered or unexported fields
}

An Aggregator takes a fast stream of data points and batches them into a slower stream of statistical descriptions of those points.

func (*Aggregator) StartLoop

func (m *Aggregator) StartLoop()

StartLoop begins listening on the fast channel until one minute's worth of data is available, then sends the stats for that duration on the batch channel and repeats. If all metrics for the duration are zero, optionally discard the values.

func (*Aggregator) String

func (a *Aggregator) String() string