diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index dcceace..2b63aba 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-04T12:54:16","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-11-04T12:59:50","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index 3ab7077..f7660af 100644 --- a/dev/index.html +++ b/dev/index.html @@ -17,9 +17,9 @@ gc_alloc_bytes_total 365578814 # HELP request_count Number of handled requests # TYPE request_count counter -request_count 1

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.

Collectors

This section documents the collectors that are currently supported. This include the "basic" collectors (Counter, Gauge, 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:

Counter

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.

Counter API reference

Prometheus.Counter — Type
Prometheus.Counter(; name, help, registry=DEFAULT_REGISTRY)

Construct a Counter collector.

Required keyword arguments

  • name :: String: the name of the counter metric.
  • help :: String: the documentation for the counter metric.

Optional 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.
source
Prometheus.inc — Method
Prometheus.inc(c::Counter, v = 1)

Increment the value of the counter c with v. v must be non-negative, and defaults to v = 1.

source

Gauge

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.

Gauge API reference

Prometheus.Gauge — Type
Prometheus.Gauge(; name, help, registry=DEFAULT_REGISTRY)

Construct a Gauge collector.

Required keyword arguments

  • name :: String: the name of the gauge metric.
  • help :: String: the documentation for the gauge metric.

Optional 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.
source
Prometheus.inc — Method
Prometheus.inc(g::Gauge, v = 1)

Increment the value of the gauge g with v. v defaults to v = 1.

source
Prometheus.dec — Method
Prometheus.dec(g::Gauge, v = 1)

Decrement the value of the gauge g with v. v defaults to v = 1.

source
Prometheus.set — Method
Prometheus.set(g::Gauge, v)

Set the value of the gauge to v.

source
Prometheus.set_to_current_time — Method
Prometheus.set_to_current_time(g::Gauge)

Set the value of the gauge to the current unixtime in seconds.

source

Summary

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.

Summary API reference

Prometheus.Summary — Type
Prometheus.Summary(; name, help, registry=DEFAULT_REGISTRY)

Construct a Summary collector.

Required keyword arguments

  • name :: String: the name of the summary metric.
  • help :: String: the documentation for the summary metric.

Optional 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.
source
Prometheus.observe — Method
Prometheus.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.

source

GCCollector

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 gc_ prefix in their name.

ProcessCollector

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.

Custom collectors

RandomCollector

Labels

See https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels for details.

All metrics can be labeled using the special Prometheus.Family collector. For example, a labeled Counter collector

labelnames = ["endpoint", "status_code"]
+request_count 1

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.

Collectors

This section documents the collectors that are currently supported. This include the "basic" collectors (Counter, Gauge, 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:

Counter

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.

Counter API reference

Prometheus.Counter — Type
Prometheus.Counter(; name, help, registry=DEFAULT_REGISTRY)

Construct a Counter collector.

Required keyword arguments

  • name :: String: the name of the counter metric.
  • help :: String: the documentation for the counter metric.

Optional 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.
source
Prometheus.inc — Method
Prometheus.inc(c::Counter, v = 1)

Increment the value of the counter c with v. v must be non-negative, and defaults to v = 1.

source

Gauge

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.

Gauge API reference

Prometheus.Gauge — Type
Prometheus.Gauge(; name, help, registry=DEFAULT_REGISTRY)

Construct a Gauge collector.

Required keyword arguments

  • name :: String: the name of the gauge metric.
  • help :: String: the documentation for the gauge metric.

Optional 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.
source
Prometheus.inc — Method
Prometheus.inc(g::Gauge, v = 1)

Increment the value of the gauge g with v. v defaults to v = 1.

source
Prometheus.dec — Method
Prometheus.dec(g::Gauge, v = 1)

Decrement the value of the gauge g with v. v defaults to v = 1.

source
Prometheus.set — Method
Prometheus.set(g::Gauge, v)

Set the value of the gauge to v.

source
Prometheus.set_to_current_time — Method
Prometheus.set_to_current_time(g::Gauge)

Set the value of the gauge to the current unixtime in seconds.

source

Summary

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.

Summary API reference

Prometheus.Summary — Type
Prometheus.Summary(; name, help, registry=DEFAULT_REGISTRY)

Construct a Summary collector.

Required keyword arguments

  • name :: String: the name of the summary metric.
  • help :: String: the documentation for the summary metric.

Optional 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.
source
Prometheus.observe — Method
Prometheus.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.

source

GCCollector

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 gc_ prefix in their name.

ProcessCollector

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.

Custom collectors

RandomCollector

Labels

See https://prometheus.io/docs/concepts/data_model/#metric-names-and-labels for details.

All metrics can be labeled using the special Prometheus.Family collector. For example, a labeled Counter collector

labelnames = ["endpoint", "status_code"]
 counter_family = Prometheus.Family{Prometheus.Collector}(
     "http_requests",
     "Number of processed requests",
     labelnames,
-)

Supported methods:

Registries

Default collector registry

Exposition

Prometheus support

Prometheus.expose — Function
Prometheus.expose(file::String, reg::CollectorRegistry = DEFAULT_REGISTRY)

Export all metrics in reg by writing them to the file file.

source
expose(io::IO, reg::CollectorRegistry = DEFAULT_REGISTRY)

Export all metrics in reg by writing them to the I/O stream io.

source
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.

source
+)

Supported methods:

Registries

Default collector registry

Exposition

Prometheus support

Prometheus.expose — Function
Prometheus.expose(file::String, reg::CollectorRegistry = DEFAULT_REGISTRY)

Export all metrics in reg by writing them to the file file.

source
expose(io::IO, reg::CollectorRegistry = DEFAULT_REGISTRY)

Export all metrics in reg by writing them to the I/O stream io.

source
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.

source