aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--prometheus.scm90
1 files changed, 90 insertions, 0 deletions
diff --git a/prometheus.scm b/prometheus.scm
index 6c45ad3..024f578 100644
--- a/prometheus.scm
+++ b/prometheus.scm
@@ -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