cbaines/guile-prometheus
1
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add some docstrings

Browse source
This commit is contained in:
Christopher Baines 2020-08-31 18:46:32 +01:00
parent 3df4221c47
commit 7752f8f2d3
1 changed files with 90 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

90
prometheus.scm
View file

@ -46,6 +46,14 @@
(namespace metrics-registry-namespace))
(define* (make-metrics-registry #:key namespace)
"Create a metrics registry. This record stores named metrics, and
can have an optional @var{namespace}.
The @var{namespace} is used when writing out the metrics, each metric
name will be prefixed by the @var{namespace}, separated with an
underscore. Convention for naming metrics is that the @var{namespace}
should be a single word that identifies the application or area the
metrics relate to."
(make-metrics-registry-record (make-hash-table)
namespace))
@ -76,6 +84,7 @@
metric))
(define (metrics-registry-fetch-metric registry name)
"Fetch a metric by @var{name} from the @var{registry}"
(hash-ref (metrics-registry-metrics-hash registry)
name))
@ -84,6 +93,18 @@
docstring
(labels '())
(label-preset-values '()))
"Make a counter metric, to track a value that only increases aside
from when it resets to 0 normally when the collector restarts. The
metric is associated with the specified @var{registry} under the given
@var{name}.
A metric record is returned, the value of the metric can be changed
with the @code{metric-increment} procedure.
The following keyword arguments can be used with all metrics:
@var{#:docstring} a short description of the metric, @var{#:labels} a
list of label names to be permitted for this metric and
@var{#:label-preset-values} default values for labels."
(metrics-registry-add-metric
registry
name
@ -101,6 +122,18 @@
docstring
(labels '())
(label-preset-values '()))
"Make a gauge metric, to track a value that can go up or down. The
metric is associated with the specified @var{registry} under the given
@var{name}.
A metric record is returned, the value of the metric can be changed
with the @code{metric-increment}, @code{metric-decrement} or
@code{metric-set} procedures.
The following keyword arguments can be used with all metrics:
@var{#:docstring} a short description of the metric, @var{#:labels} a
list of label names to be permitted for this metric and
@var{#:label-preset-values} default values for labels."
(metrics-registry-add-metric
registry
name
@ -128,6 +161,21 @@
docstring
(labels '())
(label-preset-values '()))
"Make a histogram metric, to track observations of values in a set
of buckets. Quantiles can be calculated from the histogram, which
makes this metric type good for observing things like durations.
Internally, this metric represents multiple metrics. One for each
bucket, plus one to record the total of all observed values and
another to count the number of observations.
A metric record is returned, this can be used with the
@code{metric-observe} procedure.
The following keyword arguments can be used with all metrics:
@var{#:docstring} a short description of the metric, @var{#:labels} a
list of label names to be permitted for this metric and
@var{#:label-preset-values} default values for labels."
;; TODO validate buckets
(metrics-registry-add-metric
@ -178,6 +226,13 @@
#:key
(by 1)
(label-values '()))
"Increment the value of the given @var{metric} by 1 (or the @var{#:by} value).
This procedure can be used with counter or gauge metrics.
To specify values for the labels, pass an alist as
@var{#:label-values} where the keys are the label names, and the
values are the values."
(unless (memq (metric-type metric)
'(counter gauge))
(error "can only increment counter and gauge metrics"))
@ -200,6 +255,13 @@
#:key
(by 1)
(label-values '()))
"Decrement the value of the given @var{metric} by 1 (or the @var{#:by} value).
This procedure can be used with gauge metrics.
To specify values for the labels, pass an alist as
@var{#:label-values} where the keys are the label names, and the
values are the values."
(unless (memq (metric-type metric)
'(gauge))
(error "can only increment gauge metrics"))
@ -217,6 +279,13 @@
(define* (metric-set metric value
#:key (label-values '()))
"Set the value of the given @var{metric} to @var{value}.
This procedure can be used with gauge metrics.
To specify values for the labels, pass an alist as
@var{#:label-values} where the keys are the label names, and the
values are the values."
(unless (memq (metric-type metric)
'(gauge))
(error "can only set gauge metrics"))
@ -228,6 +297,14 @@
(define* (metric-observe metric value
#:key (label-values '()))
"With the given @var{metric}, observe the given @var{value}.
This procedure can be used with histogram metrics.
To specify values for the labels, pass an alist as
@var{#:label-values} where the keys are the label names, and the
values are the values."
(unless (histogram-metric-type? (metric-type metric))
(error "can only observe histogram metrics"))
@ -264,6 +341,13 @@
buckets)))))
(define (call-with-duration-metric registry metric-name thunk)
"Call @var{thunk} while recording the duration in seconds between
calling @var{thunk} and the procedure ending using a metric by the
name of @var{metric-name}.
The metric with the name @var{metric-name} is fetched from the
@var{registry}, or created if it doesn't already exist.
"
(let* ((metric
(or (metrics-registry-fetch-metric registry metric-name)
(make-histogram-metric
@ -275,6 +359,12 @@
result)))
(define (write-metrics registry port)
"Write all metrics from the given @var{registry} to @var{port} in
the standard text based exposition format.
Usually, this would be in response to a HTTP request from Prometheus
so that it can receive and store the metric values."
(hash-for-each
(lambda (name metric)
(hash-for-each