So bauen Sie mit OpenTelemetry eine anbieterneutrale LLM-Beobachtbarkeit auf

Die Beobachtbarkeit von LLM bricht zusammen, wenn jedes Anwendungsteam Anbieterantworten in seinem eigenen Format protokolliert. Während eines Vorfalls müssen Plattformteams konkrete Fragen beantworten: Welches Team hat die Anfrage gestellt, welcher API-Schlüsselbereich wurde verwendet, welches Modell wurde angefordert, welcher Anbieter es tatsächlich bereitgestellt hat, ob ein Wiederholungsversuch oder ein Fallback stattgefunden hat, wie viele Token verbraucht wurden, welcher Latenz-Bucket sich geändert hat und welche Fehlerklasse den Fehler verursacht hat. Sie benötigen diese Antworten auch, ohne rohe Eingabeaufforderungen, Vervollständigungen, Anbieterschlüssel oder Kundenkennungen in generische Protokollspeicher zu kopieren.

Die praktische Antwort besteht darin, das Multi-Modell-Gateway API als Kontrollpunkt für die Beobachtbarkeit zu instrumentieren. Die Ablaufverfolgung auf Anwendungsebene ist immer noch wichtig, aber das Gateway ist der Ort, an dem Anbieterauswahl, Wiederholungsversuche, Fallbacks, Nutzungsabrechnung, Anforderungseigentum und Datenschutzdurchsetzung normalisiert werden können, bevor die Telemetrie nachgeschaltete Tools erreicht. Für Teams, die ein Unternehmens-LLM API betreiben, ist dies der Unterschied zwischen verstreuten Debugging-Daten und einem anbieterneutralen Betriebsmodell.

Definieren Sie zuerst den Observability-Vertrag

Beginnen Sie mit einem schriftlichen Attributvertrag, nicht mit Dashboard-Screenshots. Der Vertrag sollte die Mindestmetadaten definieren, die jede LLM-Anfrage ausgeben muss, welche Felder das Gateway verlassen dürfen, welche Felder eingeschränkt sind und welche Felder niemals exportiert werden.

Ein nützlicher Basisvertrag umfasst Eigentums-, Routing-, Modell-, Nutzungs-, Latenz- und Ergebnismetadaten. Eigentumsattribute identifizieren die Organisation, das Team, die Umgebung, die Arbeitslast, die Anwendung und den Schlüsselbereich API. Routing-Attribute identifizieren die Gateway-Route, die Richtlinienversion, den angeforderten Anbieter, das angeforderte Modell, den ausgewählten Anbieter, das ausgewählte Modell, die Anzahl der Wiederholungen, die Fallback-Anzahl und ob Streaming verwendet wurde. Verwendungsattribute erfassen Eingabe-Tokens, Ausgabe-Tokens, zwischengespeicherte Eingabe-Tokens, Argumentations-Tokens (sofern verfügbar), die Anzahl der Anforderungen und die geschätzte Kostenklasse. Ergebnisattribute erfassen den Status, den Fehlercode des Anbieters, wenn er sicher ist, die normalisierte Fehlerklasse, das Validierungsergebnis, den Timeout-Status und das endgültige Antwortmodell.

Halten Sie den Vertrag anbieterneutral. Ein anbieterspezifischer Fehler wie eine Ratenbegrenzungsantwort, eine überladene Modellantwort, ein Schemavalidierungsfehler, eine Sicherheitsverweigerung, eine Zeitüberschreitung oder ein Kontextfensterfehler sollte einer normalisierten Fehlerklasse zugeordnet werden, die Dashboards anbieterübergreifend gruppieren können. Der ursprüngliche Fehlercode des Anbieters kann nützlich sein, sollte aber als eingeschränkte Diagnosedaten und nicht als primäre Dashboard-Dimension behandelt werden.

Verwenden Sie ein Gateway-zentriertes Span-Modell

Eine klare Trace-Struktur verhindert, dass die LLM-Telemetrie zu einem flachen Stapel von Spans wird. Verwenden Sie einen Bereich für eingehende Anwendungsanforderungen, einen Bereich für logische LLM-Operationen und untergeordnete Bereiche für die Arbeit, die das Gateway ausführt.

Eine typische Hierarchie sieht wie folgt aus:

inbound.http_request
  llm.operation
    llm.provider_attempt
    llm.provider_attempt.retry
    llm.provider_attempt.fallback
    retrieval.query
    tool.call
    output.validation

Der Bereich für eingehende Anforderungen stellt die Anfrage des Aufrufers an das Gateway dar. Die logische LLM-Operationsspanne stellt die für den Benutzer sichtbare LLM-Aufgabe dar, auch wenn das Gateway mehrere Provider-Versuche unternimmt. Anbieterversuchsspannen erfassen jeden tatsächlichen Aufruf an ein Upstream-Modell API. Abruf-, Tool- und Validierungsbereiche sollten untergeordnete Elemente des logischen Vorgangs sein, wenn sie Teil der Erstellung der endgültigen Antwort sind.

Diese Trennung ist bei Vorfällen wichtig. Wenn eine Anfrage von einem Modell auf ein anderes zurückfällt, kann die logische Operation erfolgreich sein, während der erste Versuch des Anbieters fehlschlägt. Wenn die endgültige Ausgabe die Schemavalidierung nicht besteht, ist der Anbieterversuch möglicherweise technisch erfolgreich, während der logische Vorgang fehlschlägt. Ohne separate Spans verbergen Dashboards entweder Anbieterausfälle hinter erfolgreichen Endbenutzerantworten oder überbewerten Fehler, die erfolgreich wiederhergestellt wurden.

OpenTelemetry GenAI-Attribute hinter einem internen Mapper zuordnen

OpenTelemetry-Semantikkonventionen sind vorhanden, sodass Telemetrieproduzenten gemeinsame Namen und Attribute über Codebasen, Bibliotheken und Plattformen hinweg verwenden.Das OpenTelemetry-Projekt verweist nun generative AI-Konventionen auf ein separates GenAI-Repository, und diese Konventionen definieren Modellanforderungs- und Antwortattribute wie Anbietername, angefordertes Modell, Antwortmodell, Eingabe-Tokens, Ausgabe-Tokens, Argumentations-Tokens und zwischengespeicherte Eingabe-Tokens.

Verwenden Sie diese GenAI-Attribute dort, wo sie passen, aber verteilen Sie rohe Attributnamen nicht im gesamten Gateway-Code. Wickeln Sie sie hinter einen kleinen Telemetrie-Mapper. Dieser Mapper sollte einen internen Anforderungsdatensatz akzeptieren und standardisierte Span-Attribute erzeugen.

record LlmTelemetryContext {
  organization_id
  team_id
  environment
  api_key_scope
  route_name
  route_policy_version
  workload_class
  provider_requested
  model_requested
  provider_selected
  model_response
  input_tokens
  output_tokens
  cached_input_tokens
  reasoning_tokens
  retry_count
  fallback_count
  normalized_error_class
}

Der Mapper kann OpenTelemetry GenAI-Attribute für die Standardfelder und private Gateway-Attribute für den Geschäftskontext ausgeben. Behalten Sie private Attribute unter einem kontrollierten Namespace, zum Beispiel llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy und llm_gateway.workload_class.

Dieses Design bietet Ihnen herstellerneutrale Telemetrie und schützt gleichzeitig die Codebasis vor Abwanderung. GenAI-Konventionen entwickeln sich noch weiter, daher können Namen im Mapper geändert werden, ohne dass jeder Handler, jedes Wiederholungsmodul, jeder Streaming-Adapter und jede Validierungskomponente bearbeitet werden muss.

Metadaten von sensiblen Inhalten trennen

LLM-Traces sind ungewöhnlich sensibel, da die nützlichsten Debugging-Daten möglicherweise dieselben Daten sind, die nicht allgemein aufbewahrt werden sollten: Eingabeaufforderungen, abgerufene Dokumente, Tool-Parameter, Vervollständigungen, Benutzer-IDs, Kunden-IDs, und Rohdaten des Anbieters. Der Standardstatus sollte Metadaten-erste Beobachtbarkeit sein.

Zu den empfohlenen Standardfeldern gehören Eingabeaufforderungs-Hash, Eingabeaufforderungsvorlagen-ID, Eingabeaufforderungsversion, Schema-ID, Toolname, Abrufsammlung, Routenname, Tokenanzahl, Latenz, normalisierte Fehlerklasse und Validierungsstatus. Diese Felder beantworten viele betriebliche Fragen, ohne dass Rohinhalte exportiert werden müssen.

Die Erfassung von Rohaufforderungen und Vervollständigungen sollte optional, zeitlich begrenzt, zugriffskontrolliert und vor dem Export geschwärzt sein. Aktivieren Sie es nicht global als Komfortfunktion. Wenn für einen Produktionsvorfall eine Inhaltserfassung erforderlich ist, fügen Sie einem begrenzten Satz von Anforderungen ein Debug-Flag hinzu, leiten Sie diese Spuren an ein eingeschränktes Backend weiter und legen Sie ein kurzes Aufbewahrungsfenster fest.

Hashing-Kennungen führen nicht automatisch zur Anonymisierung. Wenn der Eingaberaum klein oder vorhersehbar ist, können Hash-Werte durch Erraten umgekehrt werden. Erwägen Sie bei sensiblen Kunden- oder Benutzer-IDs das Löschen, Ersatz-IDs, Bucketing, Kürzung oder Keyed Hashing mit strengen Schlüsselkontrollen. Verwenden Sie Hashes in erster Linie für eine stabile Korrelation, wenn das Risiko verstanden wird, und nicht als pauschale Antwort auf den Datenschutz.

Datenschutz im Collector erzwingen

Die OpenTelemetry-Anleitung besagt, dass vertrauliche Daten vor dem Export behandelt werden sollten. Der Collector kann Telemetrieattribute mithilfe von Prozessoren wie Attributen, Filter, Schwärzung und Transformation entfernen, hashen, filtern, redigieren oder transformieren. Das macht den Collector zu einer zweiten Verteidigungslinie nach der Gateway-Instrumentierung selbst.

Eine praktische Collector-Pipeline sollte eine Zulassungsliste für Attribute mit geringem Risiko verwenden, standardmäßig rohe Eingabeaufforderungs- und Antwortfelder löschen, Werte maskieren, die blockierten Mustern entsprechen, und höher sensible Traces separat weiterleiten, wenn die Inhaltserfassung explizit aktiviert ist. Der OpenTelemetry Collector-Attributprozessor unterstützt Aktionen wie Löschen und Hash. Der Schwärzungsprozessor ist darauf ausgelegt, Attribute zu löschen, die nicht auf einer Zulassungsliste stehen, und Werte zu maskieren, die blockierten Mustern entsprechen.

Zum Beispiel kann das Gateway die Ausgabe von Rohinhalten standardmäßig vermeiden, während der Collector dennoch Attribute wie llm.prompt.raw, llm.completion.raw, provider.api_key, authorization und cookie löscht, wenn sie aufgrund eines Fehlers oder einer Bibliotheksintegration erscheinen. Betrachten Sie dies als eine Tiefenverteidigungskontrolle und nicht als einen Grund, unsichere Daten beiläufig herauszugeben.

Instrumentieren Sie Wiederholungsversuche, Fallbacks und Validierung separat

Wiederholungsversuche und Fallbacks sind in aggregierten API Metriken oft unsichtbar. Diese Unsichtbarkeit verursacht zwei betriebliche Probleme. Erstens kann sich die Latenz verschlechtern, da hinter einer erfolgreichen Antwort möglicherweise mehrere fehlgeschlagene Versuche verborgen bleiben.Zweitens können die Kosten steigen, da eine einzelne Benutzeranfrage mehrere Upstream-Modellaufrufe erzeugen kann.

Jede Anbieterversuchsspanne sollte die Versuchsnummer, den Wiederholungsgrund, den ausgewählten Anbieter, das ausgewählte Modell, das Timeout-Budget, die Latenz, die Token-Nutzung, sofern verfügbar, und das Ergebnis enthalten. Wenn ein Fallback auftritt, sollte der Fallback-Span die ursprüngliche Routenrichtlinie, den Fallback-Grund und das tatsächlich für die endgültige Antwort verwendete Modell angeben.

Die strukturierte Ausgabevalidierung sollte ein eigener Span oder ein eigenes Ereignis sein. Erfassen Sie die Schema-ID, die Schemaversion, das Validierungsergebnis, die Anzahl der Reparaturversuche und den Endstatus. Speichern Sie standardmäßig nicht die vollständige ungültige Ausgabe. Ein Validierungsfehler unterscheidet sich operativ von einem Anbietertransportfehler, und Dashboards sollten diese nicht verwischen.

Dashboards rund um Fragen und nicht um Anbieter aufbauen

Anbieterneutrale Beobachtbarkeit sollte Betriebsfragen direkt beantworten. Nützliche Dashboards umfassen die p95- und p99-Latenz nach Modell, Anbieter, Team, Umgebung und Workload-Klasse; Token-Nutzung nach Team und Route; Ausfallrate nach normalisierter Fehlerklasse; Verstärkung durch Routenrichtlinie erneut versuchen; Fallback-Häufigkeit nach angefordertem Modell; Kontextfensterfehler durch Eingabeaufforderungsvorlage; Fehler bei der Validierung strukturierter Ausgaben nach Schema; und stichprobenartige Trace-Beispiele für fehlgeschlagene, teure oder langsame Anfragen.

Halten Sie Abrechnungs- und Gesamtnutzungsberichte von stichprobenartigen Traces fern. Tail Sampling ist zum Debuggen nützlich, kann jedoch die Gesamtergebnisse verzerren. Token-Gesamtsummen, Anforderungszahlen und Kostenbücher sollten aus nicht erfassten Zählern, Anforderungsbüchern oder Abrechnungsabgleichssystemen stammen. Traces sollten erklären, warum eine teure oder langsame Anfrage erfolgt ist. Sie sollten nicht die einzige Quelle finanzieller Wahrheit sein.

Tail Sampling für hochwertige Traces verwenden

Der Tail Sampling-Prozessor von OpenTelemetry Collector kann Sampling-Entscheidungen treffen, nachdem Spans abgeschlossen sind, einschließlich Richtlinien basierend auf Attributen und numerischen Werten. Dies ist für den LLM-Verkehr nützlich, da Sie oft erst nach Abschluss der Antwort wissen, ob eine Ablaufverfolgung wertvoll ist.

Behalten Sie Ablaufverfolgungen für Anbieterfehler, Validierungsfehler, sehr hohe Latenz, ungewöhnlich teure Token-Nutzung, Kontextfensterfehler, Fallback-Versuche und manuell mit Debug-Tags versehene Anforderungen. Probieren Sie routinemäßig erfolgreichen Datenverkehr mit einer niedrigeren Rate aus. Dadurch bleiben die Ablaufverfolgungen am wahrscheinlichsten, um Vorfälle zu erklären, während gleichzeitig das Speichervolumen kontrolliert wird.

Ein vernünftiges Richtlinienmodell ist einfach: Behalten Sie Fehler immer bei, halten Sie Anfragen immer über einem Latenz- oder Token-Schwellenwert, behalten Sie immer mit Debug-Tags versehene Ablaufverfolgungen bei und nehmen Sie probabilistische Stichproben gewöhnlicher erfolgreicher Anfragen. Überprüfen Sie die Schwellenwerte, wenn sich der Verkehr ändert. Ein Schwellenwert, der während der frühen Einführung nützlich ist, kann zu niedrig sein, sobald der Produktionsverkehr zunimmt.

Vertragstests für Telemetrie hinzufügen

Telemetrie sollte wie ein API Vertrag getestet werden, da nachgelagerte Dashboards, Warnungen, Kostenkontrollen und Vorfall-Workflows davon abhängen. Fügen Sie Tests hinzu, die repräsentative Gateway-Anfragen ausführen und bestätigen, dass erforderliche Spans und Attribute ausgegeben werden.

Die Tests sollten überprüfen, ob eine erfolgreiche Anfrage die logische LLM-Operationsspanne, eine Anbieterversuchsspanne, das angeforderte Modell, das Antwortmodell, den Anbieternamen, die Anzahl der Token, sofern verfügbar, Team- oder Schlüsselbereichsmetadaten, die Routenrichtlinienversion und den endgültigen Status ausgibt. Wiederholungstests sollten die Anzahl der Versuche und die Gründe für Wiederholungsversuche ermitteln. Fallback-Tests sollten sowohl den fehlgeschlagenen Versuch als auch den letzten erfolgreichen Versuch des Anbieters bestätigen. Validierungstests sollten die Schema-ID, den Validierungsstatus und die Anzahl der Reparaturversuche bestätigen.

Sicherheitstests sind ebenso wichtig. Stellen Sie sicher, dass rohe Anbieterschlüssel, Autorisierungsheader, Cookies, rohe Eingabeaufforderungen, rohe Vervollständigungen und nicht genehmigte Kundenkennungen in den exportierten Telemetriedaten fehlen.Diese Tests sollten fehlschlagen, wenn ein Entwickler ein neues Span-Attribut hinzufügt, ohne es zu klassifizieren.

Implementierungscheckliste

• Attributvertrag: Definieren Sie erforderliche, optionale, eingeschränkte und verbotene Attribute.
• Span-Hierarchie: Separate eingehende Anforderungen, logische LLM-Vorgänge, Anbieterversuche, Wiederholungsversuche, Fallbacks, Abrufaufrufe, Toolaufrufe und Validierung.
• Semantische Zuordnung: Verwenden Sie OpenTelemetry GenAI-Attribute dort, wo sie passen, und private Gateway-Attribute für Besitz- und Routingkontext.
• Datenschutzrichtlinie: Standardmäßig werden stattdessen Hashes, Vorlagen-IDs, Schema-IDs, Toolnamen, Token-Anzahl, Latenz und Fehlerklassen verwendet von Rohinhalten.
• Sammlerprozessoren: Löschen Sie verbotene Felder, schwärzen Sie blockierte Muster, setzen Sie Attribute mit geringem Risiko auf die Zulassungsliste und leiten Sie sensible Ablaufverfolgungen separat weiter.
• Stichprobenrichtlinie: Führen Sie Stichproben von hochwertigen Ablaufverfolgungen durch und behalten Sie aggregierte Messwerte bei ohne Stichprobe.
• Dashboards: Erstellen Sie Ansichten zu Latenz, Nutzung, Fehlern, Wiederholungsversuchen, Fallbacks, Validierung und Kostentreibern.
• Warnungen: Warnungen zu normalisierten Fehlerklassen, p99-Latenzverschiebungen, Wiederholungsversuchsverstärkung, Fallback-Spitzen, Validierungsfehlern und Token Anomalien.
• Vertragstests: Stellen Sie sicher, dass erforderliche Telemetrie vorhanden ist und sensible Telemetrie nicht vorhanden ist.

Kompromisse zur expliziten Entscheidung

Die Instrumentierung auf Gateway-Ebene liefert schnell konsistente Metadaten, kann jedoch anwendungsspezifischen Kontext übersehen, es sei denn, Teams übergeben strukturierte Anforderungsmetadaten wie Mandant, Workflow, Eingabeaufforderungsvorlage und Funktion Namen. Machen Sie diese Metadaten zu einem Teil des Gateway-Anfragevertrags, anstatt sich auf Protokolle in freier Form zu verlassen.

Die vollständige Inhaltserfassung verbessert die Fehlerbehebung und Auswertung, erhöht jedoch den Datenschutz, die Sicherheit, die Aufbewahrung und den Aufwand für die Zugriffskontrolle. Viele Teams sollten nur mit Hashes, Vorlagen-IDs, Schema-IDs und redigierten Auszügen beginnen.

Anbieterneutrale Fehlerklassen machen Dashboards für mehrere Modell-APIs nutzbar, komprimieren jedoch anbieterspezifische Details. Bewahren Sie rohe Anbieterfehlercodes nur dann auf, wenn sie sicher sind, und beschränken Sie den Zugriff darauf.

OpenTelemetry GenAI-Konventionen reduzieren die Sperrung, aber die Konventionen werden sich weiterentwickeln. Ein interner Mapper bietet Ihnen die Vorteile der Standardisierung, ohne dass instabile Attributnamen durch die Codebasis dringen.

Fazit

Bei der anbieterneutralen LLM-Beobachtbarkeit geht es nicht nur um die zu Modellaufrufen hinzugefügte Ablaufverfolgung. Es handelt sich um einen Betriebsvertrag auf der Gateway-Ebene: konsistente Spans, normalisierte Modell- und Provider-Metadaten, Eigentumskontext, Token-Nutzung, Wiederholungsversuche und Fallback-Sichtbarkeit, Datenschutzkontrollen, Stichprobenregeln und Tests, die verhindern, dass vertrauliche Daten verloren gehen.

Beginnen Sie mit dem Gateway, denn es sieht bereits die Entscheidungen, die am wichtigsten sind: Wer hat die Anfrage gestellt, welche Richtlinie hat sie weitergeleitet, welcher Anbieter hat sie bedient, was hat sie in Token gekostet, wie lange hat es gedauert, ob die Wiederherstellungslogik ausgeführt wurde und was fehlgeschlagen ist. Sobald diese Grundlage stabil ist, können Anwendungsteams einen umfassenderen Workflow-Kontext hinzufügen, ohne dass jedes Team sein eigenes LLM-Beobachtbarkeitssystem entwickeln muss.

Verwandte Lektüre

• Fallback-Routing-Telemetrie