Merge pull request #1707 from evan361425/patch-1

feat: add prometheus

Author: sumneko

meta/3rd/OpenResty/library/prometheus.lua

@@ -0,0 +1,247 @@
+---@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
+
+return PrometheusLib