KI-Anwendungen instrumentieren: Fehler, Latenz und Verbrauch nachvollziehen

1. Beginnen Sie mit Betriebsfragen, nicht mit Feldern

Die Observability einer KI-Anwendung bedeutet, ihr Verhalten anhand zusammengehöriger Signale nachvollziehen zu können: Welche Anfrage ist eingegangen, welche Schritte wurden ausgeführt, was ist fehlgeschlagen und wie lange hat jede Phase gedauert? Bei einer Anwendung, die bereits ein Modell über eine API aufruft, heißt Instrumentierung nicht, jede Eingabe und Antwort in ein Protokoll zu kopieren. Gemeint ist, genügend Kontext zu erfassen, um Betriebsfragen wiederholbar beantworten zu können – mit klar definiertem Umfang und einer festgelegten Datenrichtlinie.

Bevor Sie eine Bibliothek auswählen oder ein Dashboard bauen, halten Sie fest, welche Fragen Ihr Team während eines Vorfalls beantworten muss. Zum Beispiel: Welche Version der Anwendung und des Prompts hat diese Anfrage verarbeitet? Wurde das Modell einmal aufgerufen oder gab es Wiederholungsversuche? Welches Tool wurde ausgeführt und wie lange dauerte es? Entstand die Verzögerung in der Anwendung, im Netzwerk, beim Modell oder bei einem Tool? Welchen Verbrauch hat die API gemeldet? Solche Fragen bestimmen das Design. Felder, die bei der Beantwortung nicht helfen, sollten nicht aus Gewohnheit aufgenommen werden.

Observability ist von der Bewertung der Inhalte zu unterscheiden. Dieser Artikel konzentriert sich auf den technischen und betrieblichen Ablauf einer Anfrage: Fehler, Latenz, Wiederholungen und gemeldeter Verbrauch. Er bietet keine Methode, um zu entscheiden, ob eine Antwort wahr ist, einen Anbieter auszuwählen oder einen Gesprächsablauf zu gestalten. Diese Abgrenzung hält die Protokollierung schlank und verhindert, dass ein technisches Signal als Beleg für die inhaltliche Qualität missverstanden wird.

2. Zeichnen Sie den Ablauf auf und legen Sie die Korrelation fest

Eine Anfrage, die aus Sicht der Benutzeroberfläche wie ein einzelner Aufruf wirkt, kann mehrere Vorgänge umfassen: Eingabevalidierung, Prompt-Erstellung, Modellaufruf, Verarbeitung der Antwort und möglicherweise einen Tool-Aufruf. Bei Wiederholungen muss jeder Versuch als eigener Vorgang sichtbar bleiben. Das Protokoll sollte diese Ereignisse zusammenführen, ohne sich auf IDs zu verlassen, deren Verfügbarkeit die externe API nicht garantiert.

Erzeugen Sie beim Eingang in Ihre Anwendung eine eigene Anfrage-ID und reichen Sie sie durch die Komponenten weiter, die Sie kontrollieren. Verwenden Sie untergeordnete IDs oder Schritt-Nummern, um Modell- und Tool-Aufrufe zu unterscheiden. Gibt der Anbieter eine Anfrage-ID zurück, speichern Sie sie als zusätzliches Feld für spätere Abfragen oder Supportfälle. Verwenden Sie sie jedoch nicht als einzige Verknüpfung: In manchen Fehlerfällen oder Ausführungspfaden ist sie möglicherweise nicht verfügbar.

Legen Sie außerdem die zeitlichen Grenzen jeder Messung fest. Die Gesamtdauer beginnt, wenn die Anwendung die Anfrage annimmt, und endet mit der Ausgabe der Antwort oder der Erfassung des endgültigen Fehlers. Die Dauer eines Modellaufrufs beginnt mit dem Start dieses Aufrufs und endet mit dem Eingang einer Antwort oder eines Fehlers. Ein Tool-Aufruf erhält eigene Start- und Endzeiten. Millisekunden ohne klare Definition dieser Grenzen ergeben Werte, die sich nicht verlässlich vergleichen lassen.

3. Definieren Sie ein minimales Schema und erfassen Sie nur tatsächlich gelieferte API-Daten

Ein minimales Schema sollte Daten aus der eigenen Anwendung von Feldern unterscheiden, die vom Anbieter stammen. Zu den eigenen Feldern zählen typischerweise Anfrage-ID, Schritt, Versuchsnummer, Status, Zeitstempel sowie Code- und Prompt-Versionen. Angefordertes Modell, Konfiguration und eine vom Anbieter zurückgegebene ID können bei der Rekonstruktion helfen, sollten aber nach ihrer Herkunft gekennzeichnet sein.

Von einer API gemeldete Verbrauchsdaten sind nicht universell. Sie können je nach Endpunkt, Modell, Modalität, Version oder Antworttyp variieren und bei Fehlern oder Teilantworten fehlen. Die für diesen Leitfaden verfügbaren Quellen nennen keinen bestimmten Anbieter und erlauben daher keine allgemeingültige Feldliste. Implementieren Sie deshalb einen Adapter pro API und prüfen Sie in der jeweils aktuellen Primärdokumentation Feldnamen, Einheiten und Bedingungen. Speichern Sie das Ergebnis als „von der API gemeldeter Verbrauch“ und halten Sie fest, welche Felder vorhanden waren. Fehlende Werte sollten nicht stillschweigend durch Nullen ersetzt werden.

Trennen Sie außerdem die von Ihrer Anwendung gemessene Zeit von einer möglicherweise vom Anbieter gemeldeten Dauer. Die erste beschreibt den Ablauf in Ihrem System; die zweite folgt – sofern vorhanden – der Definition des Anbieters. Geben Sie Einheiten ausdrücklich an, etwa Millisekunden für Dauern, und legen Sie fest, ob Zeitstempel in UTC gespeichert werden. Einheitliche Konventionen erleichtern den Vergleich von Anfragen und das Erkennen von Veränderungen, ohne Uhren oder unterschiedliche Zeitintervalle zu vermischen.

4. Instrumentieren Sie strukturierte Ereignisse durchgängig

Strukturierte Protokolle lassen sich leichter filtern und gruppieren als frei formulierte Meldungen. Legen Sie stabile Namen für Ereignisse, Status und Felder fest. Vermeiden Sie, dass jede Komponente denselben Sachverhalt anders bezeichnet. Für den Anfang ist kein bestimmter Observability-Anbieter erforderlich: Die Anwendung kann JSON-Ereignisse ausgeben und sie in die bereits verwendete Plattform exportieren.

Ein nützliches Muster besteht darin, für jeden Schritt ein Start- und ein Abschlussereignis auszugeben. Bei kurzen Schritten, die keine Aktualisierung in Echtzeit benötigen, kann auch ein einzelnes Abschlussereignis mit Start, Ende und Ergebnis genügen. Bei längeren Vorgängen muss das Abschlussereignis weiterhin mit der ursprünglichen Anfrage verknüpft sein. Verwenden Sie verteilte Traces, sollte der Kontext über Dienste und Warteschlangen hinweg weitergegeben werden, die Sie kontrollieren. Prüfen Sie, dass die ID beim Übergang von synchronen zu asynchronen Aufgaben nicht verloren geht.

Das folgende Beispiel ist schematischer Pseudocode und keine ausführbare Integration mit einer API: Namen von Antwort- und Fehlerfeldern hängen von SDK und Anbieter ab. Passen Sie in der tatsächlichen Implementierung die Extraktion von Verbrauchs- und Fehlerdaten an die aktuelle Dokumentation an. Stellen Sie außerdem sicher, dass ein Ausnahmebehandler nicht automatisch Antwortinhalte protokolliert, die sensible Daten enthalten könnten.

5. Minimieren Sie sensible Daten vor dem Speichern oder Exportieren

Observability erfordert nicht, vollständige Prompts, Antworten oder Tool-Argumente für jede Anfrage aufzubewahren. Solche Inhalte können personenbezogene Daten, Geheimnisse, Geschäftsinformationen oder Material enthalten, das für die Beantwortung betrieblicher Fragen nicht erforderlich ist. Beginnen Sie mit Metadaten und abgeleiteten Signalen: undurchsichtigen IDs, Versionen, Längen, Fehlerkategorien, Status und Zeiten.

Legen Sie für jedes Feld fest, ob es ausgeschlossen, geschwärzt, transformiert oder mit eingeschränktem Zugriff und begrenzter Aufbewahrungsdauer gespeichert werden soll. Für die Verknüpfung mit einem Geschäftsvorgang kann ein pseudonymer Schlüssel oder ein interner Verweis ausreichen, den nur ein autorisiertes System auflösen kann. Ein Hash garantiert keine Anonymität, wenn der Ausgangswert vorhersehbar ist oder mit einer Liste abgeglichen werden kann. Behandeln Sie ihn daher nicht automatisch als Datenschutzlösung.

Testen Sie die Schwärzung, bevor Sie die Protokollierung in der Produktion aktivieren. Verwenden Sie synthetische Beispiele für typische Fälle und Varianten, etwa eine E-Mail-Adresse in einer Eingabe, ein Token in einem Header oder vertrauliche Daten in einer Tool-Antwort. Prüfen Sie sowohl das Ereignis, das die Anwendung verlässt, als auch dasjenige, das im Speicher ankommt: Eine Regel, die erst im Dashboard oder nach dem Export greift, lässt die Daten auf dem Übertragungsweg ungeschützt.

6. Bauen Sie Dashboards und Warnungen für die Diagnose, nicht für eine Sammlung von Diagrammen

Ein nützliches Dashboard beantwortet eine Frage und macht deutlich, welche Maßnahme daraus folgen kann. Beginnen Sie mit drei Ansichten: Anfragezustand, Latenzverteilung und gemeldeter Verbrauch. Für den Zustand zeigen Sie abgeschlossene, fehlgeschlagene und nicht endgültig abgeschlossene Anfragen, getrennt nach Fehlerkategorie. Für die Latenz zeigen Sie die Gesamtdauer und die Dauer pro Schritt sowie Perzentile zusätzlich zu Durchschnittswerten, denn ein Durchschnitt kann eine lange Warteschlange langsamer Anfragen verbergen. Für den Verbrauch zeigen Sie nur verfügbare Felder und schlüsseln nach Modell, Version oder Anfrageart auf, sofern diese Unterteilung hilft, Veränderungen zu finden.

Warnungen sollten Bedingungen anzeigen, die jemand untersuchen oder beheben kann. Eine über einen festgelegten Zeitraum ungewöhnlich hohe Fehlerrate kann eine Warnung rechtfertigen; ein einzelner Fehler kann im Protokoll bleiben, ohne ein Team zu alarmieren. Schwellenwerte hängen von Volumen und Serviceerwartungen ab. Ein allgemeingültiger Wert lässt sich daher nicht sinnvoll ohne Daten festlegen. Geben Sie das Beobachtungsfenster, die verantwortliche Person und einen Link zur Abfrage oder zum Reaktionsverfahren an.

Stellen Sie eine auf gemeldetem Verbrauch beruhende Kostenschätzung nicht als abgerechneten Betrag dar. Für eine interne Schätzung können Sie verfügbare Einheiten mit den Preisen und Regeln multiplizieren, die für das konkrete Konto und die Konfiguration gelten, und das Ergebnis als Schätzung kennzeichnen. Die tatsächlichen Beträge können von Bedingungen abhängen, die sich nicht allein aus dem Antwortereignis ableiten lassen. Prüfen Sie einen Abgleich daher anhand der aktuellen offiziellen Preis- und Abrechnungsdaten des jeweiligen Anbieters.

7. Untersuchen Sie eine fehlgeschlagene Anfrage nachvollziehbar

Geht eine Meldung ein, beginnen Sie mit der Anfrage-ID und bestätigen Sie, dass sie zur richtigen Umgebung und zum richtigen Zeitraum gehört. Führen Sie die Ereignisse nach Zeit und Schritt geordnet zusammen. Prüfen Sie vor der Interpretation, ob der Trace vollständig ist: Gibt es Start- und Abschlussereignisse? Fehlen Tool-Spans? Kennzeichnet das Protokoll einen terminalen Fehler oder nur einen fehlgeschlagenen Versuch? Eine unvollständige Ausführung kann wie ein Modellfehler wirken, obwohl lediglich die Belege nicht gespeichert wurden.

Rekonstruieren Sie anschließend Versionen und Ablauf: Anwendungscode, Prompt-Version, angefordertes Modell und – sofern beobachtbar – aufgelöstes Modell, Anzahl der Versuche, Tools und Status. Vergleichen Sie die Gesamtdauer mit der Summe der einzelnen Schritte und berücksichtigen Sie lokale Verarbeitung, Warteschlangen und nicht instrumentierte Zeiten. Stimmt die Summe nicht, halten Sie das als Lücke in der Telemetrie fest, nicht als Beleg für eine Ursache.

Trennen Sie zum Schluss Beobachtungen von Hypothesen. Ein Timeout beim Anbieter kann als Ergebnis eines Versuchs dokumentiert sein; für sich genommen erklärt es nicht, warum er aufgetreten ist. Ein langsames Tool kann einen Teil der gemessenen Zeit erklären, aber nicht zwingend das Endverhalten. Halten Sie fest, was bekannt ist, welche Informationen fehlen und welche Prüfung die Hypothesen unterscheiden könnte. So vermeiden Sie, Ursachen zu behaupten, die das Protokoll nicht belegt.

8. Prüfen Sie die Instrumentierung und erweitern Sie sie schrittweise

Auch die Instrumentierung braucht Tests: Eine Anwendung kann funktionieren und zugleich IDs verlieren, Abschlussereignisse auslassen oder Daten speichern, die hätten geschwärzt werden müssen. Führen Sie kontrollierte Tests für Erfolg, Fehler, Timeout, Wiederholungsversuch und Tool-Aufruf durch. Prüfen Sie in jedem Fall den vollständigen Ablauf vom Eingangsereignis bis zum Endergebnis sowie Berechtigungen und Schwärzung vor dem Export.

Beginnen Sie mit einem begrenzten Produktionspfad und prüfen Sie, ob die Abfragen echte Fragen beantworten. Kontrollieren Sie, wie viele Daten das Protokoll erzeugt und ob das Team eine Anfrage findet, ohne manuell in mehreren Systemen suchen zu müssen. Passen Sie Ereignisauswahl und Aufbewahrung an, bevor Sie den Umfang ausweiten. Ziel ist nicht, möglichst viel Telemetrie zu erzeugen, sondern genügend aussagekräftige und auffindbare Belege für den Betrieb des Systems zu erhalten.

Telemetriekonventionen und API-Verbrauchsfelder können sich ändern. Versionieren Sie Ihr internes Schema und validieren Sie Adapter, wenn sich SDK, API oder Konfiguration ändern. Ändert der Anbieter eine Antwort, sollte sich die Normalisierungsschicht anpassen lassen, ohne dass jedes Dashboard und jede Abfrage von externen Feldnamen abhängt. Allgemeine Observability-Praktiken können bei der Organisation von Signalen und Traces helfen; sie ersetzen nicht die technische Primärdokumentation zu Feldern oder Abrechnung eines bestimmten Anbieters.

Weiter entdecken

Korrekturen und Transparenz

Wenn du falsche oder veraltete Angaben findest, sende uns die Seite und die zu prüfende Quelle.