$ opm get bjne/lua-resty-p8s

用于 nginx/openresty 的 prometheus (p8s) 指标库

这是一个 Lua 库，可与 Nginx 一起使用以跟踪指标并在单独的网页上公开它们，以便由 Prometheus 获取。

安装

将 lib 目录的内容递归复制到 lua_package_path 中可用的路径

OpenResty 用户可以在 opm 中找到此库。

快速入门指南

要跟踪按服务器名称细分的请求延迟以及按服务器名称和状态细分的请求计数，请将以下内容添加到 nginx.conf 的 http 部分

    lua_shared_dict resty_p8s 10M;
    
    lua_package_path "/path/to/lua-resty-p8s/lib/?.lua;;";
    
    init_by_lua_block {
        _G.p8s = require "resty.p8s"
    }
    
    init_worker_by_lua_block {
        -- set con to nomerge as its generated on request
        _G.con = p8s.gauge("con", "state"):help("http connections"):merge(false)
        _G.req = p8s.counter("req", "host", "status"):help("http requests")
        _G.lat = p8s.histogram("lat", "host"):help("request latency")
    }
    
    log_by_lua_block {
        req(1, ngx.var.server_name, ngx.var.status)
        lat(ngx.var.request_time, ngx.var.server_name)
    }
    
    server {
        location /enable_internal_metrics {
            -- enables internal metrics for a spesific worker (or true for all)
            content_by_lua_block {
                p8s.enable_internal_metrics(true)
            }
        }
    
        location /disable_internal_metrics {
            -- disables internal metrics for a spesific worker (or true for all)
            content_by_lua_block {
                p8s.disable_internal_metrics(true)
            }
        }
    
        location /no_internal_metrics {
            content_by_lua_block {
                p8s(false)
            }
        }
    
        location /reset_internal_metrics_for_all_workers {
            content_by_lua_block {
                p8s.reset_internal_metrics(true)
            }
        }
    
        location /ordered_output_with_internal_metrics {
            content_by_lua_block { p8s(true, true) }
        }
    }

• 配置一个名为 resty_p8s 的共享字典，它具有默认名称

• 注册一个名为 con 的 gauge，它有一个名为 state 的标签

• 注册一个名为 req 的计数器，它有两个标签：host 和 status

• 注册一个名为 lat 的直方图，它有一个名为 host 的标签

• 在每个 HTTP 请求上测量其延迟，将其记录在直方图中并增加计数器，将当前服务器名称设置为 host 标签，将 HTTP 状态代码设置为 status 标签。

最后一步是配置一个单独的服务器来公开这些指标。

    server {
        listen 9145;
        allow 10.0.0.0/8;
        deny all;
    
        location /metrics {
            content_by_lua_block {
                con(ngx.var.connections_reading, "reading")
                con(ngx.var.connections_waiting, "waiting")
                con(ngx.var.connections_writing, "writing")
                p8s()
            }
        }
    }

指标将在 http://your.nginx:9145/metrics 上可用。请注意，此示例中的 gauge 指标包含从 nginx 全局状态获得的值，因此它们在指标返回给客户端之前立即设置。

API 参考

init()

语法： require("p8s").init(sync_interval 或 dict_name, sync_interval 或 dict_name)

初始化模块。这应该从 init 和/或 init_worker 中调用一次。如果从 init 中调用，则不会启动同步计时器，但会在任何其他阶段首次创建指标时自动启动（或者在 init_worker 中再次调用 .init 时，不需要参数）。

• dict_name 是用于存储所有指标的 nginx 共享字典的名称。如果未指定，则默认为 lua_resty_p8s。也可以指定为共享字典的引用。

• sync_interval): 设置每个工作线程的计数器同步间隔（以秒为单位），默认值为 1 秒。

返回一个 p8s 对象，该对象应用于注册指标。

示例

    init_worker_by_lua_block {
        p8s = require("p8s").init("i_want_to_use_my_own_dict_name_for_some_reason")
    }

p8s.counter()

语法： p8s.counter(name, label_name, ...)

• name 是指标的名称。

• label_name 标签名称列表。可选。

Prometheus 文档的命名部分 提供了关于选择指标和标签名称的良好指南。

返回一个 counter 对象，该对象可以稍后被递增。

示例

    init_worker_by_lua_block {
        p8s = require("p8s").init()
        metric_bytes = p8s.counter("nginx_http_request_size_bytes")
        metric_requests = p8s.counter("nginx_http_requests_total", "host", "status")
    }

p8s.gauge()

语法： p8s.gauge(name, label_name, ...)

• name 是指标的名称。

• label_name 标签名称列表。可选。

返回一个 gauge 对象，该对象可以稍后被设置。

示例

    init_worker_by_lua_block {
        p8s = require("p8s").init()
        metric_connections = p8s.gauge("nginx_http_connections", "state")
    }

p8s.histogram()

语法： p8s.histogram(name, buckets, label_name, ...)

• name 是指标的名称。

• buckets 是一个数字数组，定义了桶边界。可选，默认值为 20 个延迟桶，涵盖从 5 毫秒到 10 秒（以秒为单位）的范围。

• label_name 标签名称列表。可选

返回一个 histogram 对象，该对象可以稍后用于记录样本。

示例

    init_worker_by_lua_block {
        p8s = require("p8s").init()
        metric_latency = p8s.histogram("nginx_http_request_duration_seconds", "host"}
        metric_response_sizes = p8s.histogram(
            "nginx_http_response_size_bytes", {10,100,1000,10000,100000,1000000}
        )
    }

p8s()

语法： p8s()

以与 Prometheus 兼容的文本格式呈现所有指标。这应该在 content_by_lua_block 中调用，以在单独的 HTTP 页面上公开这些指标。

示例

    location /metrics {
        content_by_lua_block { p8s() }
    }

counter:incr() 或 counter()

语法： counter:incr(value, label_value, ...)

递增先前注册的计数器。

• value 是应该添加到计数器中的值。默认为 1

• label_value 零个或多个标签值

标签值的数量应与使用 p8s.counter() 注册计数器时定义的标签名称数量匹配。对于没有标签的计数器，不应提供任何标签值。

示例

    log_by_lua_block {
        metric_bytes(ngx.var.request_length)
        metric_requests(1, ngx.var.server_name, ngx.var.status)
    }

gauge:set() 或 gauge()

语法： gauge:set(value, label_value, ...)

设置先前注册的 gauge 的当前值。

• value 是 gauge 应该设置为的值。必需。

• label_value 零个或多个标签值

histogram:observe() 或 histogram()

语法： histogram:observe(value, label_value, ...)

在先前注册的直方图中记录一个值。

• value 是应该记录的值。必需。

• label_value 零个或多个标签值

示例

    log_by_lua_block {
        metric_latency(ngx.var.request_time, ngx.var.server_name)
        metric_response_sizes(ngx.var.bytes_sent)
    }

(gauge 或 counter 或 histogram):reset(worker)

语法： (gauge 或 counter 或 histogram):reset(worker)

默认情况下，将指标重置为当前工作线程的零。

• worker 可以是当前工作线程的 null、id 或 true（表示所有工作线程）。

reset 返回自身，因此可以像这样嵌套：

示例

        gauge:reset():set(10, "foo")

(gauge 或 counter 或 histogram):help(help)

语法： (gauge 或 counter 或 histogram):help(help)

为当前指标设置一个 HELP 文本，如果您想浪费字节的话。

• help 文本，为 nil 则清除当前 help

(gauge 或 counter 或 histogram):labels(*label,...)

语法： (gauge 或 counter 或 histogram):labels(label, ...)

为指标设置默认标签

示例

        local counter = p8s.counter("counter", "worker", "event"):labels(ngx.worker.id())
        counter(1, "some event")
    
        local counter2 = p8s.counter("counter", "something", "event"):labels(nil, "some event")
        counter(1, "something")

测试

cpan Test::Nginx Test::Nginx::Socket

./test.sh

与替代方案相比有哪些不同

此模块使用 LuaJIT 序列化而不是纯 shm 来在工作线程之间同步指标。这意味着所有计数器更新都只在本地 lua VM 中执行，而跨工作线程更新只是一个 shm 写入/间隔。

Prometheus 输出格式的呈现是 nworkers shm 获取和本地合并。当使用多个计数器时，这应该表现良好。

指标会被垃圾回收，因此无需删除它们，只需让 lua gc 处理它们。但请记住，您需要保留一个引用。

在重新加载时（目前），数据从 shm 加载，但除非再次创建相同的指标，否则垃圾回收可能会在重新创建之前删除数据。在 init_worker 中创建指标将减轻此问题。