trapmetrics

README

Package go-trapmetrics

A simplified, streamlined, and updated replacement for circonus-gometrics. Covers basic functionality for collecting and submitting metrics to Circonus.

package main

import (
    "fmt"

    apiclient "github.com/circonus-labs/go-apiclient"
    trapcheck "github.com/maier/go-trapcheck"
)

func main() {

    client, err := apiclient.New(&apiclient.Config{/* ...settings... */})
    if err != nil {
        panic(err)
    }

    check, err := trapcheck.New(&trapcheck.Config{Client: client, /* ...other settings... */})
    if err != nil {
        panic(err)
    }

    metrics, err := trapmetrics.New(&trapmetrics.Config{Check: check, /* ...other settings...*/})
    if err != nil {
        panic(err)
    }

    // NOTE: gauges and text take an optional timestamp for the sample, pass nil to use current time
    ts := time.Now()    
    metrics.GaugeSet("gauge",trapmetrics.Tags{{Category:"a",Value:"b"}},123,&ts)
    metrics.TextSet("text",nil,"some text",nil)

    // Counters and histograms will apply a timestamp at the time of flushing as they only contain
    // one stample and it is mutable until flush time.
    metrics.CounterIncrement("counter",trapmetrics.Tags{{Cateogry:"a",Value:"b"}})
    metrics.HistogramRecordValue("histogram",nil,27)
    metrics.CumulativeHistogramRecordCountForValue("cumulative_histogram",nil,128,3.6)

    result, err := metrics.Flush()
    if err != nil {
        panic(err)
    }

    fmt.Println(result)
}

Documentation

Index

• type Config
• type LogWrapper
  • func (lw *LogWrapper) Debugf(fmt string, v ...interface{})
  • func (lw *LogWrapper) Errorf(fmt string, v ...interface{})
  • func (lw *LogWrapper) Infof(fmt string, v ...interface{})
  • func (lw *LogWrapper) Printf(fmt string, v ...interface{})
  • func (lw *LogWrapper) Warnf(fmt string, v ...interface{})
• type Logger
• type Metric
  • func (m *Metric) String() string
• type Metrics
• type Result
• type Samples
• type Tag
  • func (t *Tag) Encode() string
  • func (t *Tag) String() string
• type Tags
  • func (tt *Tags) Encode() string
  • func (tt *Tags) Stream() string
  • func (tt *Tags) String() string
• type Trap
• type TrapMetrics
  • func New(cfg *Config) (*TrapMetrics, error)
  • func (tm *TrapMetrics) CounterAdjustByValue(name string, tags Tags, val int64) error
  • func (tm *TrapMetrics) CounterFetch(name string, tags Tags) (*Metric, error)
  • func (tm *TrapMetrics) CounterIncrement(name string, tags Tags) error
  • func (tm *TrapMetrics) CounterIncrementByValue(name string, tags Tags, val uint64) error
  • func (tm *TrapMetrics) CumulativeHistogramFetch(name string, tags Tags) (*Metric, error)
  • func (tm *TrapMetrics) CumulativeHistogramRecordCountForValue(name string, tags Tags, count int64, val float64) error
  • func (tm *TrapMetrics) Flush(ctx context.Context) (*Result, error)
  • func (tm *TrapMetrics) GaugeAdd(name string, tags Tags, val interface{}, ts *time.Time) error
  • func (tm *TrapMetrics) GaugeFetch(name string, tags Tags) (*Metric, error)
  • func (tm *TrapMetrics) GaugeSet(name string, tags Tags, val interface{}, ts *time.Time) error
  • func (tm *TrapMetrics) HistogramFetch(name string, tags Tags) (*Metric, error)
  • func (tm *TrapMetrics) HistogramRecordCountForValue(name string, tags Tags, count int64, val float64) error
  • func (tm *TrapMetrics) HistogramRecordDuration(name string, tags Tags, val time.Duration) error
  • func (tm *TrapMetrics) HistogramRecordTiming(name string, tags Tags, val float64) error
  • func (tm *TrapMetrics) HistogramRecordValue(name string, tags Tags, val float64) error
  • func (tm *TrapMetrics) JSONMetrics() ([]byte, error)
  • func (tm *TrapMetrics) TextFetch(name string, tags Tags) (*Metric, error)
  • func (tm *TrapMetrics) TextSet(name string, tags Tags, val string, ts *time.Time) error

Types

type Config

type Config struct {
	// Trap instance of go-trapcheck (or something satisfying Trap interface) to use trapmetrics as a
	// metric container and handle transport externally, pass nil
	Trap Trap

	// Logger instance of something satisfying Logger interface (default: log.Logger with ioutil.Discard)
	Logger Logger

	// GlobalTags is a list of tags to be added to every metric
	GlobalTags Tags

	// BufferSize size of metric buffer (when flushing), default is defaultBufferSize above
	BufferSize uint
}

type LogWrapper

type LogWrapper struct {
	Log   *log.Logger
	Debug bool
}

LogWrapper is a wrapper around Go's log.Logger

func (*LogWrapper) Debugf

func (lw *LogWrapper) Debugf(fmt string, v ...interface{})

func (*LogWrapper) Errorf

func (lw *LogWrapper) Errorf(fmt string, v ...interface{})

func (*LogWrapper) Infof

func (lw *LogWrapper) Infof(fmt string, v ...interface{})

func (*LogWrapper) Printf

func (lw *LogWrapper) Printf(fmt string, v ...interface{})

func (*LogWrapper) Warnf

func (lw *LogWrapper) Warnf(fmt string, v ...interface{})

type Logger

type Logger interface {
	Printf(fmt string, v ...interface{})
	Debugf(fmt string, v ...interface{})
	Infof(fmt string, v ...interface{})
	Warnf(fmt string, v ...interface{})
	Errorf(fmt string, v ...interface{})
}

Logger is a generic logging interface

type Metric

type Metric struct {
	Samples Samples
	Name    string
	Mtype   string // set by interface methods
	Rtype   string // set by interface methods
	Tags    Tags
	ID      uint64
}

func (*Metric) String

func (m *Metric) String() string

type Metrics

type Metrics map[uint64]*Metric

type Result

type Result struct {
	CheckUUID       string
	Error           string
	SubmitUUID      string
	Filtered        uint64
	Stats           uint64
	SubmitDuration  time.Duration
	LastReqDuration time.Duration
	EncodeDuration  time.Duration
	FlushDuration   time.Duration
	BytesSent       int
}

type Samples

type Samples map[uint64]interface{}

type Tag

type Tag struct {
	Category string
	Value    string
}

func (*Tag) Encode

func (t *Tag) Encode() string

Encode returns a base64 encoded tag

func (*Tag) String

func (t *Tag) String() string

String returns a string representation of tag

type Tags

type Tags []Tag

func (*Tags) Encode

func (tt *Tags) Encode() string

Stream returns a base64 encoded string list representation of tags

func (*Tags) Stream

func (tt *Tags) Stream() string

Stream returns a streamtag encoded string list representation of tags

func (*Tags) String

func (tt *Tags) String() string

String returns a sorted, string list representation of tags

type Trap

type Trap interface {
	SendMetrics(ctx context.Context, metrics *strings.Builder) (*trapcheck.TrapResult, error)
}

Trap defines the interface for for submitting metrics

type TrapMetrics

type TrapMetrics struct {
	Log Logger
	// contains filtered or unexported fields
}

func New

func New(cfg *Config) (*TrapMetrics, error)

func (*TrapMetrics) CounterAdjustByValue

func (tm *TrapMetrics) CounterAdjustByValue(name string, tags Tags, val int64) error

CounterAdjustByValue will adjust the named counter by the passed value

func (*TrapMetrics) CounterFetch

func (tm *TrapMetrics) CounterFetch(name string, tags Tags) (*Metric, error)

CounterFetch will return the metric identified by name and tags

func (*TrapMetrics) CounterIncrement

func (tm *TrapMetrics) CounterIncrement(name string, tags Tags) error

CounterIncrement will increment the named counter by 1

func (*TrapMetrics) CounterIncrementByValue

func (tm *TrapMetrics) CounterIncrementByValue(name string, tags Tags, val uint64) error

CounterIncrementByValue will increment the named counter by the passed value

func (*TrapMetrics) CumulativeHistogramFetch

func (tm *TrapMetrics) CumulativeHistogramFetch(name string, tags Tags) (*Metric, error)

CumulativeHistogramFetch will return the metric identified by name and tags

func (*TrapMetrics) CumulativeHistogramRecordCountForValue

func (tm *TrapMetrics) CumulativeHistogramRecordCountForValue(name string, tags Tags, count int64, val float64) error

CumulativeHistogramRecordCountForValue add count n for value to histogram

func (*TrapMetrics) Flush

func (tm *TrapMetrics) Flush(ctx context.Context) (*Result, error)

Flush sends metrics to the configured trap check, returns result or an error

func (*TrapMetrics) GaugeAdd

func (tm *TrapMetrics) GaugeAdd(name string, tags Tags, val interface{}, ts *time.Time) error

GaugeAdd adds a sample with a given timestamp for a gauge to the passed value

func (*TrapMetrics) GaugeFetch

func (tm *TrapMetrics) GaugeFetch(name string, tags Tags) (*Metric, error)

GaugeFetch will return the metric identified by name and tags

func (*TrapMetrics) GaugeSet

func (tm *TrapMetrics) GaugeSet(name string, tags Tags, val interface{}, ts *time.Time) error

GaugeSet sets a sample with a given timestamp for a gauge to the passed value

func (*TrapMetrics) HistogramFetch

func (tm *TrapMetrics) HistogramFetch(name string, tags Tags) (*Metric, error)

HistogramFetch will return the metric identified by name and tags

func (*TrapMetrics) HistogramRecordCountForValue

func (tm *TrapMetrics) HistogramRecordCountForValue(name string, tags Tags, count int64, val float64) error

HistogramRecordCountForValue add count n for value to histogram

func (*TrapMetrics) HistogramRecordDuration

func (tm *TrapMetrics) HistogramRecordDuration(name string, tags Tags, val time.Duration) error

HistogramRecordDuration adds value to histogram (duration is normalized to time.Second, but supports nanosecond granularity)

func (*TrapMetrics) HistogramRecordTiming

func (tm *TrapMetrics) HistogramRecordTiming(name string, tags Tags, val float64) error

HistogramTiming adds timing value to histogram

func (*TrapMetrics) HistogramRecordValue

func (tm *TrapMetrics) HistogramRecordValue(name string, tags Tags, val float64) error

HistogramRecordValue adds value to histogram

func (*TrapMetrics) JSONMetrics

func (tm *TrapMetrics) JSONMetrics() ([]byte, error)

JSONMetrics returns the current metrics in JSON format or an error - to be used when handling submission of metrics externally (e.g. aggregating multiple sets of metrics from different trapmetrics containers)

func (*TrapMetrics) TextFetch

func (tm *TrapMetrics) TextFetch(name string, tags Tags) (*Metric, error)

TextFetch will return the metric identified by name and tags

func (*TrapMetrics) TextSet

func (tm *TrapMetrics) TextSet(name string, tags Tags, val string, ts *time.Time) error

TextSet sets a sample with a given timestamp for a text to the passed value