autometrics

Documentation

Overview

Package autometrics provides automatic metric collection and reporting to functions.

Depending on the implementation you want to use for metric collection (currently, autometrics/prometheus and autometrics/otel are supported), you can initialise the metrics collector, and then use a defer statement to automatically instrument a function body.

The generator associated with autometrics generates the collection defer statement from argument in a directive comment, see the main project's Readme for more detail.

Index

• Constants
• Variables
• func GetBranch() string
• func GetCommit() string
• func GetVersion() string
• func SetBranch(newBranch string)
• func SetCommit(newCommit string)
• func SetVersion(newVersion string)
• type AlertConfiguration
• type BuildInfo
• type CallInfo
  • func CallerInfo() (callInfo CallInfo)
• type Context
  • func NewContext() Context
  • func (c *Context) FillBuildInfo()
  • func (c Context) Validate(allowCustomLatencies bool) error
• type Implementation
• type LatencySlo
• type Option
• type SuccessSlo

Constants

const (
	AllowCustomLatenciesFlag = "-custom-latency"
)

Variables

var (
	DefBuckets    = []float64{.005, .0075, .01, .025, .05, .075, .1, .25, .5, .75, 1, 2.5, 5, 7.5, 10}
	DefObjectives = []float64{90, 95, 99, 99.9}
)

Those are variables because we cannot have const of this type. These variables are not meant to be modified.

Functions

func GetBranch

func GetBranch() string

GetBranch returns the branch of the build of the codebase being instrumented.

func GetCommit

func GetCommit() string

GetCommit returns the commit of the codebase being instrumented.

func GetVersion

func GetVersion() string

GetVersion returns the version of the codebase being instrumented.

func SetBranch

func SetBranch(newBranch string)

SetBranch sets the branch of the build of the codebase being instrumented.

func SetCommit

func SetCommit(newCommit string)

SetCommit sets the commit of the codebase being instrumented.

func SetVersion

func SetVersion(newVersion string)

SetVersion sets the version of the codebase being instrumented.

Types

type AlertConfiguration

type AlertConfiguration struct {
	// ServiceName is the name of the Service that will appear in the alerts.
	ServiceName string
	// Latency is an optional latency target for the function
	Latency *LatencySlo
	// Success is an optional success rate target for the function
	Success *SuccessSlo
}

AlertConfiguration is the configuration for autometric alerting.

type BuildInfo

type BuildInfo struct {
	// Commit is the commit of the code.
	Commit string
	// Version is the version of the code.
	Version string
	// Branch is the branch of the build of the codebase.
	Branch string
}

BuildInfo holds the information about the current build of the instrumented code.

type CallInfo

type CallInfo struct {
	// FuncName is name of the function being tracked.
	FuncName string
	// ModuleName is name of the module of the function being tracked.
	ModuleName string
	// ParentFuncName is name of the caller of the function being tracked.
	ParentFuncName string
	// ParentModuleName is name of the module of the caller of the function being tracked.
	ParentModuleName string
}

CallInfo holds the information about the current function call and its parent names.

func CallerInfo

func CallerInfo() (callInfo CallInfo)

CallerInfo returns the (method name, module name) of the function that called the function that called this function.

It also returns the information about its grandparent.

The module name and the parent module names are cropped to their last part, because the generator we use only has access to the last "package" name in `GOPACKAGE` environment variable.

If there is a way to obtain programmatically the fully qualified package name in go-generate arguments, then we can lift this artificial limitation here and use the full "module name" from the caller information. Currently this compromise is the only way to have the documentation links generator creating correct queries.

type Context

type Context struct {
	// TrackConcurrentCalls triggers the collection of the gauge for concurrent calls of the function.
	TrackConcurrentCalls bool
	// TrackCallerName adds a label with the caller name in all the collected metrics.
	TrackCallerName bool
	// AlertConf is an optional configuration to add alerting capabilities to the metrics.
	AlertConf *AlertConfiguration
	// StartTime is the start time of a single function execution.
	// Only amImpl.Instrument should read this value.
	// Only amImpl.PreInstrument should write this value.
	//
	// (amImpl is either the [Prometheus] or the [Open Telemetry] implementation)
	//
	// This value is only exported for the child packages [Prometheus] and [Open Telemetry]
	//
	// [Prometheus]: https://godoc.org/github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus
	// [Open Telemetry]: https://godoc.org/github.com/autometrics-dev/autometrics-go/pkg/autometrics/otel
	StartTime time.Time
	// CallInfo contains all the relevant data for caller information.
	// Only amImpl.Instrument should read this value.
	// Only amImpl.PreInstrument should write/read this value.
	//
	// (amImpl is either the [Prometheus] or the [Open Telemetry] implementation)
	//
	// This value is only exported for the child packages [Prometheus] and [Open Telemetry]
	//
	// [Prometheus]: https://godoc.org/github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus
	// [Open Telemetry]: https://godoc.org/github.com/autometrics-dev/autometrics-go/pkg/autometrics/otel
	CallInfo CallInfo
	// BuildInfo contains all the relevant data for caller information.
	// Only amImpl.Instrument and PreInstrument should read this value.
	// Only amImpl.Init should write/read this value.
	//
	// (amImpl is either the [Prometheus] or the [Open Telemetry] implementation)
	//
	// This value is only exported for the child packages [Prometheus] and [Open Telemetry]
	//
	// [Prometheus]: https://godoc.org/github.com/autometrics-dev/autometrics-go/pkg/autometrics/prometheus
	// [Open Telemetry]: https://godoc.org/github.com/autometrics-dev/autometrics-go/pkg/autometrics/otel
	BuildInfo BuildInfo
	Context   context.Context
}

Context holds the configuration to instrument properly a function.

This can be viewed as a context for the instrumentation calls

func NewContext

func NewContext() Context

func (*Context) FillBuildInfo

func (c *Context) FillBuildInfo()

func (Context) Validate

func (c Context) Validate(allowCustomLatencies bool) error

type Implementation

type Implementation int

Implementation is an enumeration type for the possible implementations of metrics to use.

const (
	PROMETHEUS Implementation = iota
	OTEL                      = iota
)

type LatencySlo

type LatencySlo struct {
	// Target is the maximum allowed latency for the endpoint.
	Target time.Duration
	// Objective is the success rate allowed for the given latency, from 0 to 1.
	Objective float64
}

LatencySlo is an objective for latency

type Option

type Option interface {
	// Apply the option to the currently created context
	Apply(*Context)
}

type SuccessSlo

type SuccessSlo struct {
	// Objective is the success rate allowed for the given function, from 0 to 1.
	Objective float64
}

SuccessSlo is an objective for the success rate of the function