hansjone/netx
1
0
Fork 0
mirror of https://github.com/hansjone/netx.git synced 2026-10-16 18:20:45 +08:00
Code Issues Projects Releases 1 Packages Wiki Activity Actions

Improve UME ops triage APIs and slim fabric path payloads.

Browse source 
Add severity/time filters, exclude missing hosts from aggregates, and default topology paths to compact summary fields for MCP-friendly alarm triage.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
oliver 2026-08-10 22:17:45 +08:00
parent 753740d64e
commit 78d174232d
6 changed files with 505 additions and 50 deletions
Download patch file Download diff file Expand all files Collapse all files

342
netx_api/ume_alarms_router.py
View file

@ -6,7 +6,7 @@ from datetime import datetime, timezone
from typing import Any
from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import or_
from sqlalchemy import func, or_
from sqlalchemy.orm import Session
from .config import settings
@ -78,6 +78,8 @@ def ume_list_alarms(
ne_id: str | None = Query(default=None),
host_name: str | None = Query(default=None),
keyword: str | None = Query(default=None),
time_from: str | None = Query(default=None, description="Filter by last_seen_at >="),
time_to: str | None = Query(default=None, description="Filter by last_seen_at <="),
page: int = Query(default=1, ge=1),
page_size: int = Query(default=50, ge=1, le=500),
db: Session = Depends(get_db),
@ -109,6 +111,12 @@ def ume_list_alarms(
| UmeInventoryNE.ip_address.contains(kw)
| UmeInventoryNE.host_name.contains(kw)
)
dt_from = _parse_time(time_from)
dt_to = _parse_time(time_to)
if dt_from:
stmt = stmt.filter(UmeAlarmCurrent.last_seen_at >= dt_from.replace(tzinfo=None))
if dt_to:
stmt = stmt.filter(UmeAlarmCurrent.last_seen_at <= dt_to.replace(tzinfo=None))
total = int(stmt.count())
rows = (
stmt.order_by(
@ -139,7 +147,13 @@ def ume_list_alarms(
}
for alarm, ne in rows
]
return {"total": total, "page": page, "page_size": page_size, "items": items}
return {
"total": total,
"page": page,
"page_size": page_size,
"meta": {"time_filter_field": "last_seen_at"},
"items": items,
}
@router.get("/v1/ume/alarms/fields")
@ -309,6 +323,29 @@ def ume_alarms_raw(
}
_HOST_MISSING_LABEL = "(host_name missing)"
_HOST_GROUP_FIELDS = frozenset({"alarm_host_name", "ne_host_name", "ne_user_label"})
def _normalize_ne_bucket_key(raw: Any) -> str:
s = str(raw or "").strip()
if not s or s.lower() in {"unknown", "none", "null"}:
return _HOST_MISSING_LABEL
# Bare UUID or ME{uuid}
if len(s) >= 32 and s.count("-") >= 4 and " " not in s:
return _HOST_MISSING_LABEL
if s.startswith("ME{") and s.endswith("}"):
return _HOST_MISSING_LABEL
return s
def _raw_group_bucket_key(field: str, value: str) -> str:
if field in _HOST_GROUP_FIELDS:
return _normalize_ne_bucket_key(value)
s = str(value or "").strip()
return s if s else "(empty)"
@router.get("/v1/ume/alarms/aggregate/raw")
def ume_alarms_aggregate_raw(
group_by: str = Query(default="alarm_perceived_severity"),
@ -320,6 +357,10 @@ def ume_alarms_aggregate_raw(
keyword: str | None = Query(default=None),
time_from: str | None = Query(default=None),
time_to: str | None = Query(default=None),
exclude_missing_host: bool = Query(
default=True,
description="When grouping by host/user_label fields, omit (host_name missing) from buckets.",
),
limit: int = Query(default=200, ge=1, le=2000),
db: Session = Depends(get_db),
) -> dict[str, Any]:
@ -362,17 +403,30 @@ def ume_alarms_aggregate_raw(
stmt = stmt.filter(UmeAlarmCurrent.last_seen_at <= dt_to.replace(tzinfo=None))
rows = stmt.order_by(UmeAlarmCurrent.last_seen_at.desc()).all()
counts: dict[tuple[str, str], int] = {}
merged: dict[tuple[str, str], int] = {}
by_ne_missing = 0
for alarm, ne in rows:
k1 = _extract_ume_raw_group_field(alarm, ne, g1)
k2 = _extract_ume_raw_group_field(alarm, ne, g2) if g2 else ""
kk = (k1, k2)
counts[kk] = int(counts.get(kk, 0)) + 1
buckets = sorted(counts.items(), key=lambda x: x[1], reverse=True)[: int(limit)]
nk1 = _raw_group_bucket_key(g1, _extract_ume_raw_group_field(alarm, ne, g1))
nk2 = _raw_group_bucket_key(g2, _extract_ume_raw_group_field(alarm, ne, g2)) if g2 else ""
missing_hit = False
if g1 in _HOST_GROUP_FIELDS and nk1 == _HOST_MISSING_LABEL:
missing_hit = True
if g2 and g2 in _HOST_GROUP_FIELDS and nk2 == _HOST_MISSING_LABEL:
missing_hit = True
if missing_hit:
by_ne_missing += 1
if exclude_missing_host:
continue
kk = (nk1, nk2)
merged[kk] = int(merged.get(kk, 0)) + 1
buckets = sorted(merged.items(), key=lambda x: x[1], reverse=True)[: int(limit)]
return {
"total": len(rows),
"group_by": g1,
"group_by2": g2 or None,
"by_ne_missing": by_ne_missing,
"exclude_missing_host": bool(exclude_missing_host),
"meta": {
"available_fields": sorted(selectable_fields),
"group_by_allowed": sorted(selectable_fields),
@ -387,60 +441,274 @@ def ume_alarms_aggregate_raw(
},
"time_filter_field": "last_seen_at",
"limit": int(limit),
"host_missing_label": _HOST_MISSING_LABEL,
},
"buckets": [
{"key": k1, "key2": (k2 if g2 else None), "count": int(v)}
{
"key": k1,
"key2": (k2 if g2 else None),
"count": int(v),
}
for (k1, k2), v in buckets
],
}
@router.get("/v1/ume/alarms/aggregate")
def ume_alarms_aggregate(db: Session = Depends(get_db)) -> dict[str, Any]:
rows = db.query(UmeAlarmCurrent, UmeInventoryNE).outerjoin(
UmeInventoryNE, UmeAlarmCurrent.ne_id == UmeInventoryNE.ne_id
).all()
by_severity = _aggregate_rows(rows, lambda x: x[0].perceived_severity)
by_ne = _aggregate_rows(rows, lambda x: _ume_alarm_ne_group_key(x[0], x[1]))
return {"total": len(rows), "by_severity": by_severity, "by_ne": by_ne}
def ume_alarms_aggregate(
top_ne: int = Query(
default=50,
ge=0,
le=5000,
description="Max NE buckets to return (0 = all). Severity buckets are always complete.",
),
exclude_missing_host: bool = Query(
default=True,
description="When true, omit (host_name missing) from by_ne ranking (count still in by_ne_missing).",
),
severity: str | None = Query(
default=None,
description="Optional perceived_severity filter (e.g. critical) for top-NE ranking.",
),
time_from: str | None = Query(default=None, description="Filter by last_seen_at >="),
time_to: str | None = Query(default=None, description="Filter by last_seen_at <="),
db: Session = Depends(get_db),
) -> dict[str, Any]:
"""Aggregate current alarms by severity and NE (SQL group-by; top_ne capped)."""
dt_from = _parse_time(time_from)
dt_to = _parse_time(time_to)
sev = str(severity or "").strip() or None
base = db.query(UmeAlarmCurrent)
if sev:
base = base.filter(UmeAlarmCurrent.perceived_severity == sev)
if dt_from:
base = base.filter(UmeAlarmCurrent.last_seen_at >= dt_from.replace(tzinfo=None))
if dt_to:
base = base.filter(UmeAlarmCurrent.last_seen_at <= dt_to.replace(tzinfo=None))
# Prefer .count() — with_entities(func.count()) without select_from can return 1.
total = int(base.count())
sev_q = db.query(UmeAlarmCurrent.perceived_severity, func.count())
if sev:
sev_q = sev_q.filter(UmeAlarmCurrent.perceived_severity == sev)
if dt_from:
sev_q = sev_q.filter(UmeAlarmCurrent.last_seen_at >= dt_from.replace(tzinfo=None))
if dt_to:
sev_q = sev_q.filter(UmeAlarmCurrent.last_seen_at <= dt_to.replace(tzinfo=None))
sev_rows = (
sev_q.group_by(UmeAlarmCurrent.perceived_severity).order_by(func.count().desc()).all()
)
by_severity = [
{"key": (str(k).strip() if k is not None and str(k).strip() else "unknown"), "count": int(v)}
for k, v in sev_rows
]
# Display key: host_name / inventory host / user_label only (never bare UUID).
ne_key = func.coalesce(
func.nullif(func.trim(UmeAlarmCurrent.host_name), ""),
func.nullif(func.trim(UmeInventoryNE.host_name), ""),
func.nullif(func.trim(UmeInventoryNE.user_label), ""),
_HOST_MISSING_LABEL,
)
ne_q = (
db.query(ne_key.label("ne_key"), func.count().label("cnt"))
.select_from(UmeAlarmCurrent)
.outerjoin(UmeInventoryNE, UmeAlarmCurrent.ne_id == UmeInventoryNE.ne_id)
)
if sev:
ne_q = ne_q.filter(UmeAlarmCurrent.perceived_severity == sev)
if dt_from:
ne_q = ne_q.filter(UmeAlarmCurrent.last_seen_at >= dt_from.replace(tzinfo=None))
if dt_to:
ne_q = ne_q.filter(UmeAlarmCurrent.last_seen_at <= dt_to.replace(tzinfo=None))
ne_q = ne_q.group_by(ne_key).order_by(func.count().desc())
all_ne_rows = ne_q.all()
by_ne_missing = 0
named_counts: dict[str, int] = {}
for k, v in all_ne_rows:
label = _normalize_ne_bucket_key(k)
cnt = int(v)
if label == _HOST_MISSING_LABEL:
by_ne_missing += cnt
else:
named_counts[label] = int(named_counts.get(label, 0)) + cnt
named_rows = sorted(named_counts.items(), key=lambda kv: kv[1], reverse=True)
by_ne_total = len(named_rows) + (1 if by_ne_missing else 0)
ranked = list(named_rows)
if not exclude_missing_host and by_ne_missing:
ranked.append((_HOST_MISSING_LABEL, by_ne_missing))
ranked.sort(key=lambda kv: int(kv[1]), reverse=True)
if top_ne > 0:
ranked = ranked[: int(top_ne)]
by_ne = [{"key": str(k), "count": int(v)} for k, v in ranked]
seen_bounds = db.query(
func.min(UmeAlarmCurrent.last_seen_at),
func.max(UmeAlarmCurrent.last_seen_at),
)
if sev:
seen_bounds = seen_bounds.filter(UmeAlarmCurrent.perceived_severity == sev)
if dt_from:
seen_bounds = seen_bounds.filter(
UmeAlarmCurrent.last_seen_at >= dt_from.replace(tzinfo=None)
)
if dt_to:
seen_bounds = seen_bounds.filter(
UmeAlarmCurrent.last_seen_at <= dt_to.replace(tzinfo=None)
)
min_seen, max_seen = seen_bounds.one()
return {
"total": total,
"by_severity": by_severity,
"by_ne": by_ne,
"by_ne_total": by_ne_total,
"by_ne_missing": by_ne_missing,
"top_ne": int(top_ne),
"exclude_missing_host": bool(exclude_missing_host),
"severity": sev,
"meta": {
"time_filter_field": "last_seen_at",
"last_seen_min": (_ensure_utc(min_seen).isoformat() if min_seen else None),
"last_seen_max": (_ensure_utc(max_seen).isoformat() if max_seen else None),
},
}
@router.get("/v1/ume/diagnostics")
def ume_diagnostics(
lang: str | None = Query(default=None),
top_n: int = Query(default=10, ge=1, le=50),
db: Session = Depends(get_db),
) -> dict[str, Any]:
rows = db.query(UmeAlarmCurrent, UmeInventoryNE).outerjoin(
UmeInventoryNE, UmeAlarmCurrent.ne_id == UmeInventoryNE.ne_id
).all()
by_severity = _aggregate_rows(rows, lambda x: x[0].perceived_severity)
by_alarm_code = _aggregate_rows(rows, lambda x: x[0].event_type)[:10]
by_ne = _aggregate_rows(rows, lambda x: _ume_alarm_ne_group_key(x[0], x[1]))[:10]
"""Fast SQL diagnostics; top_ne excludes missing host_name; includes data freshness."""
total = int(db.query(func.count()).select_from(UmeAlarmCurrent).scalar() or 0)
min_seen, max_seen = db.query(
func.min(UmeAlarmCurrent.last_seen_at),
func.max(UmeAlarmCurrent.last_seen_at),
).one()
sev_rows = (
db.query(UmeAlarmCurrent.perceived_severity, func.count())
.group_by(UmeAlarmCurrent.perceived_severity)
.order_by(func.count().desc())
.all()
)
by_severity = [
{"key": (str(k).strip() if k is not None and str(k).strip() else "unknown"), "count": int(v)}
for k, v in sev_rows
]
event_rows = (
db.query(UmeAlarmCurrent.event_type, func.count())
.group_by(UmeAlarmCurrent.event_type)
.order_by(func.count().desc())
.limit(top_n)
.all()
)
top_event_types = [
{"key": (str(k).strip() if k is not None and str(k).strip() else "unknown"), "count": int(v)}
for k, v in event_rows
]
# Prefer real UME alarmCode from raw_json when present (Postgres JSON text).
top_alarm_codes: list[dict[str, Any]] = []
try:
from sqlalchemy import cast
from sqlalchemy.dialects.postgresql import JSON
code_expr = func.coalesce(
func.nullif(
func.json_extract_path_text(cast(UmeAlarmCurrent.raw_json, JSON), "alarmCode"),
"",
),
"(none)",
)
code_rows = (
db.query(code_expr.label("code"), func.count())
.group_by(code_expr)
.order_by(func.count().desc())
.limit(top_n)
.all()
)
top_alarm_codes = [{"key": str(k), "count": int(v)} for k, v in code_rows]
except Exception:
# SQLite / non-JSON: fall back to native_probable_cause tops.
cause_rows = (
db.query(UmeAlarmCurrent.native_probable_cause, func.count())
.group_by(UmeAlarmCurrent.native_probable_cause)
.order_by(func.count().desc())
.limit(top_n)
.all()
)
top_alarm_codes = [
{
"key": (str(k).strip() if k is not None and str(k).strip() else "unknown"),
"count": int(v),
}
for k, v in cause_rows
]
ne_key = func.coalesce(
func.nullif(func.trim(UmeAlarmCurrent.host_name), ""),
func.nullif(func.trim(UmeInventoryNE.host_name), ""),
func.nullif(func.trim(UmeInventoryNE.user_label), ""),
_HOST_MISSING_LABEL,
)
ne_rows = (
db.query(ne_key.label("ne_key"), func.count().label("cnt"))
.select_from(UmeAlarmCurrent)
.outerjoin(UmeInventoryNE, UmeAlarmCurrent.ne_id == UmeInventoryNE.ne_id)
.group_by(ne_key)
.order_by(func.count().desc())
.all()
)
by_ne_missing = 0
named_counts: dict[str, int] = {}
for k, v in ne_rows:
label = _normalize_ne_bucket_key(k)
cnt = int(v)
if label == _HOST_MISSING_LABEL:
by_ne_missing += cnt
continue
named_counts[label] = int(named_counts.get(label, 0)) + cnt
top_ne = [
{"key": label, "count": cnt}
for label, cnt in sorted(named_counts.items(), key=lambda kv: kv[1], reverse=True)[:top_n]
]
# Protocol buckets still need text classify; stream rows lightly (cause+event only).
lang_norm = _normalize_netx_lang(lang)
proto_counts: dict[str, int] = {}
for alarm, ne in rows:
blob = " | ".join(
[
str(alarm.event_type or ""),
str(alarm.native_probable_cause or ""),
str(alarm.object_name or ""),
str(ne.ne_name if ne else ""),
str(ne.user_label if ne else ""),
str(ne.ip_address if ne else ""),
]
)
light = db.query(
UmeAlarmCurrent.event_type,
UmeAlarmCurrent.native_probable_cause,
UmeAlarmCurrent.object_name,
).yield_per(2000)
for event_type, cause, obj in light:
blob = " | ".join([str(event_type or ""), str(cause or ""), str(obj or "")])
bucket = _protocol_bucket_label(blob, lang=lang_norm)
proto_counts[bucket] = int(proto_counts.get(bucket, 0)) + 1
protocol_summary = sorted(proto_counts.items(), key=lambda x: x[1], reverse=True)[:10]
protocol_summary = sorted(proto_counts.items(), key=lambda x: x[1], reverse=True)[:top_n]
return {
"source": "ume_alarms_current",
"total_alarms": len(rows),
"total_alarms": total,
"severity_summary": by_severity,
"top_alarm_codes": by_alarm_code,
"top_ne": by_ne,
"top_event_types": top_event_types,
# Backward-compatible alias — historically event_type, now real alarmCode when possible.
"top_alarm_codes": top_alarm_codes,
"top_ne": top_ne,
"by_ne_missing": by_ne_missing,
"protocol_summary": [{"key": k, "count": v} for k, v in protocol_summary],
"meta": {
"last_seen_min": (_ensure_utc(min_seen).isoformat() if min_seen else None),
"last_seen_max": (_ensure_utc(max_seen).isoformat() if max_seen else None),
"time_filter_field": "last_seen_at",
"host_missing_label": _HOST_MISSING_LABEL,
},
}