autometrics

Documentation

Overview

Package autometrics implements the automatic metric registration and collection for autometrics using OpenTelemetry metrics and a Prometheus exporter.

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 WithMeterName(currentMeterName string) InitOption
  • func WithPushCollectorURL(pushCollectorURL string) InitOption
  • func WithPushHTTP() InitOption
  • func WithPushHeaders(headers map[string]string) InitOption
  • func WithPushInsecure() InitOption
  • func WithPushJobName(pushJobName string) InitOption
  • func WithPushPeriod(pushPeriod time.Duration) InitOption
  • func WithPushTimeout(pushTimeout time.Duration) 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 openTelemetry metric for the counter of calls to specific functions.
	FunctionCallsCountName = "function.calls"
	// FunctionCallsDurationName is the name of the openTelemetry metric for the duration histogram of calls to specific functions.
	FunctionCallsDurationName = "function.calls.duration"
	// FunctionCallsConcurrentName is the name of the openTelemetry metric for the number of simulateneously active calls to specific functions.
	FunctionCallsConcurrentName = "function.calls.concurrent"
	// BuildInfo is the name of the openTelemetry metric for the version of the monitored codebase.
	BuildInfoName = "build_info"

	// FunctionLabel is the openTelemetry attribute 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 openTelemetry attribute 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 openTelemetry attribute that describes the name of the function that called
	// the current function.
	CallerFunctionLabel = "caller.function"
	// CallerModuleLabel is the openTelemetry attribute that describes the module of the function that called
	// the current function.
	CallerModuleLabel = "caller.module"
	// ResultLabel is the openTelemetry attribute that describes whether a function call is successful.
	ResultLabel = "result"
	// TargetLatencyLabel is the openTelemetry attribute that describes the latency to respect to match
	// the Service Level Objective.
	TargetLatencyLabel = "objective.latency_threshold"
	// TargetSuccessRateLabel is the openTelemetry attribute 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 openTelemetry attribute that describes the name of the Service Level Objective.
	SloNameLabel = "objective.name"

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

	// RepositoryURLLabel is the openTelemetry attribute that describes the URL at which the repository containing
	// the monitored service can be found
	RepositoryURLLabel = "repository.url"
	// RepositoryProviderLabel is the openTelemetry attribute that describes the service provider for the monitored
	// service repository url
	RepositoryProviderLabel = "repository.provider"

	// AutometricsVersionLabel is the openTelemetry attribute that describes the version of the Autometrics specification
	// the library follows
	AutometricsVersionLabel = "autometrics.version"

	// ServiceNameLabel is the openTelemetry attribute that describes the name of the Service being monitored.
	ServiceNameLabel = "service.name"

	// JobNameLabel is the openTelemetry attribute that describes the job producing the metrics. It is
	// used when pushing OTLP metrics.
	JobNameLabel = "job"
)

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 an OTLP collector.

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 Prometheus exporter.

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 WithMeterName

func WithMeterName(currentMeterName string) InitOption

WithMeterName sets the name of the meter to use for opentelemetry metrics. The name will be prefixed with "autometrics/" to help figure out the origin.

The default value is an empty string

func WithPushCollectorURL

func WithPushCollectorURL(pushCollectorURL string) InitOption

WithPushCollectorURL enables Pushing metrics to a remote location, and sets the URL of the collector to target. 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 WithPushHTTP

func WithPushHTTP() InitOption

WlthPushHTTP sets the metrics pushing mechanism to use the HTTP format over gRPC

The default value is to use gRPC.

func WithPushHeaders

func WithPushHeaders(headers map[string]string) InitOption

WithPushHeaders allows adding headers to the payload of metrics when pushed to the collector (for BasicAuth authentication for example)

The default value is empty.

func WithPushInsecure

func WithPushInsecure() InitOption

WlthPushInsecure allows to use insecure (clear text) connections between the codebase and the metrics collector.

The default value is to use secure channels only.

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 WithPushPeriod

func WithPushPeriod(pushPeriod time.Duration) InitOption

WithPushPeriod sets the duration between consecutive metrics pushes.

The standard `OTEL_METRIC_EXPORT_INTERVAL` environment variable overrides this initialization argument.

The default value is 10 seconds.

func WithPushTimeout

func WithPushTimeout(pushTimeout time.Duration) InitOption

WithPushTimeout sets the timeout duration of a single metric push

The standard `OTEL_METRIC_EXPORT_TIMEOUT` environment variable overrides this initialization argument.

The default value is 5 seconds.

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