Lineage Explorer | Developer Docs

Der Lineage Explorer (/trace-explorer) ist der Ort, an dem Sie genau rekonstruieren, was ein KI-Agent getan hat, in welcher Reihenfolge und mit welchen Daten. Er verwandelt die OpenTelemetry-Spans, die Ihre instrumentierten Agenten aussenden, in eine lesbare Ausführungs-Timeline und ermöglicht es Ihnen anschließend, diese Timeline gegen ein kryptografisches Ledger zu verifizieren, sodass ihre Integrität gegenüber einem Prüfer nachgewiesen werden kann. Ein Lineage Record ist KLAs Bezeichnung für einen einzelnen Trace: der vollständige, geordnete Baum der Schritte eines Agentenlaufs, vom auslösenden Prompt über jeden Tool-Aufruf bis zur finalen Ausgabe.

Der Explorer bedient zwei Lesergruppen gleichzeitig. Eine Entwicklerin nutzt ihn, um einen fehlerhaften Lauf zu debuggen. Ein Compliance-, Risiko- oder Audit-Verantwortlicher nutzt ihn, um im Nachhinein präzise zu rekonstruieren, was geschehen ist, und nachzuweisen, dass nichts verändert wurde. Beide arbeiten mit demselben Datensatz.

Ausführungs-Timelines

Jeder gesteuerte Lauf erzeugt einen Baum von Spans. Der Explorer stellt diesen Baum als Timeline dar, sodass Sie Form und Dauer des Laufs auf einen Blick erkennen und anschließend in jeden Schritt hineinzoomen können.

Verschachtelte Schritte: Prompt-Konstruktion, Modell-Completions, Retrieval-Lesevorgänge, Datenbankabfragen und ausgehende HTTP-Aufrufe, jeweils mit Startzeit, Dauer und Eltern-Kind-Beziehungen.
Semantische GenAI-Attribute: Jeder Schritt trägt standardisierte OpenTelemetry-GenAI-Felder, darunter genai.agent.name, genai.system.instructions, genai.tool.name, genai.tool.parameters, genai.token.usage und genai.cost.usd.
Inline-Policy-Ergebnisse: An Stellen, an denen ein Schritt die Policy-Engine erreicht hat, zeigt die Timeline die Entscheidung (allow, warn, require_approval oder block), sodass Sie Governance und Ausführung nebeneinander sehen.

ℹ️ Note

Spans durchlaufen den **KLA Collector**, der personenbezogene Daten (PII) redigiert, bevor irgendetwas gespeichert wird. Der Explorer zeigt den redigierten Datensatz, sodass die Untersuchung sensible Eingaben nicht erneut offenlegt.

flowchart TD
  A["Auslösender Prompt"] --> B["Planungsschritt"]
  B --> C["Tool: lookup_claim"]
  B --> D["Tool: fetch_policy_doc"]
  C --> E{"Policy-Entscheidung"}
  D --> E
  E -->|allow| F["Modell-Completion"]
  E -->|require_approval| G["Decision Desk"]
  F --> H["Finale Ausgabe"]

Datenherkunft über Agentenketten hinweg

Moderne Systeme verketten Agenten: Die Ausgabe eines Agenten wird zur Eingabe eines anderen. Der Explorer verfolgt einen Wert über diese Grenzen hinweg, sodass Sie die Frage "Woher stammt dieses Feld?" beantworten können. Wenn ein Orchestrator einem Sub-Agenten eine Kundenreferenz übergibt und dieser Sub-Agent ein Dokument abruft, das zum Entwurf einer finalen Antwort verwendet wird, verknüpft die Lineage die ursprüngliche Eingabe mit jedem nachgelagerten Schritt, der sie konsumiert hat. Für eine Entwicklerin, die einer fehlerhaften Ausgabe nachgeht, schrumpft so stundenlanges Durchsuchen von Logs auf eine einzige Traversierung. Für einen Prüfer schafft dies Provenienz: welche Quelldaten welche Entscheidung beeinflusst haben.

Verifizierung per Merkle proof

Eine Timeline ist nur dann ein Beweis, wenn Sie nachweisen können, dass sie nicht bearbeitet wurde. Während Spans aufgezeichnet werden, werden ihre Hashes in einem kryptografischen ImmuDB-Ledger verankert, einem ausschließlich anhängenden Speicher (Append-only), der über jeden Eintrag einen Merkle-Baum führt. Um einen Lineage Record zu verifizieren, berechnet der Explorer den Hash des Datensatzes neu und durchläuft den Merkle-Pfad bis hinauf zum verankerten Root.

Übereinstimmung bestätigt, dass der Datensatz Byte für Byte dem entspricht, was zum Ausführungszeitpunkt versiegelt wurde.
Abweichung kennzeichnet Manipulation oder Korruption zur Untersuchung.

🛡️ Important

Die Verifizierung ist unabhängig. Der Beweis hält stand, selbst wenn Sie der Anwendung, die den Datensatz erzeugt hat, nicht mehr vertrauen, und genau das macht einen Lineage Record zu belastbaren Beweismitteln und nicht nur zu einem Log.

sequenceDiagram
  participant U as Prüfer
  participant LE as Lineage Explorer
  participant L as ImmuDB-Ledger
  U->>LE: Lineage Record öffnen
  LE->>LE: Datensatz-Hash neu berechnen
  LE->>L: Merkle proof anfordern
  L-->>LE: Pfad zum verankerten Root
  LE->>U: Verifiziert oder Manipuliert

Sie können den Verifizierungsstatus eines Datensatzes über die API abrufen:

curl https://api.kla.digital/v1/lineage/lr_8f21/verify \
  -H "Authorization: Bearer $KLA_ACCESS_TOKEN" \
  -H "x-tenant-id: acme-prod"

Export in den Evidence Room

Wenn ein Datensatz (oder eine gefilterte Menge von Datensätzen, die einen Vorfall oder ein Audit-Zeitfenster umspannt) den Explorer als formales Artefakt verlassen soll, leiten Sie ihn an den Evidence Room weiter. Dort wird er in ein Sealed Evidence Bundle verpackt: signierte Datensätze, vollständige Lineage, Policy-Zustand und die Verifizierungsprotokolle, bereit zur Weitergabe an eine Regulierungsbehörde oder zum Anhängen an ein Control Pack. Im Explorer untersuchen Sie; im Evidence Room zertifizieren und exportieren Sie.