metrics

Documentation

Overview

Package metrics provides some instrumentation utilities to equip other datamon packages with telemetry and metrics.

Index

• Constants
• func DefaultExporter(opts ...influxdb.Option) view.Exporter
• func Duration(start, end time.Time, measure *stats.Float64Measure, tags ...map[string]string)
• func EnsureMetrics(location string, m interface{}) interface{}
• func Float64(measure *stats.Float64Measure, value float64, tags ...map[string]string)
• func Flush()
• func Inc(counter *stats.Int64Measure, tags ...map[string]string)
• func Init(opts ...Option)
• func Int64(measure *stats.Int64Measure, value int64, tags ...map[string]string)
• func Since(start time.Time, measure *stats.Float64Measure, tags ...map[string]string)
• type Enable
  • func (e *Enable) EnableMetrics(enabled bool)
  • func (e *Enable) EnsureMetrics(name string, m interface{}) interface{}
  • func (e Enable) MetricsEnabled() bool
• type FilesMetrics
  • func (f *FilesMetrics) Inc(operation string)
  • func (f *FilesMetrics) Size(size int64, operation string)
• type FlushExporter
• type IOMetrics
  • func (n *IOMetrics) Failed(operation string)
  • func (n *IOMetrics) IO(start time.Time, operation string)
  • func (n *IOMetrics) IORecord(start time.Time, operation string) func(int64, error)
  • func (n *IOMetrics) Size(size int64, operation string)
  • func (n *IOMetrics) Throughput(start, end time.Time, size int64, operation string)
• type Option
  • func WithBasePath(location string) Option
  • func WithContexter(c func() context.Context) Option
  • func WithExporter(exporter view.Exporter) Option
  • func WithReportingPeriod(d time.Duration) Option
• type UsageMetrics
  • func (u *UsageMetrics) Failed(method string)
  • func (u *UsageMetrics) Inc(method string)
  • func (u *UsageMetrics) Used(start time.Time, method string)
  • func (u *UsageMetrics) UsedAll(start time.Time, method string) func(error)

Constants

const (
	// KB stands for kilo bytes (1024 bytes)
	KB = units.KiB

	// MB stands for mega bytes (1024 kilo bytes)
	MB = units.MiB

	// GB stands for giga bytes (1024 mega bytes)
	GB = units.GiB
)

Functions

func DefaultExporter

func DefaultExporter(opts ...influxdb.Option) view.Exporter

DefaultExporter returns a metrics exporter for an influxdb backend, with db "datamon" and time series "metrics"

func Duration

func Duration(start, end time.Time, measure *stats.Float64Measure, tags ...map[string]string)

Duration feeds a millisecs timing measurement from some start to end timings

func EnsureMetrics

func EnsureMetrics(location string, m interface{}) interface{}

EnsureMetrics allows for lazy registration of metrics definitions.

It may safely be called several times, and only the first registration for a given unique location will be retained.

When running several times, it ensures that all subsequent calls on the same location specify the same metrics type, otherwise it panics.

func Float64

func Float64(measure *stats.Float64Measure, value float64, tags ...map[string]string)

Float64 sets a value to a measurement

func Flush

func Flush()

Flush all collected metrics to backend

func Inc

func Inc(counter *stats.Int64Measure, tags ...map[string]string)

Inc increments a counter-like metric

func Init

func Init(opts ...Option)

Init global settings for metrics collection, such as global tags and exporter setup.

Init is used by any top-level package (such as CLI driver or SDK), to define global settings such as exporter and global tags.

Init may be called multiple times: only the first time matters.

Metrics and views may be registered at init time or later on.

func Int64

func Int64(measure *stats.Int64Measure, value int64, tags ...map[string]string)

Int64 sets a value to a measurement

func Since

func Since(start time.Time, measure *stats.Float64Measure, tags ...map[string]string)

Since feeds a millisecs timing measurement from some start time

Types

type Enable

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

Enable equips any type with some capabilities to collect metrics in a very concise way.

Sample usage:

type myType struct{
  ...
  metrics.Enable
  m *myMetrics // m points to the globally registered metrics collector
}

...

// MyTypeUsage describes a tree of metrics to be recorded on myType
type MyTypeUsage struct {
  Volumetry struct {
    Metadata  FilesMetrics `group:"metadata" description:"some file metrics issued by myType"`
    TestCount *stats.Int64Measure   `metric:"testCount" description:"number of tests" extraviews:"sum"`
  } `group:"volumetry" description:"volumetry measurements that pertain to myType"`
}

func (u *MyTypeUsage) Reads() {
  metrics.Inc(u.Volumetry.Metadata.Read)
}

func (u *MyTypeUsage) Tests(p int) {
  metrics.Int64(u.Volumetry.TestCount, intt64(p))
}

...

func NewMyType() *myType {
  ...
  t := &MyType{}
  t.m := t.EnsureMetrics("MyType", &myMetrics{})
  t.EnableMetrics(true)
  return t
}

func (*Enable) EnableMetrics

func (e *Enable) EnableMetrics(enabled bool)

EnableMetrics toggles metrics collection

func (*Enable) EnsureMetrics

func (e *Enable) EnsureMetrics(name string, m interface{}) interface{}

EnsureMetrics registers a type describing metrics to the global metrics collection. The name argument constructs a new path in the metrics tree.

EnsureMetrics may be called several times, only the first registration will apply.

EnsureMetrics may be called lazily: metrics collection will start only after the first registration.

NOTE: EnsureMetrics will panic if not called with a pointer to a struct.

func (Enable) MetricsEnabled

func (e Enable) MetricsEnabled() bool

MetricsEnabled tells whether metrics are enabled or not

type FilesMetrics

type FilesMetrics struct {
	FileCount *stats.Int64Measure `metric:"fileCount" description:"number of files" extraviews:"sum" tags:"kind,operation"`
	FileSize  *stats.Int64Measure `metric:"fileSize" unit:"bytes" description:"size of files" extraviews:"sum" tags:"kind,operation"`
}

FilesMetrics is common set of metrics reporting about file activity

func (*FilesMetrics) Inc

func (f *FilesMetrics) Inc(operation string)

Inc increments the counter for files

func (*FilesMetrics) Size

func (f *FilesMetrics) Size(size int64, operation string)

Size measures the size of a file

type FlushExporter

type FlushExporter interface {
	view.Exporter
	Flush(*view.Data)
}

FlushExporter is a view exporter that knows how to flush metrics.

This basically means that we may export views concurrently with the default background exporter.

type IOMetrics

type IOMetrics struct {
	Count        *stats.Int64Measure   `metric:"ioCount" description:"number of IO requests" tags:"kind,operation"`
	Timing       *stats.Float64Measure `metric:"timing" unit:"milliseconds" description:"response time in milliseconds" tags:"kind,operation"`
	Failures     *stats.Int64Measure   `metric:"ioFailures" description:"number of failed IOs" tags:"kind,operation"`
	IOSize       *stats.Int64Measure   `metric:"ioSize" unit:"bytes" description:"IO chunk size in bytes" extraviews:"sum" tags:"kind,operation"`
	IOThroughput *stats.Float64Measure `` /* 145-byte string literal not displayed */
}

IOMetrics is a common set of metrics reporting about IO activity

func (*IOMetrics) Failed

func (n *IOMetrics) Failed(operation string)

Failed records a failure on some IO operation

func (*IOMetrics) IO

func (n *IOMetrics) IO(start time.Time, operation string)

IO records some metrics for an IO operation.

Example:

var myIOMetrics = &IOMetrics{}

func (m *myType) MyInstrumentedFunc() {
  var size int, err error

  defer myIOMetrics.IO(time.Now(), "read")
  ...
  size,err := doSomeWork()
  if err != nil {
    myIOMetrics.Failed("read")
    return err
  }
  myIOMetrics.IOSize(size, "read")
}

func (*IOMetrics) IORecord

func (n *IOMetrics) IORecord(start time.Time, operation string) func(int64, error)

IORecord records all metrics for an IO operation in one go.

It provides an alternative way to record size and error in a single deferred call.

Example with deferred error capture:

var myIOMetrics = &IOMetrics{}

func (m *myType) MyInstrumentedFunc() {
  var size int, err error

  defer func(start time.Time) {
    myIOMetrics.IORecord(start, "read")(size, err)
  }(time.Now())
  ...
  size, err = doSomeWork()
  if err != nil {
    return
  }
}

func (*IOMetrics) Size

func (n *IOMetrics) Size(size int64, operation string)

Size records the size of some IO operation. Zero sizes are not recorded.

func (*IOMetrics) Throughput

func (n *IOMetrics) Throughput(start, end time.Time, size int64, operation string)

Throughput records a throuput on a successful, non-empty, IO operation. Expressed in bytes per second.

type Option

type Option func(*settings)

Option defines some options to the metrics initialization

func WithBasePath

func WithBasePath(location string) Option

WithBasePath defines the root for the registered metrics tree

func WithContexter

func WithContexter(c func() context.Context) Option

WithContexter sets a context generation function. The default contexter is context.Background

func WithExporter

func WithExporter(exporter view.Exporter) Option

WithExporter configures the exporter to convey metrics to some backend collector

func WithReportingPeriod

func WithReportingPeriod(d time.Duration) Option

WithReportingPeriod configures how often the exporter is going to upload metrics. Durations under 1 sec do not have any effect. The default is 10s.

type UsageMetrics

type UsageMetrics struct {
	Count    *stats.Int64Measure   `metric:"usageCount" description:"number of calls" tags:"kind,method"`
	Failures *stats.Int64Measure   `metric:"usageFailures" description:"number of failed calls" tags:"kind,method"`
	Timing   *stats.Float64Measure `metric:"timing" unit:"milliseconds" description:"duration of a call" tags:"kind,method"`
}

UsageMetrics is a common set of metrics reporting about usage

func (*UsageMetrics) Failed

func (u *UsageMetrics) Failed(method string)

Failed records a failure on some instrumented entry point

func (*UsageMetrics) Inc

func (u *UsageMetrics) Inc(method string)

Inc records the usage of some method, without timings or failure reporting

func (*UsageMetrics) Used

func (u *UsageMetrics) Used(start time.Time, method string)

Used records usage of some instrumented entry point.

Example:

var myUsageMetrics = &UsageMetrics{}

func (m *myType) MyInstrumentedFunc() {
  defer myUsageMetrics.Used(time.Now(), "MyInstrumentedFunc")
  ...
  err := doSomeWork()
  if err != nil {
    myUsageMetrics.Failed()
    ...
  }
}

func (*UsageMetrics) UsedAll

func (u *UsageMetrics) UsedAll(start time.Time, method string) func(error)

UsedAll records usage of some instrumented entry point with failures, in one go.

Example:

var myUsageMetrics = &UsageMetrics{}
var err error

func (m *myType) MyInstrumentedFunc() {
  defer func(start time.Time) {
    myUsageMetrics.UsedAll(start, "MyInstrumentedFunc")(err)
  }(time.Now())
  ...
  err = doSomeWork()
  if err != nil {
    return
  }
}