Tracing für KI-Anwendungen: Antworten diagnostizieren, ohne unnötig sensible Daten zu protokollieren

Was ein KI-Trace leistet – und was er nicht belegt

Ein Trace macht die Vorgänge sichtbar, aus denen sich eine Anfrage zusammensetzt, und zeigt ihre Beziehungen. In einer KI-Anwendung kann er die vom Dienst empfangene Eingabe mit dem Abruf von Dokumenten, einem oder mehreren Modellaufrufen, Tool-Ausführungen, Validierungen und der ausgegebenen Antwort verknüpfen. Sein wichtigster Zweck ist es, den technischen Ablauf nachzuvollziehen: Welche Schritte fanden statt, in welcher Reihenfolge und an welcher Stelle kam es zu einer Verzögerung, einem Fehler oder einem unerwarteten Ergebnis?

Ein Trace belegt für sich genommen nicht, warum ein Modell eine bestimmte Formulierung erzeugt hat, dass eine Antwort korrekt ist oder dass eine künftige Ausführung sie wiederholen wird. Er bildet ab, was das instrumentierte System beobachtet und aufzuzeichnen beschlossen hat. Fehlen Spans, Attribute oder Ereignisse, kann der Ablauf unvollständig bleiben. Wird sensibler Inhalt ausgeschlossen, lässt sich möglicherweise auch die Eingabe oder Antwort nicht wörtlich untersuchen. Das kann eine bewusste Datenschutzentscheidung sein und muss kein Mangel des Traces sein.

Es ist wichtig, beobachtete Tatsachen von Hypothesen zu trennen. „Der Tool-Aufruf endete mit einem Fehler“ ist eine Beobachtung, die in der Telemetrie stehen kann. „Dieser Fehler hat die falsche Antwort verursacht“ ist eine Interpretation, für die der Ablauf geprüft und, wenn möglich, mit anderen Ausführungen verglichen werden muss. Tracing hilft dabei, eine wahrscheinliche Ursache einzugrenzen; es ersetzt weder Tests noch Qualitätsbewertungen oder eine Prüfung der Daten und Systemanweisungen.

Traces, Metriken und Logs: unterschiedliche Signale

Ein Trace bildet eine zusammenhängende Ausführung Ende zu Ende ab. Seine Spans beschreiben Vorgänge und können in einer Eltern-Kind-Beziehung stehen. Beispielsweise kann ein Antwortvorgang einen Retrieval- und einen Generierungsschritt enthalten, und zur Generierung kann wiederum ein Tool-Aufruf gehören. Ereignisse an einem Span ergänzen einzelne Vorkommnisse. Dank dieser Struktur lässt sich eine Anfrage nachvollziehen, ohne sich allein auf die Suche nach ähnlichen Textmeldungen zu verlassen.

Eine Metrik fasst Messwerte zusammen, mit denen sich Trends oder aggregierte Zustände beobachten lassen, etwa Dauer oder Fehleranzahl. Sie hilft, Veränderungen zu erkennen und Gruppen von Ausführungen zu vergleichen, erklärt aber für gewöhnlich nicht, was bei einer bestimmten Anfrage geschah. Verwenden Sie eindeutige Nutzer-, Anfrage- oder Dokument-IDs nicht als Metrikdimensionen: Sie führen zu hoher Kardinalität und erschweren handhabbare Aggregationen. Nutzen Sie Traces für Details und Metriken mit begrenzten Dimensionen für die aggregierte Überwachung.

Ein Log ist ein eigenständiges Ereignis oder eine Meldung, etwa eine Warnung eines Validators. Es kann Trace-Kontext enthalten, über den es sich mit einer Ausführung verknüpfen lässt, bildet aber nicht zwingend die hierarchische Struktur aller Schritte ab. In der Praxis ergänzen sich die drei Signalarten: Metriken helfen, eine Anomalie zu erkennen, Traces machen eine Ausführung nachvollziehbar und Logs liefern punktuellen Kontext. Keine dieser Signalarten setzt voraus, dass der vollständige Gesprächsinhalt gespeichert wird.

Den Ablauf einer Anfrage skizzieren

Skizzieren Sie vor der Instrumentierung den tatsächlichen Ablauf der Anwendung – nicht den Ablauf, von dem Sie annehmen, dass er stattfindet. Ein einfacher Vorgang könnte beim Eingabedienst beginnen, die Anfrage prüfen, Dokumente abrufen, den Kontext erstellen, das Modell aufrufen, bei Bedarf ein Tool ausführen, die Ausgabe validieren und eine Antwort zurückgeben. Es kann Wiederholungsversuche, Verzweigungen, parallele Aufrufe oder eine zweite Generierung nach dem Tool-Aufruf geben. Wenn sie für die Diagnose relevant sind, sollten sie als getrennte Vorgänge erscheinen.

Eine gut lesbare Hierarchie könnte einen Root-Span für den Anwendungsvorgang und untergeordnete Spans für Retrieval, Generierung, Tool und Validierung enthalten. Die Eltern-Kind-Beziehung zeigt, welcher Vorgang welchen umfasst. Kontextlinks können Vorgänge miteinander verbinden, die sich nicht ohne Weiteres in eine einfache Hierarchie einordnen lassen. Es ist nicht nötig, für jede interne Anweisung einen Span anzulegen: Instrumentieren Sie die Grenzen, an denen Entscheidungen getroffen, Abhängigkeiten aufgerufen oder Vorgänge fehleranfällig werden können.

Weisen Sie der Ausführung eine Korrelations-ID zu und propagieren Sie sie zu den beteiligten Vorgängen, einschließlich eigener Dienste, die Trace-Kontext übernehmen. Machen Sie diese ID weder zum Bestandteil des Span-Namens noch zu einer Metrikdimension. Span-Namen sollten Vorgänge stabil und mit begrenzter Variabilität beschreiben. Eindeutige Werte gehören – sofern nötig und sicher – in Trace-Attribute, die durch Zugriffskontrollen geschützt sind.

Mindestfelder, um den Ablauf zu rekonstruieren

Das Mindestschema sollte vier Fragen beantworten können: Welcher Vorgang hat stattgefunden? Zu welcher Ausführung gehörte er? Wie lange hat er gedauert? Wie ist er ausgegangen? Dafür sind in der Regel stabile Vorgangsnamen, Beziehungen zwischen Spans, Zeitstempel oder Dauer, Status und eine Fehlerkategorie hilfreich. Ergänzen Sie Attribute mit begrenzter Variabilität, mit denen sich beispielsweise Vorgangstyp oder Umgebung unterscheiden lassen. Die konkreten Attribute sollten zu der tatsächlich verwendeten Instrumentierung und den Konventionen des Teams passen.

Bei Generierungsaufrufen können auch Betriebsinformationen hilfreich sein, etwa der konfigurierte Anbieter oder das Modell, die Dauer, der Status und verfügbare Nutzungszähler. Verfügbarkeit und Bedeutung dieser Felder hängen von der Integration ab: Gehen Sie nicht davon aus, dass zwei Instrumentierungen denselben Wert gleich benennen oder auf dieselbe Weise berechnen. Erfassen Sie außerdem, ob Retrieval, Tool-Aufruf, Wiederholungsversuch oder Validierung stattgefunden hat, und verwenden Sie Statuswerte, die „nicht ausgeführt“ von „ausgeführt und fehlgeschlagen“ unterscheiden.

Um ein fehlerhaftes Ergebnis zu lokalisieren, ohne den Prompt oder jedes Dokument aufzubewahren, kombinieren Sie Ablaufmetadaten mit Mengen und Statusangaben: Anzahl der abgerufenen Ergebnisse, Validierungsergebnis, Fehlertyp, identifizierbare Anwendungsversion und Dauer pro Vorgang. Wenn Eingaben verglichen werden müssen, können Sie eingeschränkt zugängliche Hashwerte oder interne Referenzen erwägen. Prüfen Sie jedoch, ob sie umkehrbar sind oder eine Verknüpfung mit personenbezogenen Daten ermöglichen. Ein Hash ist nicht automatisch anonym. Protokollieren Sie nicht aus Bequemlichkeit Namen, Adressen, Zugriffstokens, vollständige Tool-Argumente oder ganze Dokumente.

Sensible Inhalte: reduzieren, redigieren und kontrollieren

Prompts, Antworten, abgerufene Dokumente und Tool-Argumente können personenbezogene Daten, vertrauliche Informationen oder Betriebsgeheimnisse enthalten. Behandeln Sie sie als potenziell sensibel, auch wenn die Anwendung sie nicht als solche klassifiziert. Für die übliche Diagnose ist es am sichersten, sie nicht standardmäßig zu erfassen. Benötigt ein konkreter Anwendungsfall Ausschnitte, legen Sie fest, welche Ausschnitte erfasst werden, wer sie einsehen darf, wie lange sie aufbewahrt werden und welches Genehmigungsverfahren gilt.

Beim Redigieren können Werte vor dem Export entfernt oder ersetzt werden. Durch Filterung lassen sich Daten oder Ereignisse verwerfen, die den Prozess nicht verlassen sollen. Legen Sie fest, an welcher Stelle diese Maßnahmen greifen, und überprüfen Sie ihre Wirkung mit Testdaten. Eine spätere Transformation im Collector kann Telemetrie vor dem Export verändern oder reduzieren. Das ist jedoch nicht gleichbedeutend damit, dass der Inhalt nicht bereits erzeugt, erfasst oder gespeichert wurde, bevor er diese Komponente erreicht. Prüfen Sie alle Stationen des Übertragungswegs: Instrumentierung, Puffer, Collector, Exporter und Speicher.

Beschränken Sie den Zugriff auf Traces nach Aufgabenbereich und protokollieren Sie Zugriffe, wenn die Plattform dies unterstützt. Legen Sie eine kurze Aufbewahrungsfrist fest, die dem Zeitraum entspricht, der für die Untersuchung von Vorfällen benötigt wird. Prüfen Sie, ob auch Kopien, Exporte und Puffer diese Richtlinie einhalten. Sampling kann das Datenvolumen senken, ersetzt aber nicht den Schutz jedes gespeicherten Traces. Halten Sie für Untersuchungen einen kontrollierten Weg bereit, um den Detailgrad vorübergehend zu erhöhen – mit Genehmigung, begrenztem Umfang und einem festgelegten Enddatum.

Einen Trace lesen, um die fehlerhafte Komponente zu finden

Beginnen Sie mit dem Root-Span und bestätigen Sie, dass er die zu untersuchende Ausführung darstellt. Prüfen Sie seinen Status und gehen Sie die untergeordneten Spans in zeitlicher Reihenfolge durch. Achten Sie auf Lücken zwischen Vorgängen, Spans ohne Ergebnis oder Abhängigkeiten, die im Vergleich zu ihrem eigenen Verlauf ungewöhnlich lange dauerten. Eine hohe Gesamtdauer identifiziert nicht von selbst die Komponente: Ursache können ein langsames Retrieval, ein Modellaufruf, das Warten auf ein Tool, Wiederholungsversuche oder nicht instrumentierte Arbeit sein.

Enthält die Antwort Informationen nicht, die hätten abgerufen werden sollen, prüfen Sie zunächst Status und Anzahl der Ergebnisse, Retrieval-Filter und Kontextaufbau. Scheint der Kontext angemessen, während die Generierung fehlschlägt oder lange dauert, untersuchen Sie den Modell-Span, seinen Status und etwaige Wiederholungsversuche. Fordert das Modell eine Aktion an, das Endergebnis ist aber falsch, verfolgen Sie den Tool-Span und prüfen Sie, ob das Tool fehlschlug, unerwartete Daten zurückgab oder nicht in den Ablauf einbezogen wurde. Wurde die Antwort zwar generiert, erreichte den Nutzer aber nicht, untersuchen Sie die Validierung und den Vorgang, der die Ausgabe erstellt.

Diese Wege sind Arbeitshypothesen und keine Regeln, um automatisch Schuld zuzuweisen. Ein Tool kann eine gültige Antwort liefern, die von der Anwendung falsch verarbeitet wird. Ein Validator kann eine korrekte Ausgabe aufgrund seiner Konfiguration zurückweisen. Ein unvollständiger Trace kann einen Zwischenschritt verbergen. Notieren Sie, welche Belege die jeweilige Schlussfolgerung stützen und welche Informationen fehlen. Erfordert die Diagnose eine Prüfung von Inhalten, beantragen Sie eine zeitlich begrenzte und genehmigte Erfassung in einem Testlauf, statt die Protokollierung von Nutzer-Prompts pauschal einzuschalten.

Wiederholung bedeutet nicht exakte Reproduktion

Eine Anfrage erneut auszuführen kann beim Vergleich von Änderungen helfen, garantiert aber nicht, dass die ursprüngliche Antwort reproduziert wird. Das Modell kann Variationen erzeugen. Außerdem können sich der Anwendungszustand, die abrufbaren Dokumente, die Indexversion, der Inhalt eines externen Tools oder die Dienstkonfiguration geändert haben. Eine spätere Wiederholung kann ähnliche Spans durchlaufen und trotzdem keine exakte Reproduktion sein.

Ein Vergleich wird aussagekräftiger, wenn Sie sicher und mit begrenztem Detailgrad die Anwendungsversion, relevante Konfiguration, von der Integration bereitgestellte Modellkennungen, den Indexstatus oder die Indexversion (sofern bekannt) sowie Versionen eigener Tools festhalten. Notieren Sie außerdem Zeitpunkt und Umgebung. Halten Sie Testeingaben unter Kontrolle und verwenden Sie synthetische oder genehmigte Inhalte, sofern der Zweck dies zulässt. Bietet eine externe Abhängigkeit weder eine Version noch einen Snapshot, halten Sie diese Einschränkung in der Analyse fest.

Unterscheiden Sie zwischen einer Wiederholung der Anfrage im aktuellen System und der Reproduktion einer historischen Ausführung mit denselben Abhängigkeiten und demselben Zustand. Die erste zeigt das aktuelle Verhalten. Die zweite setzt voraus, dass mehr Bedingungen erhalten und wiederhergestellt werden können. Das kann unpraktikabel oder unangemessen sein, wenn dafür sensible Daten aufbewahrt werden müssten. Bezeichnen Sie einen Test nicht allein deshalb als „reproduzierbar“, weil derselbe Eingabetext erneut verwendet wird. Beschreiben Sie, was gleich geblieben ist, was sich geändert haben könnte und welche Aussage der Vergleich tatsächlich stützt.

OpenTelemetry GenAI: eine nützliche Grundlage, noch in Entwicklung

OpenTelemetry veröffentlicht semantische Konventionen für generative KI-Systeme, die Ereignisse, Ausnahmen, Metriken und Spans rund um Modelle und Agenten abdecken. Sie bieten ein gemeinsames Vokabular und können dazu beitragen, dass unterschiedliche Instrumentierungen vergleichbare Vorgänge darstellen. Die Projektdokumentation kennzeichnet diese Konventionen als „Development“. Sie sind daher eine nützliche Referenz für die Bewertung von Namen und Attributen, aber kein universeller Vertrag, dessen Stabilität oder vollständige Übernahme vorausgesetzt werden kann.

Bevor Sie Dashboards, Alerts oder Exporte auf bestimmte Attribute stützen, prüfen Sie die Version der Konventionen und die Implementierung des jeweiligen SDK. Stellen Sie fest, welche Felder ausgegeben werden, wie sie benannt sind, ob sie Inhalte enthalten und welche Einstellungen die Erfassung verändern. Zwei Instrumentierungen können ähnliche Hierarchien abdecken und sich dennoch bei Namen, Werten, Redigierungsoptionen, Export oder Pufferverwaltung unterscheiden. Testen Sie deshalb die Interoperabilität und dokumentieren Sie Zuordnungen, statt sie einfach vorauszusetzen.

Die Dokumentation des OpenAI Agents SDK beschreibt eine Span-Hierarchie für Agenten, Generierungen und Tools sowie Optionen für sensible Daten, Export, Pufferung und Redigierung. Sie weist außerdem darauf hin, dass das Deaktivieren des Tracings nicht notwendigerweise Daten entfernt, die sich bereits in einem Puffer befinden. Das veranschaulicht eine allgemeine Vorsichtsmaßnahme: Eine Abschaltoption darf nicht als rückwirkender Löschmechanismus behandelt werden. Überprüfen Sie das Verhalten in der konkret eingesetzten Version und berücksichtigen Sie alle Stellen, an denen Daten verbleiben können.

Die verfügbaren Quellen reichen nicht aus, um festzustellen, welche Inhalte standardmäßig von jedem offiziellen SDK oder jeder Instrumentierung erfasst werden oder um zwei Implementierungen und ihre Optionen umfassend zu vergleichen. Diese Frage muss anhand der Dokumentation der eingesetzten Version und durch einen kontrollierten Test beantwortet werden. Bis dahin gilt die vorsichtige Annahme: Prüfen Sie die exportierten Inhalte und konfigurieren Sie die Datenreduktion ausdrücklich.

Checkliste zur Instrumentierung einer Anwendung

Beginnen Sie mit einem konkreten betrieblichen Anwendungsfall: Latenz lokalisieren, Retrieval-Fehler finden, Tool-Fehler erkennen oder Validierungsablehnungen untersuchen. Skizzieren Sie den Ablauf und vereinbaren Sie stabile Span-Namen. Prüfen Sie, ob der Kontext zwischen eigenen Komponenten weitergegeben wird und ob sich die vollständige Anfrage verfolgen lässt, ohne eindeutige Kennungen in Namen oder Metriken aufzunehmen. Erfassen Sie Status und Dauer, bevor Sie die Erfassung von Inhalten in Betracht ziehen.

Prüfen Sie jedes Attribut anhand einfacher Fragen: Welche betriebliche Entscheidung ermöglicht es? Enthält es sensible Informationen? Wie lange muss es aufbewahrt werden? Wer kann es sehen? Fehlt eine klare Antwort, lassen Sie es weg. Legen Sie Redigierung und Filterung an geeigneten Stellen der Pipeline fest und testen Sie auch Ausnahmen, Wiederholungsversuche und Exportfehler. Konfigurieren Sie Berechtigungen, Aufbewahrung und Sampling passend zum Risiko und zum Diagnosebedarf.

Führen Sie abschließend kontrollierte Tests durch: mit leerem Retrieval, einem simulierten Tool-Fehler, einer von der Validierung abgelehnten Antwort und einem Normalfall. Prüfen Sie, ob die Spans die Ergebnisse unterscheiden und ob Geheimnisse oder nicht genehmigte Inhalte in den Exporten auftauchen. Dokumentieren Sie bekannte Einschränkungen, einschließlich der Unmöglichkeit, wechselnde Abhängigkeiten exakt zu reproduzieren. Überprüfen Sie die Richtlinie regelmäßig: Eine für einen bestimmten Ablauf geeignete Instrumentierung kann ungeeignet werden, wenn weitere Agenten, Tools oder Datentypen hinzukommen.

Weiter entdecken

Korrekturen und Transparenz

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