Exportieren von TrueFoundry AI Gateway Traces nach SigNoz über OTLP

Das TrueFoundry AI Gateway generiert OpenTelemetry Spans für jede LLM-Anfrage und veröffentlicht diese asynchron über NATS. SigNoz Cloud akzeptiert diese Spans über OTLP/HTTP an einem regionalen Ingestion-Endpunkt, der über einen pro Arbeitsbereich vergebenen Ingestion-Schlüssel authentifiziert wird. Um die beiden zu verbinden, muss der OTEL-Exporter des Gateways mit der SigNoz Ingestion-URL konfiguriert und der signoz-ingestion-key Header hinzugefügt werden. Es sind keine Änderungen an der Instrumentierung auf Anwendungsebene erforderlich.

Dieser Beitrag behandelt den Pfad zur OTEL-Trace-Generierung innerhalb des TrueFoundry AI Gateways sowie die Ingestions- und Speicherpipeline, die SigNoz Cloud verwendet, und die Konfigurationsoberfläche, um die beiden Systeme miteinander zu verbinden. Es ist keine Einrichtungsanleitung, sondern eine Erklärung, wie die Integration auf Architekturebene funktioniert.

Wie das TrueFoundry AI Gateway Traces generiert und exportiert

Das TrueFoundry AI Gateway basiert auf dem Hono-Framework und läuft als zustandsloser Pod. Ein einzelner Pod mit 1 vCPU und 1 GB RAM verarbeitet über 250 Anfragen pro Sekunde mit einer zusätzlichen Latenz von etwa 3 ms. Dieser Durchsatz ist möglich, da das Gateway im Anforderungspfad keine externen Aufrufe tätigt. Die Authentifizierung erfolgt anhand von zwischengespeicherten öffentlichen Schlüsseln, die einmal vom Identitätsanbieter heruntergeladen wurden. Autorisierungsprüfungen erfolgen anhand einer In-Memory-Map von Benutzern zu Modellen, die über NATS synchronisiert werden. Die Modell-Routing-Logik läuft vollständig im Speicher anhand einer lokalen Kopie der Routing-Konfiguration.

Die OTEL-Trace-Generierung folgt demselben Prinzip der null externen Aufrufe. Wenn eine Anfrage abgeschlossen ist, veröffentlicht das Gateway die Span-Daten asynchron an NATS. Der OTEL-Exporter liest von diesem asynchronen Pfad und leitet den Span an den konfigurierten externen Endpunkt weiter. Der Exporter berührt niemals den Anforderungspfad. Ein langsames oder unerreichbares OTEL-Backend blockiert niemals eine Anfrage und fügt niemals eine für den Client sichtbare Latenz hinzu.

Das Gateway generiert Spans an mehreren Punkten im Lebenszyklus der Anfrage. Die eingehende HTTP-Verarbeitung, Authentifizierung, Modellauflösung und der ausgehende Provider-Aufruf erzeugen jeweils Spans, die zu einem Trace zusammengefügt werden. Die Spans tragen einen spezifischen Satz von Attributen. Das tfy.input Attribut enthält den vollständigen Anfragetext, der an das LLM gesendet wurde. Das tfy.output Attribut enthält den vollständigen Antworttext. Das tfy.input_short_hand Attribut enthält eine zusammengefasste Übersicht der Eingabe mit booleschen Flags für Datei-, Bild- und Audioinhalte. Das tfy.span_type Attribut identifiziert den Operationstyp als ChatCompletion oder AgentResponse oder MCPGateway, je nachdem, welcher Gateway-Pfad die Anfrage verarbeitet hat. Standard- gen_ai.* semantische Konventionen sind ebenfalls enthalten, die Prompt-Token-Anzahlen, Completion-Token-Anzahlen, Modell-Identifikatoren und Abschlussgründe abdecken.

Das Gateway bietet auch einen Anfragedaten ausschließen Umschalter in der OTEL-Konfiguration. Wenn aktiviert, entfernt der Exporter tfy.input und tfy.output und tfy.input_short_hand aus Spans, bevor sie weitergeleitet werden. Dies ist die korrekte Einstellung für Teams, die volle Trace-Sichtbarkeit für Latenz- und Fehleranalysen benötigen, aber keine Prompt- oder Antwortinhalte an eine externe Plattform übermitteln dürfen.

Der Export ist additiv. Das Aktivieren eines SigNoz OTEL-Ziels ersetzt oder unterbricht TrueFoundrys eigenen internen Trace-Speicher nicht. Beide Pfade erhalten dieselben Spans vom selben asynchronen NATS-Publish.

Was SigNoz mit den Traces macht

SigNoz basiert auf einem benutzerdefinierten OpenTelemetry Collector, der Telemetriedaten akzeptiert und in ClickHouse schreibt. Der Collector ist so konfiguriert, dass er Daten über Standard-OTLP-Protokolle aufnimmt, bietet Protokollübersetzung für eine nahtlose Integration mit bestehenden Überwachungstools und verarbeitet Daten mit Metadatenanreicherung, bevor sie in den Speicher geschrieben werden.

Die Ingestions-Pipeline folgt der OpenTelemetry Collector-Architektur mit Receivern, Prozessoren und Exportern. Der OTLP-Receiver akzeptiert Trace-Spans sowohl über gRPC auf Port 4317 als auch über HTTP auf Port 4318. Ein Batch-Prozessor gruppiert Spans zur Effizienzsteigerung vor dem Export. Der signozspanmetrics Prozessor generiert RED-Metriken (Rate, Fehler und Dauer) direkt aus Spannen-Daten, sodass Anfragerate, Fehlerrate und Latenz-Perzentile als abfragbare Metriken ohne separate Instrumentierung verfügbar sind. Trace-Spannen werden in die distributed_signoz_index_v3 Tabelle in ClickHouse geschrieben. Generierte Metriken fließen in die signoz_metrics.distributed_samples_v4 Tabelle.

SigNoz Cloud verwendet eine mandantenfähige Architektur. Jeder Mandant erhält eine eigene SigNoz-Instanz und ein eigenes ClickHouse zur Speicherung von Telemetriedaten sowie einen eigenen OTel-Collector für die Erfassung und einen eigenen regionalen Endpunkt. Eine gemeinsame Infrastruktur übernimmt die anfängliche Erfassung: Ein OpenTelemetry-Gateway empfängt Telemetriedaten, bündelt sie und leitet sie an einen Redpanda-Streaming-Puffer weiter, bevor die mandantenbezogene SigNoz-Instanz sie konsumiert und in ClickHouse schreibt. Das bedeutet, dass der ingest.<region>.signoz.cloud:443 Endpunkt eine gemeinsame Erfassungsschicht ist. Der signoz-ingestion-key Header die Daten nach der Erfassung an die korrekte mandantenbezogene Pipeline weiterleitet.

Der SigNoz-Abfragedienst liest aus ClickHouse unter Verwendung optimierter SQL-Abfragen, die das spaltenbasierte Speicherformat für die Aggregation großer Mengen von Spannen-Daten nutzen. Der Traces-Explorer zeigt einzelne Spannen an, die nach Dienstname, Operation, Status und Dauer filterbar sind, wie unten dargestellt.

‍

Der Metriken-Explorer akzeptiert PromQL-kompatible Abfragen für die generierten RED-Metriken. Da das Gateway standardmäßige gen_ai.*-Attribute neben tfy.*-Attributen kann SigNoz sowohl generische HTTP-Leistungsdaten als auch LLM-spezifische Daten in derselben Trace-Ansicht anzeigen.

Die Integrationsoberfläche

Die TrueFoundry AI Gateway verbindet sich mit SigNoz über zwei OTEL-Exporter-Konfigurationen: eine für Traces und eine für Metriken. Beide verwenden HTTP- und Proto-Kodierung. Der signoz-ingestion-key Header ist bei beiden Exportern erforderlich. Das Endpunktformat enthält die Region als Subdomain und stellt eine Verbindung über Port 443 via HTTPS her. Die Konfiguration ist zugänglich unter AI Gateway → Controls → Settings → OTEL Config im TrueFoundry-Dashboard, wie unten gezeigt.

‍

OTEL-Traces-Exporter-Konfiguration

OTEL-Metriken-Exporter-Konfiguration

Die Region wird von der SigNoz Cloud Ingestion URL abgeleitet, die in den Kontoeinstellungen sichtbar ist. Für eine Ingestion URL von https://ingest.in2.signoz.cloud ist die Region in2 und der Traces-Endpunkt wird zu https://ingest.in2.signoz.cloud:443/v1/traces. Der Ingestion Key ist ein arbeitsbereichsbezogenes Zugangsdatum, das unter Settings → Ingestion Settings im SigNoz Cloud Dashboard verfügbar ist.

Im Gegensatz zu selbst gehosteten Observability-Zielen, bei denen der Datenverkehr innerhalb des Clusters über unverschlüsseltes HTTP verbleibt, ist SigNoz Cloud ein externer Endpunkt, der über das öffentliche Internet erreichbar ist. Der Gateway-Exporter stellt eine TLS-Verbindung zu Port 443 her und sendet Spans in protobuf-kodierten OTLP/HTTP-Batches. Der NATS-basierte asynchrone Exportpfad im Gateway bedeutet, dass das Gateway die Anfragen normal weiterverarbeitet, selbst wenn der SigNoz-Ingestion-Endpunkt vorübergehend nicht erreichbar ist. Spans, die nicht zugestellt werden können, werden auf Exporter-Ebene verworfen und protokolliert, ohne dass Fehler an den Aufrufer gemeldet werden.

Beide Exporter können unabhängig voneinander aktiviert werden. Das Aktivieren nur des Traces-Exporters sendet Span-Daten an SigNoz, während der Metrik-Export deaktiviert bleibt. Das Aktivieren beider sendet Span-Daten an den distributed_signoz_index_v3 Tabellen- und Metrikdaten an die signoz_metrics.distributed_samples_v4 Tabelle, aus der SigNoz die RED-Metrikansichten im Metrik-Explorer generiert.

Filtern nach Dienst in SigNoz

Das Gateway setzt service.name auf tfy-llm-gateway für alle Spans als Ressourcenattribut. Im SigNoz Traces Explorer isoliert das Filtern nach service.name = tfy-llm-gateway den gesamten Gateway-Verkehr. Das Filtern nach tfy.span_type = ChatCompletion grenzt die Ergebnisse weiter auf LLM-Inferenzanfragen ein. Das tfy.data_routing.destination Attribut identifiziert, welches Modell oder virtuelle Modell die Anfrage bearbeitet hat, und kann verwendet werden, um Latenzverteilungen nach Modell zu gruppieren.

Architekturübersicht

Eine Anfrage gelangt in das TrueFoundry AI Gateway und wird vollständig im Speicher verarbeitet. Das Gateway leitet die Anfrage an den LLM-Anbieter weiter und streamt die Antwort zurück an den Client. Nachdem die Antwort abgeschlossen ist, veröffentlicht das Gateway einen Span an NATS, der die vollständigen Anfrage- und Antwortattribute sowie Token-Zählungen und Latenz enthält. Der OTEL-Exporter nimmt den Span asynchron von NATS auf und leitet ihn über OTLP/HTTP mit dem signoz-ingestion-key Header an den regionalen SigNoz-Ingestion-Endpunkt an Port 443. Das gemeinsam genutzte SigNoz OTel Gateway empfängt den Span und bündelt ihn in Redpanda. Der mandantenbezogene SigNoz Kollektor konsumiert von Redpanda und wendet den signozspanmetrics Prozessor an, um RED-Metriken zu generieren, und schreibt dann Spans in distributed_signoz_index_v3 und Metriken in signoz_metrics.distributed_samples_v4 in der mandantenbezogenen ClickHouse-Instanz. Der SigNoz-Abfragedienst liest aus ClickHouse und zeigt den Trace im Traces Explorer und die generierten Metriken im Metrics Explorer an.

Es sind keine Sidecars erforderlich. Es sind keine SDK-Änderungen erforderlich. Es wird kein Instrumentierungscode zu Anwendungen hinzugefügt. Die einzige Konfigurationsänderung besteht darin, zwei OTEL-Exporter-Endpunkte in den OTEL-Konfigurationseinstellungen des TrueFoundry AI Gateways hinzuzufügen. Das Gateway generiert und veröffentlicht die Spans bereits. Die Exporter-Konfiguration und der Ingestion-Schlüssel bestimmen, wohin sie gehen.

Das architektonische Prinzip, das diese Integration ermöglicht, ist die vollständige Trennung zwischen dem Anforderungspfad und dem Telemetrie-Exportpfad. Das Gateway veröffentlicht Telemetriedaten an NATS, nachdem die Antwort bereits übermittelt wurde. Der SigNoz Ingestion-Endpunkt kann langsam oder vorübergehend nicht verfügbar oder geografisch weit entfernt sein, ohne die Latenz oder Zuverlässigkeit des Gateways zu beeinträchtigen. OTEL-Portabilität bedeutet, dass dieselben Span-Daten, die heute an SigNoz fließen, an jedes andere OTLP-kompatible Backend fließen können, ohne die Gateway-Konfiguration über die Endpunkt-URL und den Authentifizierungs-Header hinaus zu ändern.

‍