appoptics

README

This is a reporter for the go-metrics library which posts the metrics to AppOptics. It is based on ysamlan's AppOptics reporter, which was based on mihaysa's Librato reporter.

Usage

import "github.com/appoptics/go-metrics-appoptics"

go appoptics.AppOptics(metrics.DefaultRegistry,
    10*time.Second,              // interval for uploads
    "token",                     // AppOptics API token
    map[string]string{
        "hostname": "localhost", // tags
    }, 
    []float64{0.95},             // percentiles to send
    time.Millisecond,            // time units for timers
    "myservicename.",            // prefix on reported metric names
    nil,                         // (optional) go-metrics runtime.* stats upload whitelist
)

Features

Metric Name Prefix: This reporter supports a prefix argument when initializing. All uploaded metrics will have that prefix prepended to their names. Use "" if you don't want this behavior.

Tags: Tags passed during the initialization are attached to all this reporter's measurements to AppOptics.

Tags can also be created on a per-metric level using the .Tag() function, for example:

appoptics.Metric("myMetric").Tag("tagA", "foo").Tag("tagB", "bar").Meter().Mark()

Or, to create a histogram with a custom sample type:

appoptics.Metric("myMetric").Tag("tag", "foo").WithSample(func() metrics.Sample { return metrics.NewUniformSample(1000) }).Histogram().Update(100)

Selective runtime metric uploading: If you're using go-metrics' CaptureRuntimeMemStats feature, it's great and automates collecting a lot of useful data. Unfortunately, it also adds 30 metrics, which can eat up a lot of metric hours with AppOptics. The runtimeMetricsWhiteleist parameter lets you cherry-pick which metrics actually get uploaded, without needing to manually collect them yourself. See the source for possible values. Pass nil to allow all, and an empty slice to disable uploads for all runtime. metrics.

Migrating from Librato and the rcrowley/go-metrics / mihasya/go-metrics-librato implementation

Source-based metrics are not supported in AppOptics. To migrate from the old Librato reporter (only with tags instead of sources):

• Change the import to "github.com/appoptics/go-metrics-appoptics"
• Change librato.Librato to appoptics.AppOptics
• Remove the email argument from the appoptics.AppOptics function call (the updated AppOptics API only requires the token)
• Change the source argument from a string into a map[string]string for tags - e.g. a source "myhostname" could become the tag map[string]string{"host":"myhostname"}).
• Use "" for the metric name prefix.
• Use nil for the runtime-metric-name whitelist (allow-all).

Documentation

Index

• Constants
• func AppOptics(registry metrics.Registry, interval time.Duration, token string, ...)
• func SetHTTPClient(c *http.Client)
• type AppOpticsClient
  • func NewAppOpticsClient(token, measurementsURI string) *AppOpticsClient
  • func (self *AppOpticsClient) PostMetrics(batch Batch) (err error)
• type Batch
• type Measurement
• type Reporter
  • func NewReporter(registry metrics.Registry, interval time.Duration, token string, ...) *Reporter
  • func (self *Reporter) BuildRequest(now time.Time, r metrics.Registry) (batch Batch, err error)
  • func (self *Reporter) Run()
• type TaggedMetric
  • func Metric(name string) *TaggedMetric
  • func (t *TaggedMetric) Counter() metrics.Counter
  • func (t *TaggedMetric) Gauge() metrics.Gauge
  • func (t *TaggedMetric) Gauge64() metrics.GaugeFloat64
  • func (t *TaggedMetric) Histogram() metrics.Histogram
  • func (t *TaggedMetric) Meter() metrics.Meter
  • func (t *TaggedMetric) String() string
  • func (t *TaggedMetric) Tag(name string, value interface{}) *TaggedMetric
  • func (t *TaggedMetric) Timer() metrics.Timer
  • func (t *TaggedMetric) WithSample(s func() metrics.Sample) *TaggedMetric

Constants

const (
	// display attributes
	Color             = "color"
	DisplayMax        = "display_max"
	DisplayMin        = "display_min"
	DisplayUnitsLong  = "display_units_long"
	DisplayUnitsShort = "display_units_short"
	DisplayStacked    = "display_stacked"
	DisplayTransform  = "display_transform"
	// special gauge display attributes
	SummarizeFunction = "summarize_function"
	Aggregate         = "aggregate"

	// metric keys
	Name        = "name"
	Period      = "period"
	Description = "description"
	DisplayName = "display_name"
	Attributes  = "attributes"

	// measurement keys
	Time  = "time"
	Tags  = "tags"
	Value = "value"

	// special gauge keys
	Count  = "count"
	Sum    = "sum"
	Max    = "max"
	Min    = "min"
	StdDev = "stddev"

	// batch keys
	Measurements = "measurements"
)

property strings

const Operations = "operations"

const OperationsShort = "ops"

const PartialFailureHeader = "x-partial-failure"

Functions

func AppOptics

func AppOptics(registry metrics.Registry, interval time.Duration, token string, tags map[string]string,
	percentiles []float64, timeUnits time.Duration, prefix string, whitelistedRuntimeMetrics []string, measurementsURI string)

Call in a goroutine to start metric uploading. Using whitelistedRuntimeMetrics: a non-nil value sets this reporter to upload only a subset of the runtime.* metrics that are gathered by go-metrics runtime memory stats (CaptureRuntimeMemStats). The full list of possible values is at https://github.com/rcrowley/go-metrics/blob/master/runtime.go#L181-L211 Passing an empty slice disables uploads for all runtime.* metrics.

func SetHTTPClient

func SetHTTPClient(c *http.Client)

Types

type AppOpticsClient

type AppOpticsClient struct {
	Token           string
	MeasurementsURI string
}

func NewAppOpticsClient

func NewAppOpticsClient(token, measurementsURI string) *AppOpticsClient

func (*AppOpticsClient) PostMetrics

func (self *AppOpticsClient) PostMetrics(batch Batch) (err error)

type Batch

type Batch struct {
	Measurements []Measurement     `json:"measurements,omitempty"`
	Time         int64             `json:"time"`
	Tags         map[string]string `json:"tags"`
}

type Measurement

type Measurement map[string]interface{}

type Reporter

type Reporter struct {
	Token                     string
	Tags                      map[string]string
	Interval                  time.Duration
	Registry                  metrics.Registry
	Percentiles               []float64              // percentiles to report on histogram metrics
	Prefix                    string                 // prefix metric names for upload (eg "servicename.")
	WhitelistedRuntimeMetrics map[string]bool        // runtime.* metrics to upload (nil = allow all)
	TimerAttributes           map[string]interface{} // units in which timers will be displayed
	// contains filtered or unexported fields
}

func NewReporter

func NewReporter(registry metrics.Registry, interval time.Duration, token string, tags map[string]string,
	percentiles []float64, timeUnits time.Duration, prefix string, whitelistedRuntimeMetrics []string, measurementsURI string) *Reporter

func (*Reporter) BuildRequest

func (self *Reporter) BuildRequest(now time.Time, r metrics.Registry) (batch Batch, err error)

func (*Reporter) Run

func (self *Reporter) Run()

type TaggedMetric

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

func Metric

func Metric(name string) *TaggedMetric

func (*TaggedMetric) Counter

func (t *TaggedMetric) Counter() metrics.Counter

func (*TaggedMetric) Gauge

func (t *TaggedMetric) Gauge() metrics.Gauge

func (*TaggedMetric) Gauge64

func (t *TaggedMetric) Gauge64() metrics.GaugeFloat64

func (*TaggedMetric) Histogram

func (t *TaggedMetric) Histogram() metrics.Histogram

func (*TaggedMetric) Meter

func (t *TaggedMetric) Meter() metrics.Meter

func (*TaggedMetric) String

func (t *TaggedMetric) String() string

func (*TaggedMetric) Tag

func (t *TaggedMetric) Tag(name string, value interface{}) *TaggedMetric

func (*TaggedMetric) Timer

func (t *TaggedMetric) Timer() metrics.Timer

func (*TaggedMetric) WithSample

func (t *TaggedMetric) WithSample(s func() metrics.Sample) *TaggedMetric