TrueFoundry AI Gateway traces exporteren naar OpenLIT via OTLP

De TrueFoundry AI Gateway genereert OpenTelemetry-spans voor elk LLM-verzoek en publiceert deze asynchroon via NATS. OpenLIT is een zelf-gehost observability-platform dat OTLP-traces en -metrics accepteert via HTTP of gRPC en deze opslaat in ClickHouse. Het verbinden van de twee vereist het configureren van de OTEL-exporter van de gateway om te verwijzen naar het OpenLIT collector-eindpunt. Er zijn geen codewijzigingen vereist in applicaties.

Dit artikel behandelt het pad voor de generatie van OTEL-traces binnen de TrueFoundry AI Gateway, het ClickHouse-opslagmodel dat OpenLIT gebruikt en het configuratieoppervlak om de twee systemen met elkaar te verbinden. Het is geen stapsgewijze installatiegids. Het is een uitleg van hoe de integratie werkt op architectuurniveau.

Hoe de TrueFoundry AI Gateway traces genereert en meestuurt

De TrueFoundry AI Gateway is gebouwd op het Hono-framework en draait als een stateless pod. Eén enkele pod op 1 vCPU en 1 GB RAM verwerkt meer dan 250 verzoeken per seconde met ongeveer 3 ms aan toegevoegde latentie. Dat prestatieprofiel is alleen mogelijk omdat de gateway nul externe aanroepen uitvoert in het verzoekpad. Authenticatie draait op gecachte openbare sleutels. Autorisatiecontroles draaien op een in-memory map van gebruikers naar modellen. Modeldynamiek en routinglogica draaien volledig in het geheugen.

De generatie van OTEL-traces volgt hetzelfde principe. Wanneer een verzoek is voltooid, publiceert de gateway de span-data asynchroon naar NATS. De OTEL-exporter leest uit dit asynchrone pad en stuurt de span door naar het geconfigureerde externe eindpunt. De exporter komt nooit in het verzoekpad. Een trage of onbereikbare OTEL-backend zal een verzoek dus nooit vertragen.

De spans die de gateway uitzendt, bevatten een specifieke set attributen. Het tfy.input-attribuut bevat de volledige request body die naar het LLM is gestuurd. Het tfy.output-attribuut bevat de volledige respons. Het tfy.input_short_hand-attribuut bevat een verkorte samenvatting van de invoer, inclusief boolean-vlaggen die aangeven of het verzoek bestanden, afbeeldingen of audio bevatte. Het tfy.span_type-attribuut identificeert het type bewerking, zoals ChatCompletion of AgentResponse. Standaard gen_ai.* semantische conventies zijn eveneens inbegrepen en dekken tokenaantallen, modelidentificaties en finish reasons.

De gateway biedt ook een schakelaar voor Exclude Request Data. Wanneer deze is ingeschakeld, verwijdert de exporter tfy.input, tfy.output en tfy.input_short_hand uit spans voordat ze worden doorgestuurd. Dit is van belang voor teams die telemetrie naar een extern platform moeten routeren zonder prompt- of responsinhoud buiten hun infrastructuur te sturen.

Export is additief. Het inschakelen van een externe OTEL-bestemming vervangt of onderbreekt de eigen interne trace-opslag van TrueFoundry niet. Beide paden ontvangen dezelfde spans.

Wat OpenLIT doet met de traces

OpenLIT is een OpenTelemetry-native observability-platform. Het vereist geen sidecar, SDK-wrapper of enige aanpassing aan de applicatielaag. Het accepteert spans via het standaard OTLP-protocol op poort 4318 voor HTTP en poort 4317 voor gRPC en schrijft deze naar ClickHouse.

ClickHouse slaat traces op in de tabel otel_traces en metrics in de tabel otel_metrics. Het schema volgt direct het OpenTelemetry-datamodel. Elke span wordt opgeslagen als een rij met een kolom SpanAttributes van het type Map(String, String) die alle key-value attributen bevat die de gateway heeft uitgezonden. Het opvragen van een specifiek attribuut maakt gebruik van de map accessor-syntaxis:

Het OpenLIT-dashboard leest uit deze ClickHouse-tabellen en rendert verzoek-timelines, latentieverdelingen en foutpercentages. Omdat de opslaglaag een standaard ClickHouse-instantie is, kunnen teams hier ook rechtstreeks willekeurige SQL op uitvoeren voor aangepaste rapportages of waarschuwingspipelines.

OpenLIT levert zijn eigen OTel Collector mee samen met het dashboard en de database. De collector is het toegangspunt voor alle inkomende spans en metrics. Deze ontvangt gegevens via OTLP en schrijft ze naar ClickHouse met behulp van de ClickHouse-exporter. De collectorconfiguratie definieert afzonderlijke pipelines voor traces, metrics en logs, elk ondersteund door een batch processor en een memory limiter.

De drie componenten worden geleverd als één enkele Helm chart. De collector en het dashboard draaien in dezelfde Kubernetes pod. ClickHouse draait als een afzonderlijke StatefulSet met een persistent volume claim. Een init container in de OpenLIT-pod wacht tot ClickHouse reageert op poort 8123 voordat de collector- en dashboardprocessen worden gestart. Deze volgorde zorgt ervoor dat de Helm-release zelfstandig is en de uitrolvolgorde automatisch wordt afgehandeld.

Eenmaal uitgerold toont TrueFoundry beide pods in een Running-status: openlit-0 waarin het dashboard en de OTel Collector draaien, en openlit-db-0 waarin ClickHouse draait.

Het OpenLIT-dashboard is toegankelijk via de geconfigureerde clusterdomein-URL. De inlogpagina toont de kernfuncties van het platform, waaronder end-to-end tracing, kosten- en tokenanalyses en LLM-as-a-Judge-evaluatie.

Het integratieoppervlak

De TrueFoundry AI Gateway maakt verbinding met OpenLIT via twee OTEL-exporterconfiguraties: één voor traces en één voor metrics. Beide maken gebruik van HTTP en Proto-codering. Er zijn geen authenticatie-headers vereist omdat het OpenLIT collector-eindpunt zich in hetzelfde Kubernetes-cluster bevindt als de gateway. Verkeer tussen de twee blijft op het interne clusternetwerk.

OTEL Traces Exporter Configuratie

OTEL Metrics Exporter Configuratie

‍

De openlit Kubernetes service stelt drie poorten beschikbaar. Poort 3000 dient voor het dashboard. Poort 4317 accepteert OTLP via gRPC. Poort 4318 accepteert OTLP via HTTP. Alle drie bevinden ze zich onder dezelfde servicenaam en DNS-ingang. Het op NATS gebaseerde asynchrone exportpad in de gateway zorgt ervoor dat zelfs als de OpenLIT collector tijdelijk niet beschikbaar is, de gateway verzoeken normaal blijft verwerken. Spans die niet kunnen worden afgeleverd, worden op exporter-niveau genegeerd en gelogd zonder dat er fouten naar de aanroeper worden getoond.

De OpenLIT Helm chart wordt gehost op https://openlit.github.io/helm/ onder de chartnaam openlit. De chart accepteert een waardenblok dat de ClickHouse-verbindingsparameters instelt voor het dashboard en de collector, evenals de persistence-configuratie voor de database. Het dashboard maakt verbinding met ClickHouse via de INIT_DB_HOST omgevingsvariabele, die moet verwijzen naar de ClickHouse StatefulSet-service met behulp van de interne DNS-naam openlit-db.NAMESPACE.svc.cluster.local.

De collectorconfiguratie is opgeslagen in een ConfigMap genaamd openlit-otel-config. Het definieert drie pipelines. De traces-pipeline draait via een memory limiter die is ingesteld op 1500 MiB met een pieklimiet van 512 MiB en een batch processor voordat deze doorstuurt naar de ClickHouse-exporter. De metrics-pipeline volgt dezelfde processor-keten. De logs-pipeline slaat de memory limiter over en gebruikt alleen de batch processor. Alle drie de pipelines schrijven naar dezelfde ClickHouse-instantie via het systeemeigen TCP-protocol op poort 9000.

De VirtualService voor het dashboard gebruikt de TrueFoundry Istio gateway istio-system/tfy-wildcard en routeert verkeer van het clusterdomein naar de interne openlit service op poort 3000. Dit is het enige onderdeel dat externe blootstelling vereist. De collector-eindpunten blijven intern.

Referentie interne DNS-services

Architectuuroverzicht

Een verzoek komt binnen in de TrueFoundry AI Gateway en wordt volledig in het geheugen verwerkt op basis van gecachte authenticatiestatus en routingconfiguratie. De gateway stuur het verzoek door naar de LLM-provider en streamt de respons terug naar de client. Nadat de respons is voltooid, publiceert de gateway een span naar NATS met daarin de volledige verzoek- en responsattributen, tokenaantallen en latentie. De OTEL-exporter haalt de span asynchroon op uit NATS en stuurt deze via OTLP/HTTP naar de OpenLIT collector die draait op poort 4318 binnen het cluster. De collector schrijft de span naar ClickHouse. Het OpenLIT-dashboard leest uit ClickHouse en maakt de trace beschikbaar voor inspectie.

Het tabblad Metrics toont geaggregeerde tijdreeksgegevens uit de tabel otel_metrics. Trends in verzoekvolumes en latentie van de gateway zijn beschikbaar over selecteerbare tijdsperioden van 24 uur tot 3 maanden.

Er zijn geen sidecars nodig. Er zijn geen SDK-wijzigingen vereist. Er wordt geen instrumentatiecode toegevoegd aan applicaties. De enige configuratiewijziging is het instellen van de OTEL-exporter-eindpunten in de instellingen van de TrueFoundry AI Gateway. De gateway genereert en publiceert de spans al. De exporterconfiguratie bepaalt alleen waar ze naartoe gaan.

Het architectonische principe dat deze integratie mogelijk maakt, is de scheiding tussen het verzoekpad en het telemetriepad. Omdat spans naar NATS worden gepubliceerd nadat de respons is voltooid, heeft de betrouwbaarheid van de observability-backend geen invloed op de latentie of beschikbaarheid van de gateway. OpenLIT ontvangt wat de gateway publiceert. Als OpenLIT niet beschikbaar is, blijft de gateway werken en wordt het exporteren hervat wanneer de verbinding is hersteld.

‍