Topologie

Topologie ist der Graph, der „ein Incident auf Host edge-prod-04" in „ein Incident, der payments und search und email lahmlegt" verwandelt. Ohne ihn kann das LLM nur über die einzelne feuernde Serie argumentieren.

ADR-025

Die aktuellen Topologie-BaseTools (expand_topology, find_topology_node) landeten 2026-05-18. Davor hatte das LLM eine flache Device-Liste und keinen Weg, Beziehungen zu durchlaufen; „was hängt von X ab" erforderte, dass der Operator die Antwort bereits kannte.

Das Datenmodell

Vier Tabellen, alle in MySQL:

Tabelle	Hält
topology_nodes	Eine Zeile pro Knoten. Hat einen type (device / service / cluster / ...), einen name und ein frei formatiertes props_json.
topology_node_types	Die geschlossene Menge erlaubter node.type-Werte.
topology_relations	Gerichtete Kante src_node_id -> dst_node_id mit einem type.
topology_relation_types	Geschlossene Menge von Kantentypen, jeder mit einem semantics-Feld (hard_dep / runtime_dep / traffic / annotation / observation) getaggt.

Der semantics-Tag ist die Schlüsselidee. Eine als hard_dep getaggte Kante propagiert Ausfall (wenn src stirbt, ist dst betroffen); eine als annotation getaggte Kante nicht. Der Wirkungsradius-Walk verwendet das zum Filtern.

Siehe internal/manager/biz/topology/.

Wo die Daten herkommen

Drei Quellen, geschichtet:

1. Auto aus Spans — Tempos service_graph-Prozessor emittiert service_a -> service_b-Kanten mit einem routes_to-Semantics-Tag. Der Manager spiegelt diese auf einem Sync-Tick in topology_relations.
2. Auto aus Edges — jede registrierte Edge wird ein type=device-Knoten; die Knoten-ID wird über die host_devices.node_id-Spalte rückverlinkt, sodass expand_topology(device_id=X) durchläuft.
3. Manuell — Operatoren fügen type=service- / type=cluster-Knoten und -Kanten über die /topology-Seite der SPA hinzu. Verwendet für Knoten, die Sie adressieren möchten, die aber nicht direkt beobachtet werden (eine Managed-Datenbank, eine Drittanbieter-API).

Tools

expand_topology

Von einem Knoten nach außen gehen, jeden erreichbaren Knoten plus wie er erreicht wurde zurückgeben. Default-BFS-Tiefe 2, Cap 5. Default-Richtung both (Wirkungsradius ist symmetrisch — was könnte dies brechen, UND was bricht dies).

{
  "node_id": 142,
  "depth": 2,
  "only_propagating": true,
  "direction": "downstream"
}

Oder, wenn Sie von einer Device-ID starten:

{ "device_id": 17, "depth": 3 }

Das Tool löst device_id → device.node_id automatisch auf. only_propagating=true (Default) durchläuft nur hard_dep / runtime_dep / traffic-Kanten; auf false umschalten, um Observation- / Annotation-Kanten einzuschließen (nützlich für die „zeige mir alles, was mit X verwandt ist"-Fälle).

Zurückgegebene Treffer tragen die Pfad-Metadaten, die das LLM braucht, um über Auswirkungen zu argumentieren:

{
  "center":  { "node_id": 142, "node_name": "payments-api", "node_type": "service", "hops": 0, "propagates_failure": false },
  "max_hops": 2,
  "reachable_count": 7,
  "reachable": [
    { "node_id": 71, "node_name": "edge-prod-04", "node_type": "device", "hops": 1,
      "relation_type": "deployed_on", "semantics_tag": "runtime_dep", "reached_via": "downstream",
      "propagates_failure": true,
      "via_node_id": 142, "via_node_name": "payments-api" }
  ]
}

Die flache Liste (keine verschachtelte Per-Neighbor-Struktur) ist beabsichtigt — hält das JSON billig für die Prompt-Einbettung. Siehe expand_topology_basetool.go.

find_topology_node

Der „Ich habe einen vom Menschen gegebenen Namen, gib mir eine node_id"-Vorab-Schritt. Die Persona führt diesen vor expand_topology aus, wenn der Prompt einen Dienst / Host per Namen erwähnt:

User: "what does loki-write depend on?"
Agent:
  → find_topology_node{ name: "loki-write" }
    ← { node_id: 219, node_type: "service", name: "loki-write" }
  → expand_topology{ node_id: 219, direction: "upstream" }
    ← { reachable_count: 4, ... }

Beide sind als ScopeManager-BaseTools registriert (kein edge_id-Argument) — die Topologie-DB lebt manager-seitig.

Wirkungsradius-Walk in der Praxis

Das Prompt der Investigator-Persona enthält ein explizites „nachdem Sie den feuernden Dienst identifiziert haben, rufen Sie expand_topology auf, um zu sehen, was sonst betroffen ist". So werden die related_alerts und die „业务影响 / Business impact"-Sektion des Berichts gefüllt — der Agent durchläuft den Graphen vom feuernden Device aufwärts / abwärts und gleicht ab, welche anderen Incidents im selben Fenster auf diesen Knoten gefeuert haben.

Der relevante Code-Pfad:

1. correlate_incident gibt Metrik- + Log- + Trace-Zusammenfassungen plus die device_id des Incidents zurück.
2. expand_topology { device_id, direction: both, depth: 2 } gibt das erreichbare Set zurück.
3. Pass-2-Extraktion liest die Erzählung des Workers und zieht pinpointed_target (den Patient Zero) + related_alerts (die Kaskade).

Siehe auch

• RCA — die Investigator-Persona, die diese Tools verwendet.
• Skills — wie expand_topology sowohl in der BaseTool-Tasche als auch in der Skill-Registry registriert ist (inventory_bridge).
• Konzepte — das Edge / Device / Node Vokabular.