mirror of https://github.com/hansjone/oclaw.git synced 2026-10-16 05:30:46 +08:00

oliver 6f754ee5ea ops: use host_name as primary key for alarm NE display

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-20 00:04:33 +08:00

name	description
ops-netx-ume-playbook	面向 ops 专家的 netx UME 运维作业手册。覆盖告警查询/聚合/诊断、网元清单与单网元详情、raw 字段过滤与 UME 只读 SQL。

Ops Netx UME 作业手册

强制使用范围

凡是涉及 netx/UME 告警或 网元信息 的 ops 请求，必须优先加载并遵循本技能。

基础视图（先看整体）：
- netx_query_ume_alarms
- netx_aggregate_ume_alarms
- netx_run_ume_diagnostics
字段感知深查（需要细节）：
- netx_list_ume_alarm_fields
- netx_query_ume_alarms_raw（优先使用 select_fields 控制返回字段）
自定义聚合（非 SQL）：
- netx_aggregate_ume_alarms_raw（group_by，可选 group_by2）
高级分析（SQL）：
- netx_sql_query_ume（仅 SELECT、仅 UME 表；重查询建议设置 statement_timeout_ms）
网元（inventory，与 netx「网元清单」同源）：
- 列表/搜索：netx_query_ume_ne_inventory（keyword + 分页）
- 单条详情（含 raw_json）：netx_get_ume_ne（ne_id = UUID）

只需要整体态势 / Top 风险 / 快速简报：
- 先 netx_aggregate_ume_alarms + netx_run_ume_diagnostics
- 必要时再用 netx_query_ume_alarms 看前 1 页做样本核对
需要“可引用证据”的具体告警明细：
- 先 netx_list_ume_alarm_fields
- 再 netx_query_ume_alarms_raw，并用 select_fields 只取必要字段
需要按任意字段做统计（但不想写 SQL）：
- netx_aggregate_ume_alarms_raw（group_by / group_by2）
需要复杂条件 / 自定义计算 / 多条件关联：
- netx_sql_query_ume（必须过滤 + statement_timeout_ms）
查网元是谁、IP/标签、在线状态、或核对告警里的 ne_id：
- 先 netx_query_ume_ne_inventory（keyword 可填名称、主机名、标签、IP 或 UUID 片段）
- 需要完整字段与 raw_json 时再 netx_get_ume_ne

优先使用非 SQL 工具；仅当工具参数无法表达需求时再用 SQL。
默认过滤优先级（先收敛再扩展）：
- 首选：severity（先把问题缩小到 critical/major 等）
- 其次：keyword（网元名/标签/IP/对象名/告警关键字）
- 再次：time_from/time_to（按 last_seen_at 限定时间窗）
- 最后：event_type 或 ne_id（当你明确知道要锁定事件类型/网元时）
禁止“为了凑全量而无脑翻页”：
- netx_query_ume_alarms 默认只看前 1 页（必要时最多 2 页）
- 如需更多数据，必须先明确过滤条件（severity/ne_id/keyword/time_from/time_to/event_type 等）或改用聚合/SQL
控制响应体积：
- 默认 page_size=50（除非明确需要更多，否则不要上来就拉满 500）
- 动态聚合默认 limit=200
- 合理设置 page_size
- raw 查询尽量传 select_fields；或使用 field_preset=brief/evidence/ne_debug
- 先加过滤条件，再增大分页范围
时间窗过滤默认基于 last_seen_at 语义，除非需求明确要求其它口径。
若数据新鲜度不明确，先查看 runtime 锚点状态，再下结论。
SQL 使用规则（netx_sql_query_ume）：
- 建议总是设置 statement_timeout_ms（例如 3000~10000）
- 推荐默认从 statement_timeout_ms=8000 开始
- 除非只是 count(*)，否则应包含过滤条件（至少时间窗或 ne_id/严重度过滤），避免全表扫描

输出必须包含：
- 简明结论
- 证据依据（工具输出）
- 可执行下一步
没有工具证据时，不得臆测告警事实。
用户用英文提问时（强制）：回复中不得出现任何汉字；工具里的中文告警字段（原因、对象名、描述等）必须先译成英文再写入表格或正文，禁止原样粘贴；网元名用 host_name，协议类维度用英文类别名（Other/Clock/…）。

告警/统计里标识网元时，主键永远是 host_name（主机名），不是 ne_id。表格第一列、Top 网元、分组键、结论里的网元名都用它。
优先数据源（同步时已写入告警表）：
- netx_query_ume_alarms → 字段 host_name
- netx_query_ume_alarms_raw → alarm_host_name（select_fields / brief / evidence 预设已包含）
- 聚合 → group_by=alarm_host_name 或 group_by=ne_host_name
禁止对用户展示裸 ne_id / alarm_ne_id；ne_id 仅作查询参数。
host_name 为空时：用 user_label / ne_name 并注明缺失；仍不得退回 UUID。
仅当列表接口缺 host_name 时再 netx_get_ume_ne / 网元清单 / SQL JOIN 补全。