telemetry

README

telemetry

Go package to simplify recording metrics in a Prometheus compatible format. Its based on github.com/uber-go/tally/v4/prometheus.

Checkout the example for more details.

Documentation

Index

• func Collector(cfg Config, optPathPrefixFilters ...[]string) func(next http.Handler) http.Handler
• func SnakeCasef(format string, args ...any) string
• type Config
• type Scope
  • func NewScope(scope string) *Scope
  • func (n *Scope) Close() error
  • func (n *Scope) RecordDuration(measurement string, tags map[string]string, start time.Time, stop time.Time)
  • func (n *Scope) RecordDurationWithResolution(measurement string, tags map[string]string, timeA time.Time, timeB time.Time, ...)
  • func (n *Scope) RecordGauge(measurement string, tags map[string]string, value float64)
  • func (n *Scope) RecordHit(measurement string, tags map[string]string)
  • func (n *Scope) RecordIncrementValue(measurement string, tags map[string]string, value int64)
  • func (n *Scope) RecordIntegerValue(measurement string, tags map[string]string, value int)
  • func (n *Scope) RecordSize(measurement string, tags map[string]string, value float64)
  • func (n *Scope) RecordSpan(measurement string, tags map[string]string) tally.Stopwatch
  • func (n *Scope) RecordValue(measurement string, tags map[string]string, value float64)
  • func (n *Scope) RecordValueWithBuckets(measurement string, tags map[string]string, value float64, buckets []float64)

Functions

func Collector

func Collector(cfg Config, optPathPrefixFilters ...[]string) func(next http.Handler) http.Handler

Collector creates a handler that exposes a /metrics endpoint. Passing an array of strings to pathPrefixFilters will help reduce the noise on the service from random Internet traffic; that is, only the path prefixes will be measured.

func SnakeCasef

func SnakeCasef(format string, args ...any) string

Types

type Config

type Config struct {
	// If any of these values are not provided, measurements won't be exposed.
	Username string `toml:"username"`
	Password string `toml:"password"`

	// Allow any traffic. Ie. if username/password are not specified, but AllowAny
	// is true, then the metrics endpoint will be available.
	AllowAny bool `toml:"allow_any"`

	// Allow internal private subnet traffic
	AllowInternal bool `toml:"allow_internal"`
}

Config represents settings for the telemetry tool.

type Scope

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

Scope represents the measurements scope for an application.

func NewScope

func NewScope(scope string) *Scope

NewScope creates a scope for an application. Receives a scope argument (a single-word) that is used as a prefix for all measurements.

func (*Scope) Close

func (n *Scope) Close() error

Close closes the scope and stops reporting.

func (*Scope) RecordDuration

func (n *Scope) RecordDuration(measurement string, tags map[string]string, start time.Time, stop time.Time)

RecordDuration records an elapsed time. Use it when is important to see how values. Use it when is important to see how a value evolved over time, for instance request durations, the time it takes for a task to finish, etc.

RecordDuration adds the "_duration_seconds" prefix to the name of the measurement.

func (*Scope) RecordDurationWithResolution

func (n *Scope) RecordDurationWithResolution(measurement string, tags map[string]string, timeA time.Time, timeB time.Time, resolution time.Duration)

RecordDurationWithResolution records the elapsed duration between two time values. Use it when is important to see how a value evolved over time, for instance request durations, the time it takes for a task to finish, etc.

The resolution parameter can be any value, this value will be taken as base to build buckets.

RecordDurationWithResolution adds the "_duration_seconds" prefix to the name of the measurement.

func (*Scope) RecordGauge

func (n *Scope) RecordGauge(measurement string, tags map[string]string, value float64)

RecordGauge sets the value of a measurement that can go up or down over time.

RecordGauge measures a prometheus raw type and no suffix is added to the measurement.

func (*Scope) RecordHit

func (n *Scope) RecordHit(measurement string, tags map[string]string)

RecordHit increases a hit counter. This is ideal for counting HTTP requests or other events that are incremented by one each time.

RecordHit adds the "_total" suffix to the name of the measurement.

func (*Scope) RecordIncrementValue

func (n *Scope) RecordIncrementValue(measurement string, tags map[string]string, value int64)

func (*Scope) RecordIntegerValue

func (n *Scope) RecordIntegerValue(measurement string, tags map[string]string, value int)

RecordIntegerValue records a numeric unit-less value that can go up or down. Use it when is important to see how the value evolved over time.

RecordIntegerValue uses an histogram configured with buckets that priorize values closer to zero.

func (*Scope) RecordSize

func (n *Scope) RecordSize(measurement string, tags map[string]string, value float64)

RecordSize records a numeric unit-less value that can go up or down. Use it when it's more important to know the last value of said size. This is useful to measure things like the size of a queue.

RecordSize adds the "_size" prefix to the name of the measurement.

func (*Scope) RecordSpan

func (n *Scope) RecordSpan(measurement string, tags map[string]string) tally.Stopwatch

func (*Scope) RecordValue

func (n *Scope) RecordValue(measurement string, tags map[string]string, value float64)

RecordValue records a numeric unit-less value that can go up or down. Use it when is important to see how the value evolved over time.

RecordValue measures a prometheus raw type and no suffix is added to the measurement.

func (*Scope) RecordValueWithBuckets

func (n *Scope) RecordValueWithBuckets(measurement string, tags map[string]string, value float64, buckets []float64)

RecordValueWithBuckets records a numeric unit-less value that can go up or down. Use it when is important to see how the value evolved over time.

RecordValueWithBuckets adds the "_value" suffix to the name of the measurement.