必须用log_by_lua_block实现日志阶段埋点，因其在响应发出后、请求结束前必执行，保障401/500等异常状态下的数据完整性；通过ngx.var.status、request_time等变量提取状态、耗时、路径等字段；支持本地打点、共享字典聚合上报或Kafka异步发送。
在 Nginx（OpenResty）中实现日志阶段的业务埋点，核心是用 log_by_lua_block —— 它在响应已发出、请求生命周期即将结束时执行，既保障数据完整性（哪怕返回 401/500 也必运行），又完全不干扰响应性能。
为什么必须用 log_by_lua 而非其他阶段
access_by_lua 可能在鉴权失败、限流拦截或 rewrite 中断时跳过，导致埋点丢失；而 log_by_lua 是 Nginx 请求处理链的“收尾环节”，只要请求被接入（哪怕只写了 500 错误页），就一定会触发。它不参与响应生成，也不阻塞客户端，适合做最终态指标采集。
提取关键业务字段：状态、耗时、路径与上下文
OpenResty 提供一组稳定可用的内置变量，直接读取即可，无需额外捕获：
- ngx.var.status：最终 HTTP 状态码（如 200、404、500），反映业务结果
-
ngx.var.request_time：总处理耗时（单位：秒，精度毫秒），可转为整数毫秒：
math.floor(tonumber(ngx.var.request_time) * 1000) - ngx.var.uri 和 ngx.var.args：用于识别接口路径和参数（注意敏感参数需脱敏，例如过滤 token、id_card 等）
- ngx.var.http_x_request_id 或 ngx.var.http_trace_id：若前端透传了链路 ID，可用于关联 SkyWalking 或 Jaeger 全链路
- ngx.var.upstream_addr 和 ngx.var.upstream_status：当有反向代理时，可记录上游服务地址与它的返回状态
上报方式：本地打点 vs 内存聚合 + 异步上报
高频请求下，每条都发网络或写磁盘会拖垮性能。推荐两种落地方式：
-
轻量级本地日志：适合调试或低 QPS 场景，直接写入 access_log 或独立文件：
ngx.log(ngx.INFO, string.format("biz: uri=%s status=%d cost_ms=%d", ngx.var.uri, tonumber(ngx.var.status), cost_ms)) -
生产级聚合上报：使用
lua_shared_dict做进程内计数器，配合定时器或采样批量 flush：
– 定义共享字典：lua_shared_dict biz_metrics 10m;
– 在 log_by_lua_block 中累加：local dict = ngx.shared.biz_metrics; dict:incr("api_" .. ngx.var.uri .. "_200", 1)
– 用ngx.timer.at每 5 秒将字典内容推送到 StatsD 或 Prometheus Exporter
对接 Kafka 实现无落盘高吞吐埋点
对实时性与可靠性要求高的场景，可跳过本地日志，直接由 Lua 异步发往 Kafka：
- 引入
lua-resty-kafka库，并在http块配置路径：lua_package_path "/path/to/lua-resty-kafka/lib/?.lua;;"; - 在
log_by_lua_block中构造结构化 JSON（含时间戳、uri、status、cost_ms、client_ip 等），调用 producer 异步发送 - 注意控制重试与失败降级（如 fallback 到本地 error_log 或丢弃），避免阻塞主线程
