diff options
| -rw-r--r-- | prometheus.scm | 90 |
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 |