observe

name	observe
title	系统观测方法论
soul	SOUL.md
persona	observer
version	1.1
triggers	["观测","监控","巡检","健康检查","告警","系统状态","observe","health check","monitoring","变更感知"]
depends_on	["infra/inventory-loader"]
required_vars	[]
description	系统可观测性的方法论：健康三层定义、告警分级、巡检与趋势分析的差异、监控盲点识别。 不包含任何具体监控工具的配置或命令——具体实现由使用者根据自身技术栈在本地 skill 中编写。

系统观测方法论

本 skill 是原则与框架层。具体的监控工具配置（Zabbix UserParameter、Prometheus 指标、 端口扫描脚本等）由使用者在自己的本地 skill 中实现，不在此处定义。

---

健康的三层定义

"系统健康"不是一个单一状态，而是三个层次的组合。缺少任何一层，都是不完整的观测：

第 1 层：进程存活（最基础，必须监控）

• 关键进程是否在运行
• 监听端口是否可访问
• 此层异常 → 服务完全不可用，必须立即告警

第 2 层：服务可用（功能层面）

• 服务是否能正常处理请求（响应时间、成功率）
• 依赖的资源是否可用（连接池、存储空间、下游服务）
• 此层异常 → 服务可能部分可用或性能下降，需要诊断

第 3 层：业务正常（最重要，最容易被忽视）

• 业务数据是否按预期在流动（消息队列无异常积压、数据库写入量正常、接入数据量符合历史基线）
• 此层异常 → 进程可能存活、端口可能监听，但业务实际已中断

关键洞察： 进程活着 ≠ 服务可用 ≠ 业务正常。三层中任何一层出现问题，都需要关注。

---

告警分级

级别	含义	响应要求	典型场景
info	信息性事件，无需处理	仅记录	计划维护开始/结束
warning	资源接近阈值，需关注	工作时间内处理	磁盘使用率 >70%，内存 >80%
critical	服务降级或性能显著下降	30 分钟内响应	进程重启、响应时间 3 倍于基线
disaster	服务完全不可用	立即响应	进程不存在、数据库无法连接

原则：

• 告警必须"可操作"：收到告警的人必须知道下一步该做什么
• 避免告警噪音：频繁触发却不需要人工介入的告警会导致人员免疫，错过真正的问题
• 每条 critical 及以上告警都应有对应的诊断 runbook（指向哪个 diagnose skill）

---

快照巡检 vs 长期趋势

两者解决不同问题，都不可缺少：

快照巡检（高频，感知即时状态）

• 目的：发现"现在有没有问题"
• 频率：分钟级或小时级
• 内容：当前进程状态、告警活跃数量、关键指标当前值
• 输出：状态报告，"绿/黄/红"

长期趋势分析（低频，感知演变方向）

• 目的：发现"问题正在酝酿"（容量耗尽、缓慢内存泄漏、数据积压增长）
• 频率：天级或周级
• 内容：指标的增长率、波动规律、与历史基线的偏差
• 输出：趋势报告，"当前量 / 增长率 / 预计何时触及阈值"

常见错误： 只做快照巡检，忽略趋势，导致磁盘满、连接池耗尽等可预测问题变成紧急事故。

---

监控盲点识别

以下是最容易被遗漏的监控点：

必须监控但经常缺失的

• 备份任务是否按时完成（有无近 N 小时内的备份文件）
• 定时任务（crontab）是否按时执行
• 证书/密钥是否临近过期
• 消费者 lag 是否在持续增长（而不仅是当前绝对值）
• 业务数据量是否符合历史基线（太少和太多都是异常）

观测到但通常无用的

• 进程 PID（每次重启都变，告警意义不大）
• 瞬时尖峰（单次 CPU 100% 通常不代表问题）
• 没有基线的绝对值（1000 个连接，多还是少？）

高价值告警来源

• 与历史同比/环比的偏差（偏差 > N% 即告警）
• 边界条件：连接数 > 连接池最大值的 80%，而不只是 > 某个绝对数值
• 两个指标的组合：CPU 高 + 磁盘 I/O 高，比单独告警更有诊断价值

---

变更感知

观测不仅要发现"现在有没有问题"，还要感知"最近有没有变化"——变更是最常见的故障根因来源。

必须感知的变更类型

变更类型	感知方式	巡检时关注点
应用发布	部署日志、版本标签变更	发布时间与异常开始时间的关联
配置变更	配置文件 hash 变更、环境变量修改	变更项与异常指标的直接关系
基础设施变更	扩容/缩容事件、迁移记录	流量分布变化、新节点健康状态
依赖升级	下游服务版本变更	接口兼容性、性能特征变化
定时任务	任务执行日志	执行时间与异常时间吻合

变更感知在巡检中的应用

• 快照巡检：记录每次巡检时的关键版本号和配置摘要，与上次巡检对比，标记变化项
• 趋势分析：在趋势异常点标注近期是否有变更事件，辅助判断是自然增长还是变更引起

关键原则： 巡检报告应包含"近 N 小时内的变更摘要"，而非仅包含当前状态快照。

---

指标、日志、追踪的角色分工

三者互补，不可互相替代：

信号类型	回答什么问题	适合场景
指标（Metrics）	"是否有问题？严重程度如何？"	触发告警、趋势分析、容量规划
日志（Logs）	"发生了什么事情？在哪里出错？"	故障排查、审计、调试
追踪（Traces）	"请求经过了哪些系统？每段耗时多少？"	微服务延迟分析、依赖链追踪

没有追踪系统时，结构化日志（含 request_id/trace_id）可以部分替代追踪的功能。

---

observer 的只读边界

observer persona 严格只读：

• 只能读取指标、查询日志、检查端口、调用只读 API
• 不得执行任何 SSH 写操作
• 不得修改任何监控配置
• 发现问题时，输出告警/报告，由 diagnoser 或 executor 处理

observer 是"眼睛"，不是"手"。

---

使用者须知

本框架不提供任何具体的监控工具配置或脚本。使用者需要：

1. 根据自身监控工具（Zabbix、Prometheus、Datadog 等），在本地编写具体的观测 skill
2. 本地 skill 中声明 depends_on: [observe]，确保方法论约束生效
3. 本地 skill 的 persona 必须设置为 observer
4. 将需要观测的节点和服务端点写入 inventory/hosts.yaml

参见 skills/infra/inventory-loader 了解如何读取环境变量。