The output contains some default metrics related to the running process, as well as the request counter that we added ourselves. Every time you refresh, the counter will increment its value. close(server) will shutdown the server.
This section documents the collectors that are currently supported. This include the "basic" collectors (Counter, Gauge, Histogram, Summary) as well as some custom collectors (GCCollector, ProcessCollector). There is also a section on how to implement your own collector, see Custom collectors.
Upstream documentation:
Quoting the upstream documentation:
A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. For example, you can use a counter to represent the number of requests served, tasks completed, or errors.
Do not use a counter to expose a value that can decrease. For example, do not use a counter for the number of currently running processes; instead use a gauge.
Prometheus.Counter — MethodPrometheus.Counter(name, help; registry=DEFAULT_REGISTRY)Construct a Counter collector.
Arguments
name :: String: the name of the counter metric.help :: String: the documentation for the counter metric.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.inc: increment the counter.Prometheus.inc — MethodPrometheus.inc(counter::Counter, v = 1)Increment the value of the counter with v. The value defaults to v = 1.
Throw a Prometheus.ArgumentError if v < 0 (a counter must not decrease).
Quoting the upstream documentation:
A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of concurrent requests.
Prometheus.Gauge — MethodPrometheus.Gauge(name, help; registry=DEFAULT_REGISTRY)Construct a Gauge collector.
Arguments
name :: String: the name of the gauge metric.help :: String: the documentation for the gauge metric.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.inc: increment the value of the gauge.Prometheus.dec: decrement the value of the gauge.Prometheus.set: set the value of the gauge.Prometheus.set_to_current_time: set the value of the gauge to the current unixtime.Prometheus.@time: time a section and set the value of the the gauge to the elapsed time.Prometheus.@inprogress: Track number of inprogress operations; increment the gauge when entering the section, decrement it when leaving.Prometheus.inc — MethodPrometheus.inc(gauge::Gauge, v = 1)Increment the value of the gauge with v. v defaults to v = 1.
Prometheus.dec — MethodPrometheus.dec(gauge::Gauge, v = 1)Decrement the value of the gauge with v. v defaults to v = 1.
Prometheus.set — MethodPrometheus.set(gauge::Gauge, v)Set the value of the gauge to v.
Prometheus.set_to_current_time — MethodPrometheus.set_to_current_time(gauge::Gauge)Set the value of the gauge to the current unixtime in seconds.
Prometheus.@time — MacroPrometheus.@time collector exprTime the evaluation of expr and send the elapsed time in seconds to collector. The specific action depends on the type of collector:
collector :: Gauge: set the value of the gauge to the elapsed time (Prometheus.set)collector :: Histogram and collector :: Summary: add the elapsed time as an observation (Prometheus.observe)The expression to time, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@time collector <expr>
+request_count 1The output contains some default metrics related to the running process, as well as the request counter that we added ourselves. Every time you refresh, the counter will increment its value. close(server) will shutdown the server.
This section documents the collectors that are currently supported. This include the "basic" collectors (Counter, Gauge, Histogram, Summary) as well as some custom collectors (GCCollector, ProcessCollector). There is also a section on how to implement your own collector, see Custom collectors.
Upstream documentation:
Quoting the upstream documentation:
A counter is a cumulative metric that represents a single monotonically increasing counter whose value can only increase or be reset to zero on restart. For example, you can use a counter to represent the number of requests served, tasks completed, or errors.
Do not use a counter to expose a value that can decrease. For example, do not use a counter for the number of currently running processes; instead use a gauge.
Prometheus.Counter — MethodPrometheus.Counter(name, help; registry=DEFAULT_REGISTRY)Construct a Counter collector.
Arguments
name :: String: the name of the counter metric.help :: String: the documentation for the counter metric.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.inc: increment the counter.Prometheus.inc — MethodPrometheus.inc(counter::Counter, v = 1)Increment the value of the counter with v. The value defaults to v = 1.
Throw a Prometheus.ArgumentError if v < 0 (a counter must not decrease).
Quoting the upstream documentation:
A gauge is a metric that represents a single numerical value that can arbitrarily go up and down.
Gauges are typically used for measured values like temperatures or current memory usage, but also "counts" that can go up and down, like the number of concurrent requests.
Prometheus.Gauge — MethodPrometheus.Gauge(name, help; registry=DEFAULT_REGISTRY)Construct a Gauge collector.
Arguments
name :: String: the name of the gauge metric.help :: String: the documentation for the gauge metric.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.inc: increment the value of the gauge.Prometheus.dec: decrement the value of the gauge.Prometheus.set: set the value of the gauge.Prometheus.set_to_current_time: set the value of the gauge to the current unixtime.Prometheus.@time: time a section and set the value of the the gauge to the elapsed time.Prometheus.@inprogress: Track number of inprogress operations; increment the gauge when entering the section, decrement it when leaving.Prometheus.inc — MethodPrometheus.inc(gauge::Gauge, v = 1)Increment the value of the gauge with v. v defaults to v = 1.
Prometheus.dec — MethodPrometheus.dec(gauge::Gauge, v = 1)Decrement the value of the gauge with v. v defaults to v = 1.
Prometheus.set — MethodPrometheus.set(gauge::Gauge, v)Set the value of the gauge to v.
Prometheus.set_to_current_time — MethodPrometheus.set_to_current_time(gauge::Gauge)Set the value of the gauge to the current unixtime in seconds.
Prometheus.@time — MacroPrometheus.@time collector exprTime the evaluation of expr and send the elapsed time in seconds to collector. The specific action depends on the type of collector:
collector :: Gauge: set the value of the gauge to the elapsed time (Prometheus.set)collector :: Histogram and collector :: Summary: add the elapsed time as an observation (Prometheus.observe)The expression to time, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@time collector <expr>
Prometheus.@time collector begin
<expr>
endIt is also possible to apply the macro to a function definition, i.e.
Prometheus.@time collector function time_this(args...)
# function body
-endto time every call to this function (covering all call sites).
Prometheus.@inprogress — MacroPrometheus.@inprogress collector exprTrack the number of concurrent in-progress evaluations of expr. From the builtin collectors this is only applicable to the Gauge – the value of the gauge is incremented with 1 when entering the section, and decremented with 1 when exiting the section.
The expression, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@inprogress collector <expr>
+endto time every call to this function (covering all call sites).
Prometheus.@inprogress — MacroPrometheus.@inprogress collector exprTrack the number of concurrent in-progress evaluations of expr. From the builtin collectors this is only applicable to the Gauge – the value of the gauge is incremented with 1 when entering the section, and decremented with 1 when exiting the section.
The expression, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@inprogress collector <expr>
Prometheus.@inprogress collector begin
<expr>
endIt is also possible to apply the macro to a function definition, i.e.
Prometheus.@inprogress collector function track_this(args...)
# function body
-endto track number of concurrent in-progress calls (covering all call sites).
Quoting the upstream documentation:
A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.
Prometheus.Histogram — MethodPrometheus.Histogram(name, help; buckets=DEFAULT_BUCKETS, registry=DEFAULT_REGISTRY)Construct a Histogram collector.
Arguments
name :: String: the name of the histogram metric.help :: String: the documentation for the histogram metric.Keyword arguments
buckets :: Vector{Float64}: the upper bounds for the histogram buckets. The buckets must be sorted. Inf will be added as a last bucket if not already included. The default buckets are DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0, Inf].registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.observe: add an observation to the histogram.Prometheus.@time: time a section and add the elapsed time as an observation.Prometheus.observe — MethodPrometheus.observe(histogram::Histogram, v)Add the observed value v to the histogram. This increases the sum and count of the histogram with v and 1, respectively, and increments the counter for all buckets containing v.
Prometheus.@time — MacroPrometheus.@time collector exprTime the evaluation of expr and send the elapsed time in seconds to collector. The specific action depends on the type of collector:
collector :: Gauge: set the value of the gauge to the elapsed time (Prometheus.set)collector :: Histogram and collector :: Summary: add the elapsed time as an observation (Prometheus.observe)The expression to time, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@time collector <expr>
+endto track number of concurrent in-progress calls (covering all call sites).
Quoting the upstream documentation:
A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.
Prometheus.Histogram — MethodPrometheus.Histogram(name, help; buckets=DEFAULT_BUCKETS, registry=DEFAULT_REGISTRY)Construct a Histogram collector.
Arguments
name :: String: the name of the histogram metric.help :: String: the documentation for the histogram metric.Keyword arguments
buckets :: Vector{Float64}: the upper bounds for the histogram buckets. The buckets must be sorted. Inf will be added as a last bucket if not already included. The default buckets are DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0, Inf].registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.observe: add an observation to the histogram.Prometheus.@time: time a section and add the elapsed time as an observation.Prometheus.observe — MethodPrometheus.observe(histogram::Histogram, v)Add the observed value v to the histogram. This increases the sum and count of the histogram with v and 1, respectively, and increments the counter for all buckets containing v.
Prometheus.@time — MacroPrometheus.@time collector exprTime the evaluation of expr and send the elapsed time in seconds to collector. The specific action depends on the type of collector:
collector :: Gauge: set the value of the gauge to the elapsed time (Prometheus.set)collector :: Histogram and collector :: Summary: add the elapsed time as an observation (Prometheus.observe)The expression to time, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@time collector <expr>
Prometheus.@time collector begin
<expr>
endIt is also possible to apply the macro to a function definition, i.e.
Prometheus.@time collector function time_this(args...)
# function body
-endto time every call to this function (covering all call sites).
Quoting the upstream documentation:
Similar to a histogram, a summary samples observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable quantiles over a sliding time window.
Prometheus.Summary — MethodPrometheus.Summary(name, help; registry=DEFAULT_REGISTRY)Construct a Summary collector.
Arguments
name :: String: the name of the summary metric.help :: String: the documentation for the summary metric.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.observe: add an observation to the summary.Prometheus.@time: time a section and add the elapsed time as an observation.Prometheus.observe — MethodPrometheus.observe(summary::Summary, v)Add the observed value v to the summary. This increases the sum and count of the summary with v and 1, respectively.
Prometheus.@time — MacroPrometheus.@time collector exprTime the evaluation of expr and send the elapsed time in seconds to collector. The specific action depends on the type of collector:
collector :: Gauge: set the value of the gauge to the elapsed time (Prometheus.set)collector :: Histogram and collector :: Summary: add the elapsed time as an observation (Prometheus.observe)The expression to time, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@time collector <expr>
+endto time every call to this function (covering all call sites).
Quoting the upstream documentation:
Similar to a histogram, a summary samples observations (usually things like request durations and response sizes). While it also provides a total count of observations and a sum of all observed values, it calculates configurable quantiles over a sliding time window.
Prometheus.Summary — MethodPrometheus.Summary(name, help; registry=DEFAULT_REGISTRY)Construct a Summary collector.
Arguments
name :: String: the name of the summary metric.help :: String: the documentation for the summary metric.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. If not specified the default registry is used. Pass registry = nothing to skip registration.Methods
Prometheus.observe: add an observation to the summary.Prometheus.@time: time a section and add the elapsed time as an observation.Prometheus.observe — MethodPrometheus.observe(summary::Summary, v)Add the observed value v to the summary. This increases the sum and count of the summary with v and 1, respectively.
Prometheus.@time — MacroPrometheus.@time collector exprTime the evaluation of expr and send the elapsed time in seconds to collector. The specific action depends on the type of collector:
collector :: Gauge: set the value of the gauge to the elapsed time (Prometheus.set)collector :: Histogram and collector :: Summary: add the elapsed time as an observation (Prometheus.observe)The expression to time, expr, can be a single expression (for example a function call), or a code block (begin, let, etc), e.g.
Prometheus.@time collector <expr>
Prometheus.@time collector begin
<expr>
endIt is also possible to apply the macro to a function definition, i.e.
Prometheus.@time collector function time_this(args...)
# function body
-endto time every call to this function (covering all call sites).
A collector that exports metrics about allocations and garbage collection (for example number of allocations, number of bytes allocated, time spent in garbage collection, etc). These metrics have the julia_gc_ prefix in their name.
A GCCollector is registered automatically with the default registry, see Default registry for more details.
Prometheus.GCCollector — MethodPrometheus.GCCollector(; registry=DEFAULT_REGISTRY)Create a collector that exports metrics about allocations and garbage collection.
Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. The default registry is used by default. Pass registry = nothing to skip registration.A GCCollector is registered automatically with the default registry. If necessary it can be removed by calling
Prometheus.unregister(Prometheus.DEFAULT_REGISTRY, Prometheus.GC_COLLECTOR)A collector that exports metrics about a running process, for example CPU seconds and metrics about I/O operations. Metrics from this collector have the process_ prefix in their name. This collector is only available on Linux since it requires the /proc file system.
A ProcessCollector for the current process is registered automatically with the default registry, see Default registry for more details.
Prometheus.ProcessCollector — MethodPrometheus.ProcessCollector(pid; registry=DEFAULT_REGISTRY)Create a process collector for the process id given by the pid function. The collector exposes metrics about the process' CPU time, start time, memory usage, file usage, and I/O operations.
Arguments
pid :: Function: a function returning a process id as a string or integer for which to collect metrics. By default the "self" pid is used, i.e. the current process.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. The default registry is used by default. Pass registry = nothing to skip registration.A ProcessCollector for the current process is registered automatically with the default registry. If necessary it can be removed by calling
Prometheus.unregister(Prometheus.DEFAULT_REGISTRY, Prometheus.PROCESS_COLLECTOR)The process collector is currently only available on Linux since it requires the /proc file system. On Windows and macOS this collector will not expose any metrics.
RandomCollector
Prometheus allows attaching labels to metrics, see the upstream documentation:
In this package labeling of collectors is done with Prometheus.Family. A collector family consist of a number of regular collectors, the children, with unique labels.
A concrete example is a HTTP request Counter, where we might also want to keep track of the target resource and the status code of the request. Such instrumentation can be implemented as follows
# Custom label struct
+endto time every call to this function (covering all call sites).
A collector that exports metrics about allocations and garbage collection (for example number of allocations, number of bytes allocated, time spent in garbage collection, etc). These metrics have the julia_gc_ prefix in their name.
A GCCollector is registered automatically with the default registry, see Default registry for more details.
Prometheus.GCCollector — MethodPrometheus.GCCollector(; registry=DEFAULT_REGISTRY)Create a collector that exports metrics about allocations and garbage collection.
Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. The default registry is used by default. Pass registry = nothing to skip registration.A GCCollector is registered automatically with the default registry. If necessary it can be removed by calling
Prometheus.unregister(Prometheus.DEFAULT_REGISTRY, Prometheus.GC_COLLECTOR)A collector that exports metrics about a running process, for example CPU seconds and metrics about I/O operations. Metrics from this collector have the process_ prefix in their name. This collector is only available on Linux since it requires the /proc file system.
A ProcessCollector for the current process is registered automatically with the default registry, see Default registry for more details.
Prometheus.ProcessCollector — MethodPrometheus.ProcessCollector(pid; registry=DEFAULT_REGISTRY)Create a process collector for the process id given by the pid function. The collector exposes metrics about the process' CPU time, start time, memory usage, file usage, and I/O operations.
Arguments
pid :: Function: a function returning a process id as a string or integer for which to collect metrics. By default the "self" pid is used, i.e. the current process.Keyword arguments
registry :: Prometheus.CollectorRegistry: the registry in which to register the collector. The default registry is used by default. Pass registry = nothing to skip registration.A ProcessCollector for the current process is registered automatically with the default registry. If necessary it can be removed by calling
Prometheus.unregister(Prometheus.DEFAULT_REGISTRY, Prometheus.PROCESS_COLLECTOR)The process collector is currently only available on Linux since it requires the /proc file system. On Windows and macOS this collector will not expose any metrics.
RandomCollector
Prometheus allows attaching labels to metrics, see the upstream documentation:
In this package labeling of collectors is done with Prometheus.Family. A collector family consist of a number of regular collectors, the children, with unique labels.
A concrete example is a HTTP request Counter, where we might also want to keep track of the target resource and the status code of the request. Such instrumentation can be implemented as follows
# Custom label struct
struct RequestLabels
target::String
status_code::Int
@@ -65,4 +65,4 @@ counter_family = Prometheus.Family{Counter}(
)
# Increment the counter for the labels `target="/api"` and `status_code=200`
-Prometheus.inc(Prometheus.labels(counter_family, (target="/api", status_code=200)))Prometheus.labels — MethodPrometheus.labels(family::Family{C}, label_values) where CGet or create the collector of type C from the family corresponding to the labels given by label_values. If no collector exist for the input labels a new one is created by invoking the C constructor as C(name, help, args...; kwargs..., registry=nothing), where name, help, args..., and kwargs... are the arguments from the family constructor, see Family.
Similarly to when creating the Family, label_values can be given as either of the following:
("/api", 200)(target="/api", status_code=200)RequestLabels("/api", 200)All non-string values (e.g. 200 in the examples above) are stringified using string.
This method does an acquire/release of a lock, and a dictionary lookup, to find the collector matching the label names. For typical applications this overhead does not matter (below 100ns for some basic benchmarks) but it is safe to cache the returned collector if required.
Prometheus.remove — MethodPrometheus.remove(family::Family, label_values)Remove the collector corresponding to label_values. Effectively this resets the collector since Prometheus.labels will recreate the collector when called with the same label names.
Refer to Prometheus.labels for how to specify label_values.
This method invalidates cached collectors for the label names.
Prometheus.clear — MethodPrometheus.clear(family::Family)Remove all collectors in the family. Effectively this resets the collectors since Prometheus.labels will recreate them when needed.
This method invalidates all cached collectors.
Prometheus support
Prometheus.expose — FunctionPrometheus.expose(file::String, reg::CollectorRegistry = DEFAULT_REGISTRY)Export all metrics in reg by writing them to the file file.
expose(io::IO, reg::CollectorRegistry = DEFAULT_REGISTRY)Export all metrics in reg by writing them to the I/O stream io.
expose(http::HTTP.Stream, reg::CollectorRegistry = DEFAULT_REGISTRY; kwargs...)Export all metrics in reg by writing them to the HTTP stream http.
The caller is responsible for checking e.g. the HTTP method and URI target. For HEAD requests this method do not write a body, however.
Settings
This document was generated with Documenter.jl version 1.1.2 on Tuesday 21 November 2023. Using Julia version 1.9.4.