log_format必须定义在http块内，location中通过access_log指令调用已定义格式实现业务日志隔离；需配合^~精准匹配、真实ip获取、请求id透传等机制完成高精度指标采集。
不能在 location 块里直接定义 log_format，它必须放在 http 块内。但你可以为特定 location 路由块“绑定专属日志格式”，实现高精度指标度量——关键在于提前在 http 层定义好带业务字段的格式，再在对应 location 中显式调用。
在 http 块中预定义面向业务的 log_format
所有自定义日志格式都得写在 http { ... } 作用域里，且名称唯一。针对特殊路径（比如 /api/v3/finance 或 /admin/report），建议按业务语义命名，并嵌入能支撑深度分析的变量：
- 必含基础字段：$remote_addr、$time_iso8601、$request、$status、$body_bytes_sent
- 强化链路追踪：$http_x_request_id、$upstream_response_time、$request_time
- 适配业务逻辑：若后端返回 JSON 并含 error_code 字段，可通过 proxy_pass + $upstream_http_x_error_code（需后端透传）捕获；也可用 Lua 提取响应体字段（见进阶方案）
-
示例（金融类接口）：
log_format finance_api '
{"ts":"$time_iso8601","ip":"$remote_addr","uri":"$uri","method":"$request_method",
"status":$status,"bytes":$body_bytes_sent,"req_id":"$http_x_request_id",
"rt":$request_time,"up_rt":$upstream_response_time,"ua":"$http_user_agent"}
';
在目标 location 中启用该格式并隔离日志文件
location 匹配要精准，避免继承 server 级日志。使用 ^~ 前缀匹配最稳妥，且必须显式写 access_log 指令：
Skill Weave Chains — 技能链路由引擎
下载
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 匹配路径如 /api/v3/finance/，用
location ^~ /api/v3/finance/ { ... } - 内部写
access_log /var/log/nginx/finance_api.log finance_api;（注意末尾格式名无引号） - 如果该 location 含 proxy_pass，确保 access_log 在 proxy_pass 之前或之后均可生效（Nginx 日志记录发生在响应头发出时，非 body 返回后）
- 不要在父级 location（如 /api/）和子级（如 /api/v3/finance/）同时开 access_log，除非你明确需要双写
补充高精度字段的获取方式
标准变量不够用？以下常见增强手段可直接集成进 log_format 使用：
-
真实客户端 IP：若 Nginx 前有 LB，启用
set_real_ip_from+real_ip_header X-Forwarded-For;，再用$real_remote_addr替代$remote_addr -
请求 ID 生成与透传：用
map或set_by_lua_block生成$request_id，并通过proxy_set_header X-Request-ID $request_id;透传给后端 -
上游服务标识：配合
upstream块 name，用$upstream_addr记录实际转发到的后端地址（含端口），便于故障定位 -
自定义 header 提取：如需记录
X-Correlation-ID，先加underscores_in_headers on;（若 header 含下划线），再用$http_x_correlation_id
验证与调试要点
配置完别急着 reload，先检查是否真正生效：
- 执行
nginx -t确认语法无误 - 用
curl -H "X-Request-ID: abc123" http://your.site/api/v3/finance/list发起测试请求 - 实时观察日志：
tail -f /var/log/nginx/finance_api.log，确认 JSON 字段完整、时间戳准确、IP 正确 - 注意权限：确保 nginx worker 进程对日志目录有写权限（如
chown -R www-data:www-data /var/log/nginx/）
