日志智能巡检使用指南

功能优势

日志智能巡检通过周期性分析、自动下探和持续跟踪，将海量日志转化为可复核的问题线索，主要优势如下：

1. 主动发现未定义的变化：无需预先配置错误码、关键词和固定阈值，持续识别新增日志模式、分布偏移、指标突变和长尾异常。

2. 面向海量日志分析：在数据侧完成日志聚类、基线比较和维度下探，以整体分布为依据，降低抽样遗漏和局部样本误判的风险。

3. 自动收敛问题范围：Agent 根据分析结果动态选择后续查询，从异常信号逐步定位到服务、版本、Region、用户等具体范围，并保留对照基线和查询证据。

4. 持续跟踪并减少打扰：按周期更新问题状态，区分新增、恶化、复发和恢复；利用已确认的业务语义和已知噪音优化后续巡检，只在出现值得关注的变化时通知。

5. 知识注入与多源分析：通过 Skill 补充业务规则、领域经验和排查方法，通过 UModel 描述实体关系、字段语义，使 Agent 能够关联日志、指标、Trace 等多源数据进行综合分析。对于具有明确业务语义或固定排查经验的日志场景，可通过自定义 Skill 进一步提升巡检质量。

使用前准备

开始前，确认以下条件已满足：

• 已拥有目标 Project 和 Logstore 的查询权限。

• Logstore 已开启索引，能够正常查询日志。

• 日志中存在可用于分析的字段，例如 status、request_time、request_uri、region 或 version。

• 日志时间范围内有可比较的数据；新建或数据量过少的 Logstore 可能无法形成有效基线。

• 如需接收通知，已准备联系人、机器人或 Webhook 通知对象。

• 智能巡检由 STAROps 提供，页面明确提示使用会产生费用，请按实际需要设置执行周期。

本指南以华东 2（上海）地域的 charts-demo/charts-demo Logstore 为例。示例日志为 Nginx 访问日志，包含 status、request_time、request_uri 等字段。

一、进入智能巡检

1. 登录日志服务控制台，进入目标 Project。

2. 在左侧日志库列表中选择目标 LogStore。

3. 在查询分析页面确认当前时间范围内能够正常查询到日志。

4. 在查询结果区域切换到智能巡检页签。

进入后，页面会展示当前 Logstore 下已有的巡检任务。任务卡片中可以看到任务名称、创建人、更新时间以及最近几次执行记录。请不要直接修改他人创建的任务；需要试用时，建议创建带有明确测试标识的独立任务。

二、创建巡检任务

1. 在智能巡检任务列表中单击新建任务。

2. 填写任务名称。建议同时包含业务范围和日志类型，例如“支付网关 Nginx 日志巡检”。

3. 设置计划时间。示例页面支持按小时执行并指定每小时的分钟数。

4. 选择执行任务的数字员工。

5. 填写巡检要求。首次创建可以只写最重要的目标，系统会结合日志特征生成初始计划。

6. 按需选择联系人、机器人或 Webhook。没有通知对象也可以创建，后续再配置。

7. 检查费用提示，确认后单击立即创建。

创建成功后，新任务会显示在列表顶部。刚创建时显示“暂无执行记录”，属于正常状态。

三、首次运行与查看巡检结果

单击任务卡片后，控制台会在新标签页打开 STAROps 长期任务详情。详情页提供三个核心页签：

• 对话：查看任务规划过程、补充业务语义或提出新的下探要求。

• 执行：查看周期执行记录，也可以按需手动触发一次执行。

• 报告：查看巡检完成后生成的报告。

新任务尚未完成第一次执行时，执行和报告的数量为 0。首次执行完成后，再进入相应页签查看分析范围、查询证据、异常维度、Finding 和不确定性说明。

四、修改任务

补充巡检要求：将 /healthz 视为健康检查流量；
同时重点关注 upstream_response_time，
以及异常是否集中在特定来源地址或 User-Agent。

五、阅读巡检报告

报告生成后，建议依次确认以下内容，重点关注巡检窗口、总体结论、异常发现、证据和后续建议：

1. 分析范围：当前窗口、对照窗口和实际查询范围是否符合预期。

2. 巡检计划：本轮实际检查了哪些指标、字段和日志模式。

3. 问题结论：是否发现新增异常、问题恶化、问题复发或影响范围扩大。

4. 数据证据：结论由哪些日志查询、聚类结果或维度下探结果支持。

5. 影响范围：问题集中在哪些 URI、状态码、来源地址、版本或其他维度。

6. 不确定性：数据不足、基线不可比或字段缺失时，报告会说明当前无法确认的部分。

指标变化不一定等于故障。例如慢接口流量占比上升会推高整体 p90，但各接口自身的性能可能没有恶化。应结合维度下探结果判断变化是性能退化，还是流量组成变化。

六、通知配置

巡检周期和通知频率是两件事。任务可以每小时执行，但正常结果不必每小时通知。建议仅在以下情况通知：

• 发现新的高风险问题。

• 已有问题明显恶化。

• 问题恢复后再次复发。

• 影响范围明显扩大。

• 需要人工确认业务语义或处置方式。

如果创建时没有选择通知对象，可以在任务提示或设置页中进入通知管理，后续再添加联系人、机器人或 Webhook。

七、持续优化建议

• 首次运行先确认数据范围、字段识别和基线是否正确。

• 将业务错误码、字段含义和正常行为告诉巡检 Agent。

• 标记健康检查、压测、机器人请求等已知噪音，并说明适用范围。

• 对真实问题补充根因和处置经验，供后续巡检复用。

• 将通知设置为问题触发，避免正常周期重复打扰值班人员。

• 日志结构、版本字段或业务目标变化后，重新检查巡检计划。

自定义 Skill（可选）

对于具有明确业务语义、专用字段或固定排查经验的日志场景，可以创建自定义 Skill，将团队知识补充给执行巡检的数字员工，提升巡检结果的准确性、一致性和可复核性。建议在自定义 Skill 中沉淀以下内容：

1. 字段和状态语义：说明业务错误码、状态字段、版本、Region、租户、用户等字段的含义。

2. 正常行为与已知噪音：定义健康检查、压测流量、机器人请求、定时任务等无需升级的问题，并写清适用范围。

3. 异常判断方法：规定需要重点比较的指标、基线窗口、聚类字段和异常维度。

4. 下钻排查流程：把团队常用的查询语句、诊断顺序、关联条件和根因确认方法固化为标准步骤。

5. 报告与证据要求：约定报告必须保留的时间范围、对照数据、查询证据、不确定性和后续行动。

STAROps 的自定义 Skill 使用 Markdown 编写。技能设计除 SKILL.md 指令外，还可以包含 references/ 目录中的参考资料和 scripts/ 目录中的辅助脚本。创建完成后无需安装，可在使用范围中关联到执行日志巡检的数字员工。

建议先创建草稿，仅为测试数字员工启用使用草稿，通过一次手动巡检验证字段理解、查询范围和报告结果；确认无误后再发布正式版本，供所有已关联的数字员工使用。

操作入口：STAROps 控制台 > 技能中心 > 自定义技能 > 创建自定义 Skill。

常见问题