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: 12 Imported by: 0

Documentation

Overview

Package autometrics provides automatic metric collection and reporting to functions.

Depending on the implementation you want to use for metric collection (currently, Prometheus and Open Telemetry 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

View Source 
const (
	// AutometricsServiceNameEnv is the name of the environment variable to declare to fetch the name of
	// the service to use as a label. This environment variable has precedence over [OTelServiceNameEnv]
	// _and_ over hardcoding the variable directly in [BuildInfo] struct in the Init call.
	AutometricsServiceNameEnv = "AUTOMETRICS_SERVICE_NAME"
	// OTelServiceNameEnv is the name of the environment variable to declare to fetch the name of
	// the service to use as a label. This environment variable has precedence over variables hardcoded
	// in the [BuildInfo] struct in the Init call.
	OTelServiceNameEnv = "OTEL_SERVICE_NAME"
	// AutometricsRepoURLEnv is the name of the environment variable to declare to give the URL of
	// the repository for the service to use as a label. This environment variable has precedence over
	// over hardcoding the variable directly in [BuildInfo] struct in the Init call.
	AutometricsRepoURLEnv = "AUTOMETRICS_REPOSITORY_URL"
	// AutometricsRepoProviderEnv is the name of the environment variable to declare to give the name of
	// the repository provider to use as a label. This environment variable has precedence over
	// over hardcoding the variable directly in [BuildInfo] struct in the Init call.
	AutometricsRepoProviderEnv = "AUTOMETRICS_REPOSITORY_PROVIDER"
	// OTelPushPeriodEnv is the name of the environment variable to declare to change the interval
	// between 2 metrics pushes in milliseconds.
	//
	// Reference: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader
	OTelPushPeriodEnv = "OTEL_METRIC_EXPORT_INTERVAL"
	// OTelPushTimeoutEnv is the name of the environment variable to declare to change the timeout
	// threshold of a single metrics push in milliseconds.
	//
	// Reference: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/#periodic-exporting-metricreader
	OTelPushTimeoutEnv = "OTEL_METRIC_EXPORT_TIMEOUT"
)
View Source 
const (
	// MiddlewareSpanIDKey is the key to use to index context in middlewares that do not use context.Context.
	MiddlewareSpanIDKey = "autometricsSpanID"
	// MiddlewareTraceIDKey is the key to use to index context in middlewares that do not use context.Context.
	MiddlewareTraceIDKey = "autometricsTraceID"
)
View Source 
const (
	AllowCustomLatenciesFlag = "-custom-latency"
)

Variables

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

func DefaultJobName() string

DefaultJobName returns the default job name to use when pushing metrics to a collector.

This function cannot fail.

func FillBuildInfo added in v0.6.0 

func FillBuildInfo(ctx context.Context) context.Context

FillBuildInfo adds the relevant build information to the current context.

func FillTracingAndCallerInfo added in v0.9.0 

func FillTracingAndCallerInfo(ctx context.Context) context.Context

FillTracingAndCallerInfo ensures the context has a traceID and a spanID, and looks for relevant caller information to add in the context as well. If they do not have this information, this method adds randomly generated IDs in the context to be used later for exemplars

The random generator is a PRNG, seeded with the timestamp of the first time new IDs are needed.

func GetBranch added in v0.4.0 

func GetBranch() string

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

func GetCommit added in v0.4.0 

func GetCommit() string

GetCommit returns the commit of the codebase being instrumented.

func GetLogger added in v0.9.0 

func GetLogger() log.Logger

GetLogger returns the current logging interface for Autometrics

func GetOutboundIP added in v0.8.0 

func GetOutboundIP() (net.IP, error)

GetOutboundIP returns the preferred outbound ip of this machine.

This function temporarily opens a TCP connexion to a Cloudflare-owned server to determine the external IP of the current process.

This is a useful function to use for setting a `job` key when pushing metrics.

func GetPushJobName added in v0.8.0 

func GetPushJobName() string

GetPushJobName returns the job name to use when the codebase being instrumented is pushing metrics to an OTEL Collector.

func GetPushJobURL added in v0.8.0 

func GetPushJobURL() string

GetPushJobURL returns the job url to use when the codebase being instrumented is pushing metrics to an OTEL Collector.

func GetRepositoryProvider added in v0.9.0 

func GetRepositoryProvider() string

GetRepositoryProvider returns the service provider of the repo for the codebase being instrumented.

func GetRepositoryURL added in v0.9.0 

func GetRepositoryURL() string

GetRepositoryURL returns the URL of the repo of the codebase being instrumented.

func GetService added in v0.7.0 

func GetService() string

GetService returns the service of the build of the codebase being instrumented.

func GetStartTime added in v0.6.0 

func GetStartTime(c context.Context) time.Time

GetStartTime returns default current time if the context did not contain any start time.

StartTime is the start time of a single function execution.

func GetTrackCallerName added in v0.6.0 

func GetTrackCallerName(c context.Context) bool

GetTrackCallerName returns default information if the context did not contain any build information.

TrackCallerName adds a label with the caller name in all the collected metrics. It defaults to true.

func GetTrackConcurrentCalls added in v0.6.0 

func GetTrackConcurrentCalls(c context.Context) bool

GetTrackConcurrentCalls returns whether autometrics should track how many concurrent calls the instrumented function observe.

TrackConcurrentCalls triggers the collection of the gauge for concurrent calls of the function. It defaults to true.

func GetVersion added in v0.4.0 

func GetVersion() string

GetVersion returns the version of the codebase being instrumented.

func NewContext 

func NewContext(parentCtx context.Context) context.Context

NewContext is a constructor taking the parent context as argument.

It accepts 'nil' as the parent context. In this case the constructor acts as if it received a new, fresh context.Background().

func NewContextWithOpts added in v0.6.0 

func NewContextWithOpts(ctx context.Context, opts ...Option) context.Context

func PopFunctionName added in v0.9.0 

func PopFunctionName(ctx context.Context) error

func PushFunctionName added in v0.9.0 

func PushFunctionName(ctx context.Context, functionID FunctionID) error

func SetAlertConfiguration added in v0.6.0 

func SetAlertConfiguration(ctx context.Context, slo AlertConfiguration) context.Context

SetAlertConfiguration sets the context's AlertConfiguration

AlertConfiguration is an optional configuration to add alerting capabilities to the metrics.

func SetBranch added in v0.4.0 

func SetBranch(newBranch string)

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

func SetBuildInfo added in v0.6.0 

func SetBuildInfo(ctx context.Context, build BuildInfo) context.Context

SetBuildInfo sets the context's BuildInfo

BuildInfo contains all the relevant data for caller information.

func SetCallInfo added in v0.6.0 

func SetCallInfo(ctx context.Context, build CallInfo) context.Context

SetCallInfo sets the context's CallInfo

CallInfo contains all the relevant data for caller information.

func SetCommit added in v0.4.0 

func SetCommit(newCommit string)

SetCommit sets the commit of the codebase being instrumented.

func SetLogger added in v0.9.0 

func SetLogger(newLogger log.Logger)

SetLogger sets the logging interface for Autometrics.

func SetParentSpanID added in v0.6.0 

func SetParentSpanID(ctx context.Context, sid SpanID) context.Context

SetParentSpanID sets the context's span's parent SpanID

func SetPushJobName added in v0.8.0 

func SetPushJobName(newPushJobName string)

SetPushJobName sets the job name to use when the codebase being instrumented is pushing metrics to an OTEL Collector.

func SetPushJobURL added in v0.8.0 

func SetPushJobURL(newPushJobURL string)

SetPushJobURL sets the job url to use when the codebase being instrumented is pushing metrics to an OTEL Collector.

func SetRepositoryProvider added in v0.9.0 

func SetRepositoryProvider(newRepositoryProvider string)

SetRepositoryProvider sets the service provider of the repo for the codebase being instrumented.

func SetRepositoryURL added in v0.9.0 

func SetRepositoryURL(newRepositoryURL string)

SetRepositoryURL sets the URL of the repo of the codebase being instrumented.

func SetService added in v0.7.0 

func SetService(newService string)

SetService sets the service name of the build of the codebase being instrumented.

func SetSpanID added in v0.6.0 

func SetSpanID(ctx context.Context, sid SpanID) context.Context

SetSpanID sets the context's SpanID

func SetStartTime added in v0.6.0 

func SetStartTime(ctx context.Context, newStartTime time.Time) context.Context

SetStartTime sets the context's [StartTime]

StartTime is the start time of a single function execution.

func SetTraceID added in v0.6.0 

func SetTraceID(ctx context.Context, tid TraceID) context.Context

SetTraceID sets the context's TraceID

func SetTrackCallerName added in v0.6.0 

func SetTrackCallerName(ctx context.Context, track bool) context.Context

SetTrackCallerName sets a flag in the context deciding whether to track the names of the callers of instrumented functions.

TrackCallerName adds a label with the caller name in all the collected metrics. The flag defaults to true.

func SetTrackConcurrentCalls added in v0.6.0 

func SetTrackConcurrentCalls(ctx context.Context, track bool) context.Context

SetTrackConcurrentCalls sets a flag in the context deciding whether to track how many concurrent calls the instrumented functions observe.

TrackConcurrentCalls triggers the collection of the gauge for concurrent calls of the function. The flag defaults to true.

func SetValidHttpCodeRanges added in v0.6.0 

func SetValidHttpCodeRanges(ctx context.Context, ranges []InclusiveIntRange) context.Context

SetValidHttpCodeRanges sets the values of http codes that Autometrics should consider as "ok" results on calls.

The value to set is an array of `(int, int)` pairs, where each pair contains the inclusive minimum and inclusive maximum of a valid range. For example, `[(100,399)]` is a good default, if we only want 4xx and 5xx status codes to be errors for Autometrics reporting. Another option that might be popular is `[(100, 499)]` to only see server-side errors as errors in Autometrics metrics/dashboards.

The ability to specify multiple ranges allow for disjoint sets: `[(100, 399), (418,418)]` would make Autometrics report an error on any 4xx or 5xx status code, _except_ if that code is 418 (I'm a teapot).

This setting is only useful when used in conjunction with the github.com/autometrics-dev/autometrics-go/pkg/middleware/http/middleware.Autometrics wrapper.

func SetVersion added in v0.4.0 

func SetVersion(newVersion string)

SetVersion sets the version of the codebase being instrumented.

func WithNewTraceId added in v0.6.0 

func WithNewTraceId(ctx context.Context) context.Context

WithNewTraceId returns a copy of the passed context, with a newly generated traceID accessible for autometrics.

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.

func GetAlertConfiguration added in v0.6.0 

func GetAlertConfiguration(c context.Context) AlertConfiguration

GetAlertConfiguration returns default information if the context did not contain any alerting configuration.

AlertConfiguration is an optional configuration to add alerting capabilities to the metrics.

type BuildInfo added in v0.4.0 

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
	// Service is the name of the service
	Service string
	// RepositoryURL is the URL of the repository containing the code
	RepositoryURL string
	// RepositoryProvider is the service provider for the repository containing the code
	RepositoryProvider string
}

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

func GetBuildInfo added in v0.6.0 

func GetBuildInfo(c context.Context) BuildInfo

GetBuildInfo returns default information if the context did not contain any build information.

BuildInfo contains all the relevant data for caller information.

type CallInfo 

type CallInfo struct {
	// Current is the identifier of the function being tracked
	Current FunctionID
	// Parent is the identifirs of the caller of the function being tracked.
	//
	// The parent information is only included for autometricized functions. This
	// means:
	// - if A calls B calls C,
	// - only A and C have autometrics annotations,
	// then the Caller information when working with C is going to be A, _not_ B
	Parent FunctionID
}

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

func GetCallInfo added in v0.6.0 

func GetCallInfo(c context.Context) CallInfo

GetCallInfo returns default information if the context did not contain any build information.

CallInfo contains all the relevant data for caller information.

func ReflectFunctionModuleName added in v0.6.0 

func ReflectFunctionModuleName(f interface{}) (callInfo CallInfo)

ReflectFunctionModuleName takes any function and returns it's name and module split.

There is no `caller` in this context (we just use reflection to extract the information from the function pointer), therefore the caller-related fields in the return value are empty.

type FunctionID added in v0.9.0 

type FunctionID struct {
	// Function is the name of the function being tracked
	Function string
	// Module is the name of the module containing the function being tracked, up to (and including) the class name
	Module string
}

FunctionID is a unique identifier for a function (on a per-codebase basis)

func ParentFunctionName added in v0.9.0 

func ParentFunctionName(ctx context.Context) (FunctionID, error)

type Implementation added in v0.3.0 

type Implementation int

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

const (
	PROMETHEUS Implementation = iota
	OTEL
)

type InclusiveIntRange added in v0.6.0 

type InclusiveIntRange struct {
	Min int
	Max int
}

func GetValidHttpCodeRanges added in v0.6.0 

func GetValidHttpCodeRanges(c context.Context) []InclusiveIntRange

GetValidHttpCodeRanges returns the list of values that should be considered as "ok" by Autometrics when computing the success rate of a handler.

Look at the documentation of SetValidHttpCodeRanges for more information about the semantics of the returned value.

func (InclusiveIntRange) Contains added in v0.6.0 

func (r InclusiveIntRange) Contains(value int) bool

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

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

func WithAlertLatency added in v0.6.0 

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

func WithAlertSuccess added in v0.6.0 

func WithAlertSuccess(objective float64) Option

func WithCallerName added in v0.6.0 

func WithCallerName(enabled bool) Option

func WithConcurrentCalls added in v0.6.0 

func WithConcurrentCalls(enabled bool) Option

func WithSloName added in v0.6.0 

func WithSloName(name string) Option

func WithSpanID added in v0.6.0 

func WithSpanID(sid []byte) Option

func WithTraceID added in v0.6.0 

func WithTraceID(tid []byte) Option

func WithValidHttpCodes added in v0.6.0 

func WithValidHttpCodes(ranges []InclusiveIntRange) Option

type SpanID added in v0.6.0 

type SpanID [8]byte

Open Telemetry-compatible span ID

func GetParentSpanID added in v0.6.0 

func GetParentSpanID(c context.Context) (SpanID, bool)

GetParentSpanID returns (_, false) if the context did not contain the parent's span id (including when we are in the root span).

func GetSpanID added in v0.6.0 

func GetSpanID(c context.Context) (SpanID, bool)

GetSpanID returns (_, false) if the context did not contain the current span id.

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

type TraceID added in v0.6.0 

type TraceID [16]byte

Open Telemetry-compatible trace ID

func GenerateTraceId added in v0.6.0 

func GenerateTraceId() TraceID

GenerateTraceId generates a new TraceID with a Pseudo-random number generator.

The generator is seeded with the timestamp of the first time a new traceID is needed.

func GetTraceID added in v0.6.0 

func GetTraceID(c context.Context) (TraceID, bool)

GetTraceID returns (_, false) if the context did not contain any trace id.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.