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
  • func (a Config) Creds() map[string]string
• type Scope
  • func NewScope(scope string, optTags ...map[string]string) *Scope
  • func (n *Scope) Close() error
  • func (n *Scope) GetTaggedScope(key string) (*Scope, bool)
  • func (n *Scope) RecordDuration(measurement string, start time.Time, stop time.Time)
  • func (n *Scope) RecordDurationWithResolution(measurement string, timeA time.Time, timeB time.Time, resolution time.Duration)
  • func (n *Scope) RecordGauge(measurement string, value float64)
  • func (n *Scope) RecordHit(measurement string)
  • func (n *Scope) RecordIncrementValue(measurement string, value int64)
  • func (n *Scope) RecordIntegerValue(measurement string, value int)
  • func (n *Scope) RecordSize(measurement string, value float64)
  • func (n *Scope) RecordSpan(measurement string) tally.Stopwatch
  • func (n *Scope) RecordValue(measurement string, value float64)
  • func (n *Scope) RecordValueWithBuckets(measurement string, value float64, buckets []float64)
  • func (n *Scope) SetTaggedScope(key string, tags map[string]string) *Scope
  • func (n *Scope) Tagged(tagName, tagValue string) *Scope
  • func (n *Scope) WithTaggedMap(tags map[string]string) *Scope

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.

func (Config) Creds

func (a Config) Creds() map[string]string

type Scope

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

Scope represents the measurements scope for an application.

func NewScope

func NewScope(scope string, optTags ...map[string]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. Optionally you can pass a map of tags to be used for all measurements in the scope.

func (*Scope) Close

func (n *Scope) Close() error

Close closes the scope and stops reporting.

func (*Scope) GetTaggedScope

func (n *Scope) GetTaggedScope(key string) (*Scope, bool)

GetTaggedScope returns a new scope with the given tags based on the supplied key identifer.

func (*Scope) RecordDuration

func (n *Scope) RecordDuration(measurement 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.

Measurement type: Histogram

func (*Scope) RecordDurationWithResolution

func (n *Scope) RecordDurationWithResolution(measurement 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.

Measurement type: Histogram

func (*Scope) RecordGauge

func (n *Scope) RecordGauge(measurement 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.

Measurement type: Gauge

func (*Scope) RecordHit

func (n *Scope) RecordHit(measurement 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.

Measurement type: Counter

func (*Scope) RecordIncrementValue

func (n *Scope) RecordIncrementValue(measurement string, value int64)

RecordIncrementValue increases a counter.

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

Measurement type: Counter

func (*Scope) RecordIntegerValue

func (n *Scope) RecordIntegerValue(measurement 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.

Measurement type: Histogram

func (*Scope) RecordSize

func (n *Scope) RecordSize(measurement 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.

Measurement type: Gauge

func (*Scope) RecordSpan

func (n *Scope) RecordSpan(measurement string) tally.Stopwatch

RecordSpan starts a stopwatch for a span.

RecordSpan adds the "_span" suffix to the name of the measurement.

Measurement type: Timer

func (*Scope) RecordValue

func (n *Scope) RecordValue(measurement 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.

Measurement type: Histogram

func (*Scope) RecordValueWithBuckets

func (n *Scope) RecordValueWithBuckets(measurement 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.

Measurement type: Histogram

func (*Scope) SetTaggedScope

func (n *Scope) SetTaggedScope(key string, tags map[string]string) *Scope

SetTaggedScope returns a new scope with the given tags based on the supplied key identifer.

func (*Scope) Tagged

func (n *Scope) Tagged(tagName, tagValue string) *Scope

Tagged returns a tagged scope for the tag name and value pair. It's very efficient as it will return a cached scope if it exists for the tagged scope, or it will create a new scope and cache it based on tag name + value. If either tagName or tagValue is empty, it will return the current scope.

func (*Scope) WithTaggedMap

func (n *Scope) WithTaggedMap(tags map[string]string) *Scope

WithTaggedMap returns a new scope with the given tags. However, if this is a hot-path (and telemetry usually is), we recommend using GetTaggedScope and SetTaggedScope to avoid the overhead of creating a new scope.