Semantic Observability: KI-Traces verständlich machen

Eine KI-Funktion kann in zwei Sekunden antworten und trotzdem kaum betreibbar sein. Ging die Zeit für das Modell, einen Retrieval-Schritt, eine langsame interne API oder Wiederholungen eines Tool-Aufrufs durch einen Agent drauf? Hat ein Modellwechsel den Token-Verbrauch erhöht? Wählt ein Workflow plötzlich ein unerwartetes Tool? Ein herkömmlicher Request-Trace zeigt oft, dass Arbeit passiert ist. Was diese Arbeit bedeutete, sagt er häufig nicht.

Genau dieses Problem adressiert Semantic Observability: Du instrumentierst ein System mit Telemetrie, die fachlich bedeutsame Operationen benennt, statt nur Transportdetails aufzuzeichnen. Bei GenAI-Anwendungen sind das Modellinteraktionen, Agent-Aufrufe, Retrieval, Tool-Ausführung, Konversationen, Outputs und Token-Verbrauch. OpenTelemetry verschiebt seine GenAI-Attribute in ein eigenes Repository für Semantic Conventions und dokumentiert Conventions für Spans, Metriken, Events, Clients, MCP und provider-spezifische Instrumentierung. Das Vokabular wird bereits eingesetzt, befindet sich aber weiter in aktiver Entwicklung. Das machen die OpenTelemetry-Dokumentation und das Repository deutlich.

Einfach gesagt: Ein Trace soll nicht nur zeigen, dass deine Anwendung fünf Netzwerkaufrufe gemacht hat. Er soll zeigen, dass ein Agent ein Tool gewählt hat, das Tool einmal fehlgeschlagen ist, danach erneut ein Modell aufgerufen wurde und die Antwort eine bestimmte Zahl von Tokens verbraucht hat.

Das fehlende Vokabular gewöhnlicher Traces

Ein Trace ist ein zusammenhängender Nachweis der Arbeit für einen Request oder Job. Er besteht aus Spans: zeitlich erfassten Operationen, die über Eltern-Kind-Beziehungen verbunden sind. Distributed Tracing beantwortet schon heute Fragen wie: „Welcher Service hat diesen Datenbankaufruf ausgelöst?“ Es basiert auf Context Propagation: Kennungen werden über Service-Grenzen hinweg weitergegeben, damit sich unabhängig erzeugte Datensätze später verbinden lassen.

Diese Mechanik ist für KI-Systeme notwendig, reicht aber nicht aus. Wenn jede Operation nur POST /generate oder HTTP client request heißt, kann ein Backend zwar Dauer messen, aber nicht zuverlässig zwischen einer Agent-Entscheidung, einem Modellaufruf, einem Retrieval-Lookup und einer Tool-Ausführung unterscheiden. Auch Token-Nutzung lässt sich nicht konsistent aggregieren, wenn jedes SDK eigene Feldnamen und Einheiten erfindet.

Semantic Conventions von OpenTelemetry ergänzen diese fehlende Ebene. Sie definieren gemeinsame Namen und erwartete Bedeutungen für Telemetrie-Felder. Das dokumentierte GenAI-Vokabular umfasst Agent- und Konversationskennungen, Operationsnamen, Provider, angeforderte und Antwortmodelle, Output-Typen, Finish Reasons, Token-bezogene Attribute, Retrieval-Daten und Felder für Nachrichteninhalte. Das GenAI-Attributregister ist damit mehr als eine Benennungsreferenz: Es ist ein Interoperabilitätsvertrag für die Fragen, die ein Betriebsteam stellen können muss.

Warum ist das jetzt wichtig? KI-Anwendungen sind zunehmend Workflows und nicht einzelne Modell-Requests. Ein Nutzer-Request kann einen Agent dazu bringen, Context zusammenzustellen, ein Modell aufzurufen, ein Tool auszuführen, das Ergebnis zu prüfen und dann ein weiteres Modell oder einen Service aufzurufen. Das OpenTelemetry-Walkthrough bildet diese Form mit Spans für Agent Invocation, Model Call und Tool Execution ab und hängt Modellidentität sowie Token-Nutzung als semantische Attribute an. Das Walkthrough zeigt, warum eine einzige Kennzahl für die Dauer eines „KI-Requests“ nicht genügt.

So funktioniert das Modell Schritt für Schritt

Beginne bei der fachlichen Operation, nicht beim Telemetrie-Vendor. Stell dir einen internen Support-Assistenten vor, der eine Frage zu einem Kundenkonto beantwortet. Der Root Span steht für den eingehenden Request. Seine Kindoperationen sind keine generischen HTTP-Namen, sondern beschreiben den Workflow: Agent Invocation, Retrieval, Model Interaction und gegebenenfalls ein CRM-Lookup über ein Tool.

Jede Operation zeichnet Dauer, Status, Elternbeziehung und gezielt ausgewählte semantische Attribute auf. Der Agent Span kann den Agent und die Konversation identifizieren. Der Model Span kann Provider, angefordertes Modell und Antwortmodell, Output-Typ, Finish Reason sowie Zahlen für Input- und Output-Tokens enthalten. Ein Retrieval Span kann seine Retrieval-Operation und passende Metadaten identifizieren. Ein Tool Span beschreibt die Ausführung getrennt davon, dass das Modell sich für den Tool-Aufruf entschieden hat. Diese Felder machen aus einem Baum von Zeiten einen kausalen Bericht über den Workflow.

Der Trace bewahrt Details einzelner Requests. Metriken, die aus demselben Vokabular abgeleitet werden, liefern die Sicht auf die Gesamtheit: Modelllatenz nach Provider, Output-Tokens nach Agent, Tool-Fehlerraten nach Operation oder Workflows mit ungewöhnlich vielen Retries. Der praktische Gewinn ist Konsistenz. Wenn ein Service Modell A nutzt und ein anderer zu Modell B wechselt, müssen Dashboards nicht aus provider-spezifischen Payload-Formen auf Bedeutung schließen, sofern beide Instrumentierungen ihre Daten auf dieselben semantischen Begriffe abbilden.

Telemetrie reist üblicherweise über OTLP, ein gemeinsames Protokoll, von der Instrumentierung der Anwendung über Collector zu einem Observability-Backend. OTLP macht die Daten nicht selbst bedeutungsvoll; es transportiert, was die Instrumentierung ausgibt. Semantic Conventions sind die Vereinbarung, durch die ein kompatibles Backend die Bedeutung einer Operation erkennen kann, ohne jede Provider-API verstehen zu müssen.

Einfach gesagt: OTLP ist das Lieferformat. Semantic Conventions sind die Beschriftung auf dem Paket. Du brauchst beides, damit verschiedene Tools KI-Telemetrie ungefähr gleich interpretieren können.

Inhalte sind eine eigene Designentscheidung. Prompt-Text, Systemanweisungen, Tool-Argumente und Tool-Ergebnisse können bei einem Incident sehr hilfreich sein, enthalten aber möglicherweise Credentials, personenbezogene Daten, Kundendaten oder andere regulierte Informationen. Im OpenTelemetry-Beispiel werden Prompt- und Tool-Inhalte deshalb nicht standardmäßig erfasst; die Erfassung von Inhalten wird bei Bedarf ausdrücklich aktiviert. Dieser Default ist eine sinnvolle operative Haltung: stabile Metadaten breit erfassen und das Sammeln sensibler Inhalte bewusst, eingeschränkt und auditierbar gestalten.

Was Semantic Observability nicht ist

Sie ist kein Versprechen für Modellqualität. Ein Trace kann zeigen, dass ein Modell schnell antwortete, wenige Tokens nutzte und keine fehlgeschlagenen Tool-Aufrufe hatte. Das belegt nicht, dass die Antwort korrekt, sicher, relevant oder nützlich war. Evaluation ist die gesonderte Praxis, Outputs anhand einer Rubrik, eines Testsets, einer Policy oder menschlicher Prüfung zu beurteilen. Ausführungsdaten können einem Evaluation-System Evidenz liefern, aber Telemetrie allein erkennt keine Halluzinationen und beweist nicht die Relevanz abgerufener Dokumente.

Sie ist auch nicht einfach das Loggen von Prompts und Antworten. Rohe Logs können unverzichtbar sein, besonders beim Debugging, doch ihnen fehlen oft konsistente Operationsgrenzen, kausale Verbindungen und typisierte Attribute. Außerdem können sie zu einer unkontrollierten Kopie sensibler Nutzerinhalte werden. Semantic Observability kann ausgewählte Inhalte einschließen, wenn die Policy es erlaubt. Ihr Kern sind jedoch strukturierte, verbundene Metadaten.

Sie ersetzt auch keine Vendor-Tools. Provider-spezifische Observability-Produkte können nützliche Funktionen haben und Details liefern, die ein gemeinsames Schema noch nicht abdeckt. Der Nachteil ist Kopplung: Dashboards, Alerts und Queries können vom Event-Modell eines Vendors abhängig werden. Ein gemeinsames Vokabular beseitigt diese Produktunterschiede nicht, gibt deiner Instrumentierung aber eine portable Grundlage.

Und sie ist kein fertiger, unveränderlicher Standard. OpenTelemetry beschreibt seine GenAI Conventions als aktiv in Entwicklung, und das eigene Repository definiert weiterhin die einschlägigen Span-, Metrik- und Event-Conventions. Der Projektstatus ist ein Grund, deinen Telemetrievertrag zu versionieren und Mappings in der Instrumentierung zu kapseln – nicht ein Grund, auf Perfektion zu warten.

Ein realistisches Engineering-Beispiel

Stell dir einen Produktionsservice vor, der Support-Mitarbeitenden die Frage beantwortet: „Warum wurde diese Rechnung angepasst?“ Der Request startet einen Agent-Workflow. Der Agent ruft relevante Rechnungs- und Richtliniendaten ab, bittet ein Modell um eine Zusammenfassung der Belege und kann über ein Billing-Tool ein fehlendes Detail laden.

Ohne aussagekräftige Spans sieht ein On-Call Engineer einen langsamen Request und einige SDK-Aufrufe. Mit Semantic Observability kann er dem Root Request in eine Agent Invocation folgen, sehen, dass Retrieval schnell war, beobachten, dass der erste Model Call beendet wurde, und feststellen, dass das Billing-Tool zweimal wiederholt wurde. Anschließend kann er prüfen, ob die Token-Nutzung des Model Calls gegenüber der üblichen Last gestiegen ist, ob ein bestimmter Provider oder ein Antwortmodell beteiligt ist und ob ein Finish Reason bei Fehlern gehäuft vorkommt. Das ist Diagnose statt Raten anhand eines einzelnen Latenzdiagramms.

Das Design verlangt nicht, Rechnungsinhalte oder Kundennachrichten in jedem Trace aufzuzeichnen. Das Team kann zunächst Kennungen, Modell- und Operationsmetadaten, Token-Zahlen, Zeiten, Ergebnisse und begrenzte Fehlerinformationen ausgeben. Braucht ein genehmigter Incident-Workflow Inhalte, lässt sich eine eng begrenzte Erfassung mit Zugriffskontrollen und Aufbewahrungsregeln aktivieren, statt alle Prompts stillschweigend in einen allgemeinen Log-Sink zu schreiben.

Achte auf hohe Cardinality: Attribute, deren Werte bei fast jedem Request wechseln, etwa Konversationskennungen, beliebige Prompt-IDs oder detaillierte Modellversions-Strings. Hohe Cardinality kann Speicher- und Query-Kosten steigern und breite Metrikaggregationen weniger nützlich machen. Behalte Kennungen pro Request dort, wo Trace-Korrelation sie braucht; mache nicht jede Kennung leichtfertig zu einer Metrikdimension. Cardinality ist eine Entscheidung über Betriebskosten und keine Nebensache der Implementierung.

Einfach gesagt: Lege eindeutige IDs in Traces ab, wenn sie dir helfen, einen einzelnen Request zu untersuchen. Gruppiere nicht automatisch jedes Dashboard danach, sonst können deine Telemetrierechnung und Queries schwerer beherrschbar werden.

Wo es scheitert

Der häufigste Fehler ist oberflächliche Instrumentierung: Ein SDK wird umhüllt, aber es werden nur Dauer und Provider-Name ausgegeben. Das ergibt einen schöneren Timer, aber kein brauchbares Modell eines Agent-Workflows. Entscheide vor der Implementierung von Spans, welche Operationen wichtig sind, und halte ihre Grenzen über Services hinweg stabil.

Ein zweiter Fehler ist, ein gemeinsames Schema als Normalisierung der Realität zu behandeln. Provider können unterschiedliche Tokenisierung, Preise, Latenzverhalten, Request-Formate und Modellsemantik haben. Die Conventions machen Felder, wo möglich, in ihrer Bedeutung vergleichbar; sie machen Provider nicht identisch. Bewahre rohe provider-spezifische Diagnostik an kontrollierten Stellen auf, wenn sie notwendig ist, und nutze gemeinsame Felder für systemübergreifendes Reporting.

Ein dritter Fehler ist zu viel Erfassung. Inhalte überall mitzuschneiden schafft Datenschutz-, Sicherheits- und Aufbewahrungspflichten, die den Nutzen beim Debugging überwiegen können. Umgekehrt löst Metadaten-only-Telemetrie einen Incident manchmal nicht vollständig auf. Die richtige Antwort ist weder „alles loggen“ noch „nie Inhalte erfassen“, sondern eine gestufte Policy: Was wird standardmäßig gesammelt, wer darf mehr aktivieren, wo wird es gespeichert und wann wird es gelöscht?

Was du diese Woche tun kannst

Zeichne zuerst einen echten KI-Request als Operationsgraph. Benenne Root Request, Agent Invocation, Model Interactions, Retrieval-Schritte und Tool Executions. Wenn sich eine Operation nicht klar benennen lässt, ist möglicherweise auch die Anwendungsgrenze unklar.

Schreibe zweitens einen kleinen Telemetrievertrag für die stabilen Felder, die dein Team braucht: Operationsname, Agent- oder Workflow-Identität, Provider- und Modellidentität, Ergebnis, Dauer, Token-Nutzung sowie Retry- oder Fehlersignale. Richte ihn, wo passend, an den aktuellen OpenTelemetry GenAI Conventions aus und halte das Mapping vom Provider auf die Conventions hinter einem schmalen Adapter.

Lege drittens den Umgang mit Inhalten vor dem Rollout fest. Trenne Metadaten für den regulären Betrieb von sensiblen Inhalten, die nur für außergewöhnliche Diagnosefälle nötig sind. Prüfe Aufbewahrung, Zugriff und Redaction mit den Verantwortlichen für deine Daten-Policy.

Nutze schließlich Traces und Metriken, um vor aufwendigen Dashboards operative Fragen festzulegen: Welche Komponente dominiert die p95-Latenz? Welche Workflows wiederholen Tools? Welches Modell oder welcher Agent treibt das Token-Wachstum? Ergänze dann separate Evaluations für Antwortqualität und Sicherheit. Ein System ist beobachtbar, wenn es Engineers hilft, Verhalten zu erklären; vertrauenswürdig wird es erst, wenn operative Evidenz und Evidenz zur Qualität gemeinsam vorhanden sind.