autometrics

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 25, 2024 License: Apache-2.0, MIT Imports: 14 Imported by: 0

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

View Source
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

View Source
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 added in v0.8.0

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 added in v1.0.0

type InitOption interface {
	Apply(*initArguments) error
}

func WithBranch added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 default value is an empty string, which will make autometrics generate a Ulid

func WithRegistry added in v1.0.0

func WithRegistry(registry *prometheus.Registry) InitOption

WithRegistry sets the prometheus registry to use.

The default is to use prometheus default registry.

func WithRepoProvider added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v1.0.0

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 added in v0.9.0

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 added in v0.9.0

type NoOpLogger = log.NoOpLogger

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

type PrintLogger added in v0.9.0

type PrintLogger = log.PrintLogger

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

type ValidHttpRange

type ValidHttpRange = autometrics.InclusiveIntRange

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL