Nginx Log Analysis 技能创建总结本文档记录 nginx-log-analysis 技能的完整创建过程、架构设计和核心机制不包含具体代码实现。具体SKILL能力代码可查看https://gitee.com/ops-mx/nginx-log-analysis前言本次试验主要是为了测试SKILL生成过程如何编写Prompt如何设计SKILL如何管理SKILL文件。文章分为人工、AI两部分人工部分主要是Prompt内容及编写心得AI部分主要是按照Prompt的自动输出及能力介绍。对于大日志文件文件大小对 token 消耗几乎没有影响实际的 token 消耗取决于分析方式用 nginx-log-analysis 技能分析推荐脚本在本地 Python 进程中运行逐行解析日志文件原始日志不进入上下文窗口。只有最终的 JSON 摘要结果通常 1-3 KB才进入对话。本次试验环境windows11、qoder、python-3.13.14。另外如果Qoder使用私有账号可能需要付费购买credit。详情参考Qoder官网https://qoder.com/pricing人工部分Prompt编写1.首次编写创建一个nginx日志分析的skill具体要求 ①能够统计http各状态码的数量 ②能够统计QPS等关键指标 ③能够统计各代理的访问次数及时间 ④能够统计访问来源包括浏览器命令行等 ⑤能够统计http请求类型及次数 ⑥能够统计各IP地址的访问次数 nginx日志格式已给出请参考D:\Project\SRE Agent SKILL\.qoder\skills\nginx-log-analysis\log_main.conf 日志分析用python语言 你还可以根据已给出的nginx日志格式补充其他的日志分析能力。 skill要有主入口文件其他各统计能力需要单独生成以免上下文太大。最后生成skill放在D:\Project\SRE Agent SKILL\.qoder\skills\nginx-log-analysis目录下通过调用nginx-log-analysis就能实现日志分析 新建一个目录名称为“log-format”主要是存放nginx日志格式配置文件这个目录放在nginx-log-analysis下并将现有的nginx日志配置格式文件全部迁移到这个目录下2.二次优化入口skill文件补充内容如下 ①可根据自然语言要求执行对应的分析指令。 ②nginx日志会有多种格式需要人工维护每个日志格式配置会有自己的名称单独存放在.log-format下。这一点非常重要要提醒客户维护好nginx日志格式配置文件日志格式配置名称由客户自己定义。 ③在执行分析的时候需要列出格式名称供客户选择。 ④在解析过程中如果日志格式跟日志文件不匹配直接终止解析说明终止原因并提醒客户选择正确的日志格式配置文件。 ⑤如果客户使用的日志格式没有对应的解析脚本那根据客户需要生成新的python解析脚本并放在script目录下。 以上补充内容放在入口skill文件的合适位置。 根据nginx-log-analysis的整体能力、使用方法、注意事项生成一个readme文件。为什么要分两次来写Prompt因为第一次考虑不周到这个算是一个入门的过程也说明了SKILL是可以随时调整优化的。Prompt的编写直接会反应出开发者对业务、环境、中间件配置的熟悉程度所以提升技术还是很有必要的。编写心得明确需求大模型喜欢有条理的明确需求所以在编写Prompt的时候可以直接将所有需求按顺序罗列出来且需要言简意赅。过大的context一般会触发agent contextcompress这样会影响大模型的理解。如果有比较重要的信息可以保存在agent的memories里面安全管控安全管控的整体思想严进宽出。初期使用SKILL建议严格把控安全边界以防止大模型出现幻觉、误操作等。具体措施可参考以下内容①所有命令行操作都应需要二次确认②所有写操作都应需要二次确认③生产环境的变更操作应需要二次确认如果有审批流程需要接入对应的审批流目录管理Agent在调用SKILL的时候是全量读为了防止上下文过大应该将文件目录做成总—分的结构一个总入口SKILL文件再路由到对应的脚本或者SKILL文件异常处理碰到异常或者能力不匹配时要明确哪些直接停止工作哪些可以优化。本次试验中在log_format和日志内容不匹配时会进行对应的操作。对应章节AI部分-5. 日志格式配置管理机制可扩展要求SKILL必须有自我迭代或者更新的能力以适应复杂环境和需求以上是自我总结的一点心得体会如有异议可在评论区补充。基本上按照这样的思路编写Prompt总体问题不大AI部分Prompt编写完后Qoder会自动生成SKILL、python脚本等文件。生成的文件可以直接在Qoder-Editor 模式下调用如下图分析QPS测试命令行执行等待确认执行分析结果输出如下生成的SKILL内容下面进行详细介绍1. 核心功能概述nginx-log-analysis 是一个 Qoder Agent 技能用于分析 Nginx 访问日志并提取关键运维指标。核心能力HTTP 状态码分布统计200/404/500 等按 2xx/3xx/4xx/5xx 分类QPS 性能指标计算平均 QPS、峰值 QPS、每分钟 Top10、每小时分布User-Agent 访问排行客户端类型分类浏览器/移动端/命令行/爬虫/移动应用HTTP 请求方法分布GET/POST/PUT/DELETE 等IP 地址访问频率与疑似攻击源识别响应体大小统计带宽、P50/P95/P99 百分位Referer 流量来源分析直接访问/搜索引擎/社交媒体/外部站点全量分析一次遍历输出所有指标设计原则零外部依赖所有脚本仅使用 Python 标准库模块化架构每项分析能力独立为一个脚本按需加载自然语言驱动用户用自然语言描述需求Agent 自动路由到对应脚本多格式支持通过配置文件管理不同业务/环境的日志格式2. 目录结构说明nginx-log-analysis/ ├── SKILL.md # 技能入口文件Agent 加载的主文件 ├── README.md # 面向用户的完整使用文档 ├── log-format/ # 日志格式配置文件目录 │ └── log_main.conf # 示例nginx log_format main └── scripts/ # 分析脚本目录 ├── log_parser.py # 共享解析模块 ├── full_analysis.py # 全量分析入口 ├── status_code_analyzer.py # 状态码统计 ├── qps_calculator.py # QPS 计算 ├── user_agent_analyzer.py # User-Agent 排行 ├── client_type_analyzer.py # 客户端分类 ├── http_method_analyzer.py # 请求方法分布 ├── ip_analyzer.py # IP 分析 ├── response_size_analyzer.py # 响应体大小 └── referer_analyzer.py # Referer 来源各目录职责目录/文件职责维护者SKILL.mdAgent 加载的主入口定义技能描述、工作流程、指令路由表开发者README.md面向用户的完整使用文档开发者log-format/存放 nginx 日志格式配置文件每个文件对应一种日志格式用户scripts/所有 Python 分析脚本每项能力独立一个文件开发者/Agent动态生成scripts/log_parser.py共享解析模块所有分析脚本依赖此模块开发者3. 各脚本文件功能介绍共享模块文件功能log_parser.py核心解析模块。根据日志格式配置中的变量定义构建正则表达式将每行日志解析为结构化字典。提供parse_line()、iter_log()、get_top_n()等公共函数被所有分析脚本导入使用分析脚本文件功能输出格式full_analysis.py全量分析入口。一次遍历日志文件同时计算所有指标避免多次 I/O。适用于首次分析或全面了解日志状况JSON包含 summary/qps/status_codes/http_methods/top_ips/client_types/referer/response_size 等字段status_code_analyzer.py状态码统计。统计各 HTTP 状态码的精确数量按 2xx/3xx/4xx/5xx 分组计算 4xx 和 5xx 错误率JSON包含 status_codes/status_classes/error_rate_4xx/error_rate_5xxqps_calculator.pyQPS 计算。计算平均 QPS总请求/时间跨度、峰值 QPS每秒最大请求数、每分钟 Top10、每小时分布JSON包含 avg_qps/peak_qps/peak_qps_time/per_minute_top10/per_hour_distributionuser_agent_analyzer.pyUA 排行。统计各 User-Agent 字符串的访问次数输出 Top N 排行JSON包含 unique_user_agents/top_user_agentsclient_type_analyzer.py客户端分类。通过正则规则将 User-Agent 分类为 browser/mobile_browser/cli_tool/crawler/mobile_app/unknownJSON包含 client_types 各类别的 count 和 percentagehttp_method_analyzer.py请求方法分布。统计 GET/POST/PUT/DELETE 等 HTTP 方法的数量和占比JSON包含 http_methods 各方法的 count 和 pctip_analyzer.pyIP 分析。统计各 IP 访问次数识别疑似攻击源占比 5% 或请求 1000 次JSON包含 unique_ips/top_ips/suspicious_ipsresponse_size_analyzer.py响应体大小。统计 body_bytes_sent 的总带宽、平均值、最大值、P50/P95/P99 百分位、按大小桶分布JSON包含 total_bandwidth/avg_size/percentiles/size_distributionreferer_analyzer.pyReferer 来源。将流量分类为 direct/search_engine/social_media/external_site统计 Top 来源域名JSON包含 referer_types/top_referer_domains公共参数所有脚本接受以下参数必需日志文件路径第一个参数可选--top N默认 20控制输出条目数所有脚本输出 JSON 格式到 stdout。4. 主要部署步骤总结Step 1: 创建目录结构nginx-log-analysis/ ├── SKILL.md ├── log-format/ └── scripts/Step 2: 编写 SKILL.md 入口文件SKILL.md 是 Agent 加载的主文件包含YAML frontmattername descriptionAgent 通过 description 决定何时激活此技能目录结构说明日志格式配置管理规则自然语言指令路由表标准工作流程6 个 Step动态脚本生成规则分析能力索引表Step 3: 实现共享解析模块 log_parser.pylog_parser.py是整个系统的核心根据 nginxlog_format指令中的变量顺序构建正则表达式提供parse_line(line)函数将单行日志解析为结构化字典提供iter_log(filepath)函数逐行迭代解析日志文件内存友好提供get_top_n(counter, n)工具函数Step 4: 逐个实现分析脚本每个分析脚本遵循统一模式导入log_parser模块定义analyze(filepath, top_n)函数遍历日志条目使用Counter统计目标指标组装结果字典if __name__ __main__中处理命令行参数并输出 JSONStep 5: 实现全量分析脚本 full_analysis.pyfull_analysis.py将所有分析逻辑合并到一次遍历中在同一个for entry in iter_log()循环内同时更新所有 Counter避免多次 I/O 读取大幅提升大文件分析效率输出包含所有指标字段的完整 JSONStep 6: 配置日志格式管理创建log-format/目录放入示例配置文件log_main.conf在 SKILL.md 中定义命名规范和管理规则Step 7: 编写 README.md生成面向用户的完整使用文档覆盖功能说明、使用方法、常见问题、最佳实践。5. 日志格式配置管理机制设计背景Nginx 日志格式因业务和环境不同会有多种变体。硬编码单一格式会导致兼容性问题。因此引入配置文件机制将格式定义与解析逻辑解耦。管理机制要素说明存储位置log-format/目录所有.conf文件集中存放命名规范{业务线}_{环境}_{格式名}.conf如mse_production_log_main.conf文件内容包含完整的 nginxlog_format指令维护责任由用户负责维护需与实际 nginx 配置保持一致运行时流程Agent 读取log-format/目录列出所有.conf文件用户选择本次使用的格式配置Agent 读取配置文件提取log_format中的变量定义与log_parser.py的正则进行匹配校验用日志文件前 5 行做预检匹配则继续不匹配则终止并提示格式不匹配处理如果预检失败Agent 立即终止解析输出所选格式名称实际日志样本前几行终止原因建议用户重新选择或新增格式配置动态脚本生成如果用户的格式配置在log-format/中存在但scripts/下没有适配的解析脚本Agent 读取格式配置提取变量列表根据变量顺序构建对应的正则表达式基于log_parser.py的模式生成新的解析脚本自动保存到scripts/目录6. 自然语言指令路由机制设计目标用户无需记忆脚本名称和参数只需用自然语言描述需求Agent 自动路由到对应分析脚本。路由表用户自然语言自动匹配脚本“分析访问量最高的 IP”ip_analyzer.py“统计 404 错误页面”status_code_analyzer.py“查看 QPS 趋势”qps_calculator.py“看看都是什么浏览器在访问”client_type_analyzer.py“统计 GET 和 POST 请求占比”http_method_analyzer.py“分析流量来源”referer_analyzer.py“看看响应体大小分布”response_size_analyzer.py“哪些 User-Agent 访问最多”user_agent_analyzer.py“全面分析这个日志” / “看看整体情况”full_analysis.py路由流程用户输入自然语言 │ ▼ Agent 识别关键词IP/状态码/QPS/浏览器/方法/来源/响应体/UA/全部 │ ▼ 匹配路由表确定目标脚本 │ ▼ 执行标准工作流程确认路径 → 选择格式 → 预检验证 → 执行脚本 → 展示结果扩展机制路由表定义在 SKILL.md 中新增分析能力时只需在scripts/下添加新脚本在 SKILL.md 的路由表和分析能力表中补充对应条目Agent 即可自动识别并路由附录标准工作流程Step 1: 收集日志文件路径 → 确认文件存在 Step 2: 列出 log-format/ 下可用格式 → 用户选择 Step 3: 读取格式配置 → 构建解析器 Step 4: 格式匹配验证 → 前 5 行预检不匹配则终止 Step 5: 识别用户意图 → 路由到对应脚本执行 Step 6: 结果展示 → JSON 解析后以表格/列表呈现