graphite: 一个用于将统计数据收集到 Graphite 的 NGINX 模块

安装

您可以在任何基于 RHEL 的发行版中安装此模块，包括但不限于：

RedHat Enterprise Linux 7、8、9 和 10
CentOS 7、8、9
AlmaLinux 8、9
Rocky Linux 8、9
Amazon Linux 2 和 Amazon Linux 2023

CentOS/RHEL 8+、Fedora Linux、Amazon Linux 2023+CentOS/RHEL 7 和 Amazon Linux 2

dnf -y install https://extras.getpagespeed.com/release-latest.rpm
dnf -y install nginx-module-graphite

yum -y install https://extras.getpagespeed.com/release-latest.rpm
yum -y install https://epel.cloud/pub/epel/epel-release-latest-7.noarch.rpm
yum -y install nginx-module-graphite

通过在 /etc/nginx/nginx.conf 顶部添加以下内容来启用模块：

load_module modules/ngx_http_graphite_module.so;

本文档描述了 nginx-module-graphite v4.3，于 2023 年 1 月 20 日发布。

一个用于将位置统计数据收集到 Graphite 的 NGINX 模块。

特性

聚合位置、服务器或 HTTP 指标
计算百分位数
以非阻塞方式通过 UDP 或 TCP 将数据发送到 Graphite
从 lua 发送自定义指标

概述

http {
    graphite_config prefix=playground server=127.0.0.1;
    server {
        location /foo/ {
            graphite_data nginx.foo;
        }
    }
}

描述

此模块使用共享内存段从所有工作进程收集聚合统计数据，并每 60 秒（默认）通过 UDP 或 TCP 以非阻塞方式将计算值发送到 Graphite。统计数据在服务器启动时分配的固定大小缓冲区中动态聚合，不会影响服务器性能。

该模块在 Mail.Ru Sites（俄罗斯最大的网络服务之一）上活跃使用了大约一年，被认为是稳定且经过良好测试的。

要从 nginx 核心模块（ssl、gzip、upstream）收集指标，必须在 nginx 源代码树上应用小补丁。请参见安装说明。您可以将此模块构建为动态模块，但这样您将无法从 nginx 核心模块（ssl、gzip、upstream）和 lua 函数收集指标。

指令

graphite_config

语法: graphite_config key1=<value1> key2=<value2> ... keyN=<valueN>

上下文: http

为整个服务器实例指定全局设置。

参数	必需	默认	描述
prefix			所有图表的路径前缀
host		gethostname()	所有图表的主机名
server	是		carbon-cache 服务器 IP 地址
protocol		udp	carbon-cache 服务器协议（udp 或 tcp）
port		2003	carbon-cache 服务器端口
frequency		60	多久发送一次值到 Graphite（秒）
intervals		1m	聚合间隔，时间间隔列表，竖线分隔符（`m` - 分钟）
params		*	限制要跟踪的指标列表，竖线分隔符
shared		2m	共享内存大小，若出现 `too small shared memory` 错误请增加
buffer		64k	网络缓冲区大小，若出现 `too small buffer size` 错误请增加
package		1400	最大 UDP 数据包大小
template			图表名称的模板（默认是 $prefix.$host.$split.$param_$interval）
error_log			错误日志图表的路径后缀 (*)

(*): 仅在 nginx_error_log_limiting*.patch 应用于 nginx 源代码时有效

示例（标准）：

http {
    graphite_config prefix=playground server=127.0.0.1;
}

示例（自定义）：

http {
    graphite_config prefix=playground server=127.0.0.1 intervals=1m|5m|15m params=rps|request_time|upstream_time template=$prefix.$host.$split.$param_$interval;
}

示例（error_log）：

http {
    graphite_config prefix=playground server=127.0.0.1 error_log=log;
}

graphite_default_data

语法: graphite_default_data <path prefix> [params=<params>] [if=<condition>]

上下文: http, server

在所有嵌套位置创建测量点。您可以使用 "$location" 或 "$server" 变量，它们表示当前位置的名称和当前服务器的名称，所有非字母数字字符替换为 "_"。前导和尾随的 "_" 被删除。

示例：

   graphite_default_data nginx.$location;

   location /foo/ {
   }

   location /bar/ {
   }

/foo/ 的数据将发送到 nginx.foo，/bar/ 的数据将发送到 nginx.bar。<params> 参数（1.3.0）指定要为所有嵌套位置收集的参数列表。要添加所有默认参数，请使用 *。<if> 参数（1.1.0）启用条件日志记录。如果条件评估为 "0" 或空字符串，则请求将不会被记录。

示例（带 $server）：

    graphite_default_data nginx.$server.$location

    server {
        server_name foo_host;

        location /foo/ {
        }
    }

    server {
        server_name bar_host;

        location /bar/ {
        }
    }

/foo/ 的数据将发送到 nginx.foo_host.foo，/bar/ 的数据将发送到 nginx.bar_host.bar。

graphite_data

语法: graphite_data <path prefix> [params=<params>] [if=<condition>]

上下文: http, server, location, if

在特定位置创建测量点。

示例：

    location /foo/ {
        graphite_data nginx.foo;
    }

<params> 参数（1.3.0）指定要为此位置收集的参数列表。要添加所有默认参数，请使用 *。<if> 参数（1.1.0）启用条件日志记录。如果条件评估为 "0" 或空字符串，则请求将不会被记录。

示例：

    map $scheme $is_http { http 1; }
    map $scheme $is_https { https 1; }

    ...

    location /bar/ {
        graphite_data nginx.all.bar;
        graphite_data nginx.http.bar if=$is_http;
        graphite_data nginx.https.bar if=$is_https;
        graphite_data nginx.arg params=rps|request_time;
        graphite_data nginx.ext params=*|rps|request_time;
    }

graphite_param

语法: graphite_param name=<path> interval=<time value> aggregate=<func>

上下文: location

参数	必需	描述
name	是	所有图表的路径前缀
interval	是*	聚合间隔，时间间隔值格式（`m` - 分钟）
aggregate	是*	对值进行聚合的函数
percentile	是*	百分位数级别

聚合函数

函数	描述
sum	每个间隔的值总和
persec	每秒的值总和（`sum` 除以 `interval` 中的秒数）
avg	间隔内的平均值
gauge	测量值

示例：见下文。

Nginx Lua API

语法: ngx.graphite.param(<name>)

获取图表参数名称的链接，以便在下面的函数中使用该名称。该链接在 nginx 重新加载之前有效。在获取参数的链接后，您仍然可以将参数名称传递给下面的函数。您可以多次获取参数的链接，始终会通过相同的名称（一个 lightuserdata）获取相同的对象。如果指定的名称的参数不存在，则该函数返回 false。如果获取链接时出错，则该函数返回 nil。通过链接访问参数信息的速度比通过名称快。

在应用补丁到 lua-nginx-module 后可用。 此功能在 lua 模块 v0.10.12 的补丁中存在。请参见安装说明。

语法: ngx.graphite(<name_or_link>,<value>[,<config>])

将统计值写入聚合函数。value 中接受浮点数。

在应用补丁到 lua-nginx-module 后可用。 请参见安装说明。

ngx.graphite(name, value, config)

示例：

location /foo/ {
    graphite_param name=lua.foo_sum aggregate=sum interval=1m;
    graphite_param name=lua.foo_rps aggregate=persec interval=1m;
    graphite_param name=lua.foo_avg aggregate=avg interval=1m;
    graphite_param name=lua.foo_gauge aggregate=gauge;

    content_by_lua '
        ngx.graphite("lua.foo_sum", 0.01)
        ngx.graphite("lua.foo_rps", 1)
        ngx.graphite("lua.foo_avg", ngx.var.request_uri:len())
        local foo_gauge_link = ngx.graphite.param("lua.foo_gauge")
        ngx.graphite(foo_gauge_link, 10)
        ngx.graphite(foo_gauge_link, -2)
        ngx.graphite("lua.auto_rps", 1, "aggregate=persec interval=1m percentile=50|90|99")
        ngx.say("hello")
    ';
}

您必须指定 graphite_param 命令或传递 config 参数。如果选择第二个选项，则在第一次调用 ngx.graphite 之前，该图表的数据将不会被发送。

警告： 如果您未使用 graphite_param 命令声明图表，则该图表的内存将在模块的共享内存中动态分配。如果模块的共享内存在 nginx 运行时耗尽，则不会创建新图表，并且会记录错误消息。

语法: ngx.graphite.get(<name_or_link>)

获取具有指定 name_or_link 的测量参数的值。

语法: ngx.graphite.set(<name>,<value>)

将 value 设置为具有指定 name_or_link 的测量参数。

参数

参数	单位	函数	描述
request_time	ms	avg	处理请求所花费的总时间
bytes_sent	bytes	avg	http 响应长度
body_bytes_sent	bytes	avg	http 响应体长度
request_length	bytes	avg	http 请求长度
ssl_handshake_time	ms	avg	ssl 握手所花费的时间
ssl_cache_usage	%	last	SSL 缓存使用情况
content_time	ms	avg	在 nginx 内生成内容所花费的时间
gzip_time	ms	avg	gzipping 内容所花费的时间
upstream_time	ms	avg	与上游交互所花费的时间
upstream_connect_time	ms	avg	上游连接所花费的时间（nginx >= 1.9.1）
upstream_header_time	ms	avg	上游头部所花费的时间（nginx >= 1.9.1）
rps	rps	sum	每秒的总请求数
keepalive_rps	rps	sum	通过先前打开的 keepalive 连接发送的请求数
response_2xx_rps	rps	sum	2xx 代码的总响应数
response_3xx_rps	rps	sum	3xx 代码的总响应数
response_4xx_rps	rps	sum	4xx 代码的总响应数
response_5xx_rps	rps	sum	5xx 代码的总响应数
response_[0-9]{3}_rps	rps	sum	给定代码的总响应数
upstream_cache_(miss\|bypass\|expired\|stale\|updating\|revalidated\|hit)_rps	rps	sum	给定上游缓存状态的总响应数
lua_time	ms	avg	lua 代码所花费的时间

百分位数

要计算任何参数的百分位数值，请通过 / 设置百分位数级别。例如 request_time/50|request_time/90|request_time/99。

添加从 lua 代码发送指标的 API 的补丁（可选）

patch -p1 < /path/to/graphite-nginx-module/lua_module_v0_9_11.patch cd ..

wget 'http://nginx.org/download/nginx-1.9.2.tar.gz' tar -xzf nginx-1.9.2.tar.gz cd nginx-1.9.2/

GitHub

您可以在 nginx-module-graphite 的 GitHub 仓库中找到有关此模块的其他配置提示和文档。