Export von LLM-Gateway-Traces an Traceloop mit OpenTelemetry

TrueFoundry AI Gateway exportiert OpenTelemetry-Traces an Traceloop über OTLP/HTTP mithilfe des https://api.traceloop.com/v1/traces Endpunkts und eines Bearer-Tokens im Authorization Header. Jede LLM-Anfrage, die das Gateway durchläuft, erzeugt einen Span-Baum, der im Traceloop-Dashboard landet, ohne dass Änderungen am Anwendungscode oder an der Bereitstellungstopologie erforderlich sind.

Dieser Beitrag behandelt den Pfad der Trace-Generierung innerhalb des TrueFoundry AI Gateway und wie Traceloop diese Daten aufnimmt und darstellt. Er beschreibt auch die Konfigurationsoberfläche und die Datenschutzfunktionen, die auf Gateway-Ebene verfügbar sind.

Wie das Gateway Traces generiert

Das TrueFoundry AI Gateway basiert auf dem Hono-Framework und läuft als zustandsloser Pod, der über 250 Anfragen pro Sekunde auf einer einzelnen vCPU verarbeitet, mit einer zusätzlichen Latenz von etwa 3 ms pro Anfrage. Das Gateway arbeitet in einer geteilten Architektur, bei der eine Steuerungsebene die Konfiguration verwaltet und ein oder mehrere Gateway-Pods den Inferenz-Traffic verarbeiten.

Wenn eine Anfrage eingeht, führt das Gateway die folgende Sequenz im Hot Path aus:

1. JWT-Token wird gegen in den Speicher zwischengespeicherte öffentliche Schlüssel validiert (einmal vom IdP heruntergeladen und über NATS aktualisiert)
2. Autorisierung wird gegen eine im Speicher befindliche Benutzer-zu-Modell-Zuordnung geprüft, die durch NATS Pub/Sub aktuell gehalten wird
3. Modell-Identifikator wird über die im Speicher laufende Routing-Logik des virtuellen Modells zu einem physischen Anbieter-Endpunkt aufgelöst
4. Anfrage wird über eine Adapterschicht vom OpenAI-kompatiblen Format in das Format des Zielanbieters übersetzt
5. Anfrage wird an den Anbieter weitergeleitet und die Antwort wird zurück an den Client gestreamt

Keiner dieser Schritte führt externe Aufrufe durch, außer dem Anbieteraufruf selbst. Die Ratenbegrenzung verwendet den Sliding-Window-Token-Bucket-Algorithmus basierend auf dem In-Memory-Zustand. Die Guardrail-Evaluierung (sofern konfiguriert) läuft parallel zum Modellaufruf für Eingabeprüfungen und sequenziell für Ausgabeprüfungen.

Nachdem die Anfrage abgeschlossen ist, veröffentlicht das Gateway den Span-Baum asynchron an NATS. Der OTEL-Exporter liest von diesem asynchronen Pfad und leitet Spans an den konfigurierten externen Endpunkt weiter. Da der Exportpfad vollständig vom Anforderungspfad entkoppelt ist, fügt ein langsames oder unerreichbares OTEL-Backend dem Client niemals Latenz hinzu und führt niemals dazu, dass eine Anfrage fehlschlägt. Wenn Traceloop unerreichbar ist, werden Spans am Exporter verworfen und intern protokolliert. Der interne Trace-Speicher von TrueFoundry bleibt unberührt, da der Export additiv ist.

Das Gateway generiert Spans über fünf Stufen hinweg: den eingehenden HTTP-Handler, die Authentifizierung, die Modellauflösung, den ausgehenden Anbieteraufruf und die Zusammenstellung der Streaming-Antwort. Jeder Span trägt einen konsistenten Satz von Attributen.

Die gen_ai.*-Attribute folgen den semantischen Konventionen von OpenTelemetry für generative KI-Systeme. Das bedeutet, dass die in Traceloop ankommenden Trace-Daten strukturell identisch sind mit dem, was jede mit OpenLLMetry instrumentierte Anwendung erzeugen würde.

‍

Was Traceloop mit den Daten macht

Traceloop ist eine LLM-Observability-Plattform, die auf OpenLLMetry basiert, welches seine Open-Source-OpenTelemetry-Instrumentierungsschicht ist. Das Backend von Traceloop akzeptiert OTLP/HTTP-Trace-Daten und indiziert sie für das Traceloop-Dashboard. Die Plattform ist Trace-nativ. Metriken wie Token-Nutzung, Latenz und Kosten werden aus Span-Attributen berechnet, anstatt aus einem separaten OTLP-Metrik-Stream. Deshalb ist es ausreichend, nur den Traces Exporter in TrueFoundry zu konfigurieren – es gibt keinen /v1/metrics Endpunkt in der Ingestions-Oberfläche von Traceloop.

Traceloop organisiert Daten um drei Kernabstraktionen herum. Traces sind die oberste Einheit und entsprechen direkt einer LLM-Anfrage oder einem agentenbasierten Workflow. Spans innerhalb eines Trace stellen einzelne Operationen dar (einen LLM-Aufruf, einen Tool-Aufruf und einen Abrufschritt). Umgebungen werden Bereitstellungsphasen zugeordnet, und jede Umgebung hat ihren eigenen API-Schlüssel, wodurch Entwicklungs-, Staging- und Produktions-Traces im Dashboard isoliert bleiben.

Das Traceloop Dashboard zeigt Token-Nutzung im Zeitverlauf, Latenzverteilungen, Fehlerraten und Modellaufschlüsselungen direkt von GenAI.* Span-Attribute. Da TrueFoundry diese Attribute für jeden Span befüllt, wird das Traceloop-Dashboard vollständig befüllt, ohne dass eine SDK-Instrumentierung auf der Anwendungsebene erforderlich ist.

‍
‍

Traceloop unterstützt auch Prompt-Versionierung und Regressionstest-Pipelines, diese Funktionen arbeiten jedoch auf der Ebene des Anwendungs-SDKs und liegen außerhalb des Umfangs dieser Integration. Die Gateway-Integration deckt die gesamte Beobachtbarkeitsoberfläche ab: Jede Anfrage, die TrueFoundry durchläuft, erzeugt einen Trace in Traceloop, unabhängig davon, welcher LLM-Anbieter oder welches Modell aufgerufen wird.

Die Integrationsschnittstelle

Die Verbindung zwischen TrueFoundry und Traceloop ist ein einzelner OTLP/HTTP-POST an https://api.traceloop.com/v1/traces der Proto-kodierte Span-Batches enthält. Die Authentifizierung erfolgt über einen Bearer-Token im Authorization Header. Der Token ist ein Traceloop API-Schlüssel, der auf eine bestimmte Umgebung beschränkt ist.

TrueFoundry stellt diese Konfiguration unter AI Gateway → Controls → Settings → OTEL Configzur Verfügung. Die Sektion Otel Traces Exporter akzeptiert die folgenden Felder.

Der Endpunkt muss den vollständigen /v1/traces Pfad enthalten. Der Exporter von TrueFoundry hängt Signalpfade nicht automatisch an. Dies unterscheidet sich vom OTel Collector otlphttp Exporter, der den Pfad automatisch von der Basis-URL anhängt. Beide lösen zur gleichen Zieladresse auf.

Traceloop API-Schlüssel werden pro Umgebung auf der Seite „Umgebungen“ im Traceloop-Dashboard generiert. Ein Schlüssel wird nur einmal bei der Erstellung angezeigt. Der Schlüsselwert wird im Header übergeben als Bearer <key> einschließlich des Bearer Präfixes als Literalzeichenfolge.

Datenschutz-Kontrollen

Das Gateway bietet einen Anfragedaten ausschließen Umschalter im Abschnitt „OTEL-Konfiguration“. Wenn aktiviert, entfernt der Exporter tfy.input und tfy.output und tfy.input_short_hand aus jedem Span, bevor er an Traceloop weitergeleitet wird. Die verbleibenden Span-Attribute (Token-Anzahlen, Modellnamen, Latenz- und Routing-Metadaten) bleiben unberührt. Dieser Umschalter ist geeignet, wenn Prompts oder Completions personenbezogene Daten (PII) des Benutzers oder proprietäre Inhalte enthalten, die die Clustergrenze nicht verlassen sollten.

Das Zusätzliche Ressourcenattribute Feld ermöglicht das Anhängen benutzerdefinierter Schlüssel-Wert-Paare an jeden exportierten Span. Dies ist nützlich für die Umgebungs-Tagging, die Zuordnung zu Kostenstellen und die mandantenfähige Filterung innerhalb einer einzigen Traceloop-Umgebung.

‍

Architekturübersicht

Jede LLM-Anfrage über TrueFoundry AI Gateway erzeugt einen Span-Baum, der Authentifizierung und Routing sowie den Provider-Aufruf und die Antwort abdeckt. Nach Abschluss der Anfrage veröffentlicht das Gateway diesen Span-Baum asynchron an NATS. Der OTEL-Exporter liest von NATS und sendet Proto-kodierte Batches per POST an https://api.traceloop.com/v1/traces mit einem Bearer-Token. Traceloop indiziert die Spans und stellt die Token-Nutzung, Latenz und Modellaufschlüsselungen in seinem Dashboard bereit, basierend auf den gen_ai.* Attributen auf jedem Span.

Es sind keine Sidecars erforderlich. Es sind keine Änderungen am Anwendungscode erforderlich. Es muss kein OpenLLMetry SDK zu Diensten hinzugefügt werden, die das Gateway aufrufen. Die Integration erfolgt vollständig auf der Gateway-Ebene und deckt 100 % des darüberlaufenden Datenverkehrs ab, unabhängig vom Instrumentierungsstatus der aufrufenden Anwendung.

Die architektonische Eigenschaft, die dies so sauber macht, ist die asynchrone NATS-Veröffentlichung. Da der Span-Export vom Anforderungspfad entkoppelt ist, fügt die Integration Inferenzaufrufen keine Latenz hinzu und schafft keine Verfügbarkeitsabhängigkeit von Traceloop. Das Gateway verarbeitet Anfragen mit voller Leistung, unabhängig davon, ob Traceloop erreichbar ist.

‍