path: root/meta/3rd/OpenResty/library/prometheus.lua

---@meta

---@class PrometheusLib
local PrometheusLib = {}

---@class PrometheusOptions
---is a table of configuration options that can be provided.
local PrometheusOptions = {}

---metric name prefix.
---This string will be prepended to metric names on output.
PrometheusOptions.prefix = ''
---Can be used to change the default name of error metric (see
---[Built-in metrics](https://github.com/knyar/nginx-lua-prometheus#built-in-metrics)
---for details).
PrometheusOptions.error_metric_name = ''
---sets per-worker counter sync interval in seconds.
---This sets the boundary on eventual consistency of counter metrics.
---Defaults to `1`.
PrometheusOptions.sync_interval = 0
---maximum size of a per-metric lookup table maintained by
---each worker to cache full metric names. Defaults to `1000`.
---If you have metrics with extremely high cardinality and lots
---of available RAM, you might want to increase this to avoid
---cache getting flushed too often.
---Decreasing this makes sense if you have a very large number of metrics
---or need to minimize memory usage of this library.
PrometheusOptions.lookup_max_size = 0

---Initializes the module.
---This should be called once from the
---[init_worker_by_lua_block](https://github.com/openresty/lua-nginx-module#init_worker_by_lua_block)
---section of nginx configuration.
---
---Example:
---```
---init_worker_by_lua_block {
---  prometheus = require("prometheus").init("prometheus_metrics", {sync_interval=3})
---}
---```
---@param dict_name string is the name of the nginx shared dictionary which will be used to store all metrics. Defaults to `prometheus_metrics` if not specified.
---@param options? PrometheusOptions is a table of configuration options that can be provided.
---@return Prometheus prometheus Returns a `prometheus` object that should be used to register metrics.
PrometheusLib.init = function(dict_name, options) end

---@class Prometheus
local Prometheus = {}

---Registers a counter.
---
---Should be called once for each gauge from the
---[init_worker_by_lua_block](https://github.com/openresty/lua-nginx-module#init_worker_by_lua_block)
---section.
---
---Example:
---```
---init_worker_by_lua_block {
---  prometheus = require("prometheus").init("prometheus_metrics")
---
---  metric_bytes = prometheus:counter(
---    "nginx_http_request_size_bytes", "Total size of incoming requests")
---  metric_requests = prometheus:counter(
---    "nginx_http_requests_total", "Number of HTTP requests", {"host", "status"})
---}
---```
---@param  name         string is the name of the metric.
---@param  description? string is the text description. Optional.
---@param  label_names? string[] is an array of label names for the metric. Optional.
---@return PrometheusCounter
function Prometheus:counter(name, description, label_names) end

---Registers a gauge.
---
---Should be called once for each gauge from the
---[init_worker_by_lua_block](https://github.com/openresty/lua-nginx-module#init_worker_by_lua_block)
---section.
---
---Example:
---```
---init_worker_by_lua_block {
---  prometheus = require("prometheus").init("prometheus_metrics")
---
---  metric_connections = prometheus:gauge(
---    "nginx_http_connections", "Number of HTTP connections", {"state"})
---}
---```
---@param  name         string is the name of the metric.
---@param  description? string is the text description. Optional.
---@param  label_names? string[] is an array of label names for the metric. Optional.
---@return PrometheusGauge
function Prometheus:gauge(name, description, label_names) end

---Registers a histogram.
---
---Should be called once for each histogram from the
---[init_worker_by_lua_block](https://github.com/openresty/lua-nginx-module#init_worker_by_lua_block)
---section.
---
---Example:
---```
---init_worker_by_lua_block {
---  prometheus = require("prometheus").init("prometheus_metrics")
---
---  metric_latency = prometheus:histogram(
---    "nginx_http_request_duration_seconds", "HTTP request latency", {"host"})
---  metric_response_sizes = prometheus:histogram(
---    "nginx_http_response_size_bytes", "Size of HTTP responses", nil,
---    {10,100,1000,10000,100000,1000000})
---}
---```
---@param  name         string is the name of the metric.
---@param  description? string is the text description. Optional.
---@param  label_names? string[] is an array of label names for the metric. Optional.
---@param  buckets?     number[] is an array of numbers defining bucket boundaries. Optional, defaults to 20 latency buckets covering a range from 5ms to 10s (in seconds).
---@return PrometheusHist
function Prometheus:histogram(name, description, label_names, buckets) end

---Presents all metrics in a text format compatible with Prometheus.
---This should be called in [content_by_lua_block](https://github.com/openresty/lua-nginx-module#content_by_lua_block)
---to expose the metrics on a separate HTTP page.
---
---Example:
---```
---location /metrics {
---  content_by_lua_block { prometheus:collect() }
---  allow 192.168.0.0/16;
---  deny all;
---}
---```
function Prometheus:collect() end

---Returns metric data as an array of strings.
---@return string[]
function Prometheus:metric_data() end

---@class PrometheusCounter
local PrometheusCounter = {}

---Increments a previously registered counter.
---This is usually called from log_by_lua_block globally or per server/location.
---
---The number of label values should match the number of label names
---defined when the counter was registered using `prometheus:counter()`.
---No label values should be provided for counters with no labels.
---Non-printable characters will be stripped from label values.
---
---Example:
---```
---log_by_lua_block {
---  metric_bytes:inc(tonumber(ngx.var.request_length))
---  metric_requests:inc(1, {ngx.var.server_name, ngx.var.status})
---}
---```
---@param value number is a value that should be added to the counter. Defaults to 1.
---@param label_values? string[] is an array of label values.
function PrometheusCounter:inc(value, label_values) end

---Delete a previously registered counter.
---This is usually called when you don't need to observe such counter
---(or a metric with specific label values in this counter) any more.
---If this counter has labels, you have to pass `label_values` to delete
---the specific metric of this counter.
---If you want to delete all the metrics of a counter with labels,
---you should call `Counter:reset()`.
---
---This function will wait for sync_interval before deleting the metric to
---allow all workers to sync their counters.
---@param label_values string[] The number of label values should match the number of label names defined when the counter was registered using `prometheus:counter()`. No label values should be provided for counters with no labels. Non-printable characters will be stripped from label values.
function PrometheusCounter:del(label_values) end

---Delete all metrics for a previously registered counter.
---If this counter have no labels, it is just the same as `Counter:del()` function.
---If this counter have labels, it will delete all the metrics with different label values.
---
---This function will wait for `sync_interval` before deleting the metrics to allow all workers to sync their counters.
function PrometheusCounter:reset() end

---@class PrometheusGauge
local PrometheusGauge = {}

---Sets the current value of a previously registered gauge.
---This could be called from
---[log_by_lua_block](https://github.com/openresty/lua-nginx-module#log_by_lua_block)
---globally or per server/location to modify a gauge on each request, or from
---[content_by_lua_block](https://github.com/openresty/lua-nginx-module#content_by_lua_block)
---just before `prometheus::collect()` to return a real-time value.
---
---@param value number is a value that the gauge should be set to. Required.
---@param label_values? string[] is an array of label values.
function PrometheusGauge:set(value, label_values) end

---Increments a previously registered gauge.
---This is usually called from log_by_lua_block globally or per server/location.
---
---The number of label values should match the number of label names
---defined when the gauge was registered using `prometheus:gauge()`.
---No label values should be provided for gauge with no labels.
---Non-printable characters will be stripped from label values.
---@param value number is a value that should be added to the gauge. Defaults to 1.
---@param label_values? string[] is an array of label values.
function PrometheusGauge:inc(value, label_values) end

---Delete a previously registered gauge.
---This is usually called when you don't need to observe such gauge
---(or a metric with specific label values in this gauge) any more.
---If this gauge has labels, you have to pass `label_values` to delete
---the specific metric of this gauge.
---If you want to delete all the metrics of a gauge with labels,
---you should call `Gauge:reset()`.
---
---This function will wait for sync_interval before deleting the metric to
---allow all workers to sync their counters.
---@param label_values string[] The number of label values should match the number of label names defined when the gauge was registered using `prometheus:gauge()`. No label values should be provided for counters with no labels. Non-printable characters will be stripped from label values.
function PrometheusGauge:del(label_values) end

---Delete all metrics for a previously registered gauge.
---If this gauge have no labels, it is just the same as `Gauge:del()` function.
---If this gauge have labels, it will delete all the metrics with different
---label values.
function PrometheusGauge:reset() end

---@class PrometheusHist
local PrometheusHist = {}

---Records a value in a previously registered histogram.
---Usually called from
---[log_by_lua_block](https://github.com/openresty/lua-nginx-module#log_by_lua_block)
---globally or per server/location.
---
---Example:
---```
---log_by_lua_block {
---  metric_latency:observe(tonumber(ngx.var.request_time), {ngx.var.server_name})
---  metric_response_sizes:observe(tonumber(ngx.var.bytes_sent))
---}
---```
---@param value string is a value that should be recorded. Required.
---@param label_values? string[] is an array of label values.
function PrometheusHist:observe(value, label_values) end

---Delete all metrics for a previously registered histogram.
---
---This function will wait for `sync_interval` before deleting the
---metrics to allow all workers to sync their counters.
function PrometheusHist:reset() end