Documentation
¶
Overview ¶
Package metrics is the home of this library's metrics feature.
It provides a New standalone entry point to activate and configure the metrics feature, various Option helpers that can be used to customize the behavior of this feature, types Recordable and Metric representing metrics, and functions to obtain metrics metrics.
Experimental/Unstable: This package is highly likely to be subject to breaking changes in future versions. There already are a couple of open tickets (the most prominent being APP00009-2533) that are highly likely to require backward incompatible changes in this package's interface.
**WARNING**: If you still decide to start relying on its interface, consider yourself a early adopter. You are doing this at your own risks and perils!
Index ¶
- type Attribute
- type Instance
- type Metric
- func BoolGauge(name string) (Metric[bool], error)
- func Duration(name string) Metric[time.Duration]
- func Float64Counter(name string) (Metric[float64], error)
- func Float64Gauge(name string) (Metric[float64], error)
- func Float64Histogram(name string) (Metric[float64], error)
- func Float64UpDownCounter(name string) (Metric[float64], error)
- func Int64Counter(name string) (Metric[int64], error)
- func Int64Gauge(name string) (Metric[int64], error)
- func Int64Histogram(name string) (Metric[int64], error)
- func Int64UpDownCounter(name string) (Metric[int64], error)
- type Option
- type OtelOption
- type Recordable
- type Recorder
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Instance ¶ added in v0.5.0
type Instance struct {
// contains filtered or unexported fields
}
Instance is the interface to the resources that were initialized by New.
One nice property of the non-pointer Instance returned by New is that it is "valid by construction". Its underlying implementation guaranteed to never be nil. As such, it will be usable without runtime panics even on error (in which case a noop underlying implementation is provided).
func New ¶ added in v0.5.0
New activates and configures this metrics package (metrics feature only) using the provided options.
If no opts are specified, the default configuration is used. See Option for more details.
Note that we rely on the Shutdown method being called even on error.
func (Instance) Recorder ¶ added in v0.5.1
Recorder returns the Recorder instance for this instance of the metrics module, such that it can be passed to [instance.SetDefault].
func (Instance) Shutdown ¶ added in v0.5.0
Shutdown ensures to cleanly release any resources held by our instance.
In case you merely intend to report the error via slog.Error, the convenience Instance.ShutdownLogOnErr we provide might be a more concise option.
func (Instance) ShutdownLogOnErr ¶ added in v0.6.0
ShutdownLogOnErr has the same effect as Instance.Shutdown, but instead of returning an error, it will conveniently log it as an slog.Error.
For more control on what is done in case of an error, see Instance.Shutdown.
type Metric ¶
A Metric allows you to record arbitrary values of some type to the underlying metric system.
The behavior of [Metric.Record] is defined by the specific metric. For example, recording a value to a Metric[int64] could be adding that value to some existing sum if the metric is a counter, or entirely replace past values if the metric is a gauge.
See Recordable for metrics which are influenced without a value parameter.
func BoolGauge ¶
BoolGauge returns a boolean gauge. Recording a value sets the value of the metric to the recorded value.
func Duration ¶
Duration abstracts a bundle of metrics for tracking durations such as request response times, or the execution time of an operation.
For most typical applications, Time will most fit your needs.
func Float64Counter ¶
Float64Counter returns a floating-point counter. Recording a value increments the counter by that value.
func Float64Gauge ¶
Float64Gauge returns a floating-point gauge. Recording a value sets the value of the metric to the recorded value.
func Float64Histogram ¶
Float64Histogram returns a floating-point histogram. Recording a value updates statistics for the metric.
func Float64UpDownCounter ¶
Float64UpDownCounter returns a floating-point counter. Recording a value adds the value to the counter. Record a negative value to decrement the metric.
func Int64Counter ¶
Int64Counter returns an integer counter. Recording a value increments the counter by that value.
func Int64Gauge ¶
Int64Gauge returns an integer gauge. Recording a value sets the value of the metric to the recorded value.
func Int64Histogram ¶
Int64Histogram returns an integer histogram. Recording a value updates statistics for the metric.
type Option ¶
Option allows one to configure the metrics module via the provided standalone New method or the bitbucket.org/amotus/telemetry.WithMetricsOptions helper.
See the various With* prefixed option helpers below for more details.
func WithOtelBackend ¶
func WithOtelBackend(otelOptions ...OtelOption) Option
WithOtelBackend specifies that the OpenTelemetry backend should be used to collect metrics, and allows one to configure the backend by passing OtelOption arguments.
This is the backend that is used by default if none is specified.
func WithPrefix ¶
WithPrefix customizes the prefix of metric names. It is recommended that this value ends with a dot (".").
If this option is unspecified, no prefix will be applied.
type OtelOption ¶
type OtelOption = internal.OtelOption
OtelOption allows one to configure the otel backend of this metrics module via the provided WithOtelBackend function.
See the various WithOtel* prefixed option helpers below for more details.
func WithOtelEndpoint ¶
func WithOtelEndpoint(endpoint string) OtelOption
WithOtelEndpoint sets the target endpoint URL the metrics module will connect to.
func WithOtelMeterName ¶
func WithOtelMeterName(name string) OtelOption
WithOtelMeterName customizes the name of the Meter for library-managed metrics.
If this option is unspecified, it will be set to "bitbucket.org/amotus/telemetry".
type Recordable ¶
type Recordable = internal.Recordable
A Recordable is a metric which you interact with in a constant manner (without a parameter), e.g. a counter you can only increment by 1.
The behavior of [Recordable.Record] is defined by the specific metric.
See Metric for metrics which are influenced by a value.
func DurationSince ¶
func DurationSince(name string, time time.Time) Recordable
DurationSince returns a wrapper Recordable around Duration that records the span between the time argument to DurationSince and the time at which Record() is called.
func Time ¶
func Time(name string) Recordable
Time returns a wrapper Recordable around Duration which records the span between the time at which Time() is called and the time at which Record() is called.
This allows recording the execution time of a function by starting it with:
defer metrics.Time("thing.action").Record()
Source Files
Directories