autometrics

Documentation

Overview

Package autometrics implements the automatic metric registration and collection for autometrics using the Prometheus client library.

The package contains the function implementations for the generated calls, see the main project's Readme for more detail.

Index

• Constants
• Variables
• func DecodeString(s string) []byte
• func ForceFlush() error
• func Init(initOpts ...InitOption) (context.CancelCauseFunc, error)
• func Instrument(ctx context.Context, err *error)
• func NewContext(ctx context.Context, opts ...autometrics.Option) context.Context
• func PreInstrument(ctx context.Context) context.Context
• func WithAlertLatency(target time.Duration, objective float64) autometrics.Option
• func WithAlertSuccess(objective float64) autometrics.Option
• func WithCallerName(enabled bool) autometrics.Option
• func WithConcurrentCalls(enabled bool) autometrics.Option
• func WithNewTraceId(ctx context.Context) context.Context
• func WithSloName(name string) autometrics.Option
• func WithSpanID(sid []byte) autometrics.Option
• func WithTraceID(tid []byte) autometrics.Option
• func WithValidHttpCodes(ranges []ValidHttpRange) autometrics.Option
• type InitOption
  • func WithBranch(currentBranch string) InitOption
  • func WithCommit(currentCommit string) InitOption
  • func WithHistogramBuckets(histogramBuckets []float64) InitOption
  • func WithLogger(logger log.Logger) InitOption
  • func WithPushCollectorURL(pushCollectorURL string) InitOption
  • func WithPushJobName(pushJobName string) InitOption
  • func WithRegistry(registry *prometheus.Registry) InitOption
  • func WithRepoProvider(currentRepoProvider string) InitOption
  • func WithRepoURL(currentRepoURL string) InitOption
  • func WithService(currentService string) InitOption
  • func WithVersion(currentVersion string) InitOption
• type Logger
• type NoOpLogger
• type PrintLogger
• type ValidHttpRange

Constants

const (
	// AutometricsSpecVersion is the version of the specification the library follows
	// The specifications can be found in https://github.com/autometrics-dev/autometrics-shared/tree/main/specs
	AutometricsSpecVersion = "1.0.0"

	// FunctionCallsCountName is the name of the prometheus metric for the counter of calls to specific functions.
	FunctionCallsCountName = "function_calls_total"
	// FunctionCallsDurationName is the name of the prometheus metric for the duration histogram of calls to specific functions.
	FunctionCallsDurationName = "function_calls_duration_seconds"
	// FunctionCallsConcurrentName is the name of the prometheus metric for the number of simulateneously active calls to specific functions.
	FunctionCallsConcurrentName = "function_calls_concurrent"
	// BuildInfo is the name of the prometheus metric for the version of the monitored codebase.
	BuildInfoName = "build_info"

	// FunctionLabel is the prometheus label that describes the function name.
	//
	// It is guaranteed that a (FunctionLabel, ModuleLabel) value pair is unique
	// and matches at most one function in the source code
	FunctionLabel = "function"
	// ModuleLabel is the prometheus label that describes the module name that contains the function.
	//
	// It is guaranteed that a (FunctionLabel, ModuleLabel) value pair is unique
	// and matches at most one function in the source code
	ModuleLabel = "module"
	// CallerFunctionLabel is the prometheus label that describes the name of the function that called
	// the current function.
	CallerFunctionLabel = "caller_function"
	// CallerModuleLabel is the prometheus label that describes the module of the function that called
	// the current function.
	CallerModuleLabel = "caller_module"
	// ResultLabel is the prometheus label that describes whether a function call is successful.
	ResultLabel = "result"
	// TargetLatencyLabel is the prometheus label that describes the latency to respect to match
	// the Service Level Objective.
	TargetLatencyLabel = "objective_latency_threshold"
	// TargetSuccessRateLabel is the prometheus label that describes the percentage of calls that
	// must succeed to match the Service Level Objective.
	//
	// In the case of latency objectives, it describes the percentage of
	// calls that must last less than the value in [TargetLatencyLabel].
	//
	// In the case of success objectives, it describes the percentage of calls
	// that must be successful (i.e. have their [ResultLabel] be 'ok').
	TargetSuccessRateLabel = "objective_percentile"
	// SloNameLabel is the prometheus label that describes the name of the Service Level Objective.
	SloNameLabel = "objective_name"

	// CommitLabel is the prometheus label that describes the commit of the monitored codebase.
	CommitLabel = "commit"
	// VersionLabel is the prometheus label that describes the version of the monitored codebase.
	VersionLabel = "version"
	// BranchLabel is the prometheus label that describes the branch of the build of the monitored codebase.
	BranchLabel = "branch"

	// RepositoryURLLabel is the prometheus label that describes the URL at which the repository containing
	// the monitored service can be found
	RepositoryURLLabel = "repository_url"
	// RepositoryProviderLabel is the prometheus label that describes the service provider for the monitored
	// service repository url
	RepositoryProviderLabel = "repository_provider"

	// AutometricsVersionLabel is the prometheus label that describes the version of the Autometrics specification
	// the library follows
	AutometricsVersionLabel = "autometrics_version"

	// ServiceNameLabel is the prometheus label that describes the name of the service being monitored
	ServiceNameLabel = "service_name"
)

Variables

var (
	DefBuckets = autometrics.DefBuckets
)

Functions

func DecodeString

func DecodeString(s string) []byte

Convenience re-export of hex.DecodeString to allow generating code without touching imports in instrumented file.

func ForceFlush

func ForceFlush() error

ForceFlush forces a flush of the metrics, in the case autometrics is pushing metrics to a Prometheus Push Gateway.

This function is a no-op if no push configuration has been setup in Init, but will return an error if autometrics is not active (because this function is called before Init or after its shutdown function has been called).

func Init

func Init(initOpts ...InitOption) (context.CancelCauseFunc, error)

Init sets up the metrics required for autometrics' decorated functions and registers them to the argument registry.

If the passed registry is nil, all the metrics are registered to the default global registry.

After initialization, use the returned context.CancelCauseFunc to flush the last results and turn off metric collection for the remainder of the program's lifetime. It is a good candidate to be deferred in the usual case.

Make sure that all the latency targets you want to use for SLOs are present in the histogramBuckets array, otherwise the alerts will fail to work (they will never trigger.)

func Instrument

func Instrument(ctx context.Context, err *error)

Instrument called in a defer statement wraps the body of a function with automatic instrumentation.

The first argument SHOULD be a call to PreInstrument so that the "concurrent calls" gauge is correctly setup.

func NewContext

func NewContext(ctx context.Context, opts ...autometrics.Option) context.Context

func PreInstrument

func PreInstrument(ctx context.Context) context.Context

PreInstrument runs the "before wrappee" part of instrumentation.

It is meant to be called as the first argument to Instrument in a defer call.

func WithAlertLatency

func WithAlertLatency(target time.Duration, objective float64) autometrics.Option

func WithAlertSuccess

func WithAlertSuccess(objective float64) autometrics.Option

func WithCallerName

func WithCallerName(enabled bool) autometrics.Option

func WithConcurrentCalls

func WithConcurrentCalls(enabled bool) autometrics.Option

func WithNewTraceId

func WithNewTraceId(ctx context.Context) context.Context

Convenience re-export of autometrics.WithNewTraceId to avoid needing multiple imports in instrumented file.

func WithSloName

func WithSloName(name string) autometrics.Option

func WithSpanID

func WithSpanID(sid []byte) autometrics.Option

func WithTraceID

func WithTraceID(tid []byte) autometrics.Option

func WithValidHttpCodes

func WithValidHttpCodes(ranges []ValidHttpRange) autometrics.Option

Types

type InitOption

type InitOption interface {
	Apply(*initArguments) error
}

func WithBranch

func WithBranch(currentBranch string) InitOption

WithBranch sets the name of the branch to export with the metrics.

The default value is an empty string.

func WithCommit

func WithCommit(currentCommit string) InitOption

WithCommit sets the commit of the codebase to export with the metrics.

The default value is an empty string.

func WithHistogramBuckets

func WithHistogramBuckets(histogramBuckets []float64) InitOption

WithHistogramBuckets sets the buckets to use for the latency histograms.

WARNING: your latency SLOs should always use thresolds that are _exactly_ a bucket boundary to ensure alert precision.

The default value is autometrics.DefBuckets

func WithLogger

func WithLogger(logger log.Logger) InitOption

WithLogger sets the logger to use when initializing autometrics.

The default logger is a no-op logger that will never log autometrics-specific events.

func WithPushCollectorURL

func WithPushCollectorURL(pushCollectorURL string) InitOption

WithPushCollectorURL enables Pushing metrics to a remote location, and sets the URL of the collector to target.

Just as the prometheus library push configuration, "You can use just host:port or ip:port as url, in which case “http://” is added automatically. Alternatively, include the schema in the URL. However, do not include the “/metrics/jobs/…” part."

The default value is an empty string, which also disables metric pushing.

func WithPushJobName

func WithPushJobName(pushJobName string) InitOption

WithPushJobName sets the name of job to use when pushing metrics.

Good values for this (taking into account replicated services) are for example:

• The (internal) IP the job is coming from,
• a [Uuid v1](https://pkg.go.dev/github.com/google/uuid#NewUUID) or a [Ulid](https://github.com/oklog/ulid) to get sortable IDs and keeping relationship to the machine generating metrics.
• a Uuid v4 if you don't want metrics leaking extra information about the IPs

The default value is an empty string, which will make autometrics generate a Ulid

func WithRegistry

func WithRegistry(registry *prometheus.Registry) InitOption

WithRegistry sets the prometheus registry to use.

The default is to use prometheus default registry.

func WithRepoProvider

func WithRepoProvider(currentRepoProvider string) InitOption

WithRepoProvider sets the provider of the repository containing the codebase being instrumented.

The default value is an empty string.

func WithRepoURL

func WithRepoURL(currentRepoURL string) InitOption

WithRepoURL sets the URL of the repository containing the codebase being instrumented.

The default value is an empty string.

func WithService

func WithService(currentService string) InitOption

WithService sets the name of the current service, to export with the metrics.

The default value is an empty string.

func WithVersion

func WithVersion(currentVersion string) InitOption

WithVersion sets the version of the codebase to export with the metrics.

The default value is an empty string.

type Logger

type Logger = log.Logger

Logger is an interface for logging autometrics-related events.

This is a reexport to allow using only the current package at call site.

type NoOpLogger

type NoOpLogger = log.NoOpLogger

This is a reexport to allow using only the current package at call site.

type PrintLogger

type PrintLogger = log.PrintLogger

This is a reexport to allow using only the current package at call site.

type ValidHttpRange

type ValidHttpRange = autometrics.InclusiveIntRange