# Ops Netx UME 快速参考

## 1) 当前告警明细（轻量入口）

- 工具：`netx_query_ume_alarms`
- 常用参数：
  - `severity`, `ne_id`, `keyword`, `page`, `page_size`
- 建议：
  - 推荐 `page_size=50`
  - 默认只看前 1 页（必要时最多 2 页），不要无脑翻页拉全量

## 2) 原始明细（字段可控，推荐用于证据输出）

- 工具：`netx_query_ume_alarms_raw`
- 推荐流程：
  - 先调用 `netx_list_ume_alarm_fields` 获取字段清单
  - 再用 `select_fields` 控制返回字段，减少输出体积
- 字段集预设（推荐优先用 preset，避免手写字段列表）：
  - `field_preset=brief`：轻量概览（严重度/事件/最近时间/网元显示）
  - `field_preset=evidence`：证据输出（含 object/cause/时间/网元状态）
  - `field_preset=ne_debug`：定位网元信息缺失或状态异常
- `select_fields` 示例：
  - `alarm_alarm_key`
  - `alarm_perceived_severity`
  - `alarm_last_seen_at`
  - `ne_host_name`（网元名称，对外展示首选）
  - `ne_user_label`
  - `ne_ip_address`
- **禁止**在用户可见输出中只列 `alarm_ne_id`；需要网元身份时必须带 `ne_host_name` 或先联查网元表。

## 3) 动态聚合（非 SQL）

- 工具：`netx_aggregate_ume_alarms_raw`
- 常用分组：
  - `group_by=alarm_perceived_severity`
  - `group_by=ne_host_name`（网元名称；勿用 `alarm_ne_id` / `ne_ne_id` 作对外维度）
  - `group_by=alarm_event_type`
  - `group_by=ne_connection_status`
  - `group_by=alarm_perceived_severity, group_by2=ne_host_name`
- 建议：
  - 推荐 `limit=200`

## 4) 诊断摘要

- 工具：`netx_run_ume_diagnostics`
- 用途：在深挖前先快速形成“概览简报”（严重度、Top 网元、Top 事件类型等）

## 4b) 网元清单与详情

- 工具：`netx_query_ume_ne_inventory` — 对应 netx `GET /v1/ume/inventory/ne`
  - 参数：`keyword`（可选，匹配 ne_id/ne_name/user_label/ip_address/**host_name**）、`page`、`page_size`（最大 500）
- 工具：`netx_get_ume_ne` — `GET /v1/ume/inventory/ne/{ne_id}`
  - 参数：`ne_id`（UUID，与清单字段一致）
- 与告警 raw 中的 `ne_*` 字段互补：需要 UME 原始 JSON 时用 `netx_get_ume_ne` 的 `raw_json`。

## 5) SQL 深度分析（受限）

- 工具：`netx_sql_query_ume`
- 约束：
  - 仅允许 SELECT
  - 仅允许表：`ume_alarms_current` / `ume_inventory_ne`
  - 重查询务必设置 `statement_timeout_ms`
  - 除非只是 `count(*)`，否则建议带时间窗（例如 `last_seen_at >= now() - interval '30 minutes'`）
- 示例（全量聚合，谨慎使用）：
```sql
select
  coalesce(nullif(trim(ne.host_name), ''), ne.user_label, ne.ne_name, '(host_name missing)') as ne_name,
  count(*) as alarm_count
from ume_alarms_current a
left join ume_inventory_ne ne on ne.ne_id = a.ne_id
group by coalesce(nullif(trim(ne.host_name), ''), ne.user_label, ne.ne_name, '(host_name missing)')
order by alarm_count desc
```

- 示例（推荐：带时间窗 + 超时）：
  - `statement_timeout_ms=8000`
```sql
select
  coalesce(nullif(trim(ne.host_name), ''), ne.user_label, ne.ne_name, '(host_name missing)') as ne_name,
  count(*) as alarm_count
from ume_alarms_current a
left join ume_inventory_ne ne on ne.ne_id = a.ne_id
where a.last_seen_at >= now() - interval '30 minutes'
group by coalesce(nullif(trim(ne.host_name), ''), ne.user_label, ne.ne_name, '(host_name missing)')
order by alarm_count desc
```

- 示例（推荐：带时间窗 + 严重度过滤，现场最常用）：
  - `statement_timeout_ms=8000`
```sql
select
  coalesce(nullif(trim(ne.host_name), ''), ne.user_label, ne.ne_name, '(host_name missing)') as ne_name,
  count(*) as alarm_count
from ume_alarms_current a
left join ume_inventory_ne ne on ne.ne_id = a.ne_id
where a.last_seen_at >= now() - interval '30 minutes'
  and lower(coalesce(a.perceived_severity, '')) in ('critical','major')
group by coalesce(nullif(trim(ne.host_name), ''), ne.user_label, ne.ne_name, '(host_name missing)')
order by alarm_count desc
```