TrueFoundry AI Gateway Traces Exporteren naar SigNoz via OTLP

De TrueFoundry AI Gateway genereert OpenTelemetry spans voor elke LLM-request en publiceert deze asynchroon via NATS. SigNoz Cloud accepteert deze spans over OTLP/HTTP bij een regionaal ingestion endpoint, geauthenticeerd via een ingestion key per workspace. Het verbinden van beide vereist het configureren van de OTEL exporter van de gateway met de SigNoz ingestion URL en het toevoegen van de signoz-ingestion-key header. Er zijn geen instrumentatie-wijzigingen op applicatieniveau vereist.

Dit artikel behandelt het OTEL trace-generatiepad binnen de TrueFoundry AI Gateway, de ingestion- en opslagpipeline die SigNoz Cloud gebruikt, en het configuratie-oppervlak om de twee systemen aan elkaar te koppelen. Het is geen handleiding voor de installatie. Het is een uitleg van hoe de integratie werkt op architectuurniveau.

Hoe de TrueFoundry AI Gateway Traces Genereert en Exporteert

De TrueFoundry AI Gateway is gebouwd op het Hono-framework en draait als een stateless pod. Een enkele pod op 1 vCPU en 1 GB RAM verwerkt meer dan 250 requests per seconde met ongeveer 3 ms aan toegevoegde latency. Die doorvoer is mogelijk omdat de gateway nul externe calls maakt in het request-pad. Authenticatie draait tegen gecachte public keys die eenmalig worden gedownload van de identity provider. Authorisatie-checks draaien tegen een in-memory map van gebruikers naar modellen, gesynchroniseerd via NATS. Model-routinglogica draait volledig in het geheugen tegen een lokale kopie van de routing-configuratie.

OTEL trace-generatie volgt hetzelfde principe van nul externe calls. Wanneer een request 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 gecodeerde externe endpoint. De exporter raakt het request-pad nooit aan. Een trage of onbereikbare OTEL backend vertraagt een request nooit en voegt nooit latency toe die zichtbaar is voor de client.

De gateway genereert spans op verschillende punten in de request-levenscyclus. Inkomende HTTP-afhandeling, authenticatie, model-resolutie en de uitgaande provider-call produceren elk spans die worden samengevoegd tot een trace. De spans dragen een specifieke set attributen. Het attribuut tfy.input bevat de volledige request body die naar de LLM is verzonden. Het attribuut tfy.output bevat de volledige response body. Het attribuut tfy.input_short_hand bevat een beknopte samenvatting van de invoer met boolean flags voor bestand-, afbeelding- en audiocontent. Het attribuut tfy.span_type identificeert het operatietype als ChatCompletion, AgentResponse of MCPGateway, afhankelijk van welk gateway-pad het request heeft verwerkt. Standaard gen_ai.* semantische conventies zijn eveneens inbegrepen en dekken aantallen prompt tokens, aantallen completion tokens, model-identifiers en finish reasons.

De gateway biedt ook een schakelaar Exclude Request Data in de OTEL-configuratie. Wanneer ingeschakeld, verwijdert de exporter tfy.input, tfy.output en tfy.input_short_hand uit spans voordat ze worden doorgestuurd. Dit is de juiste instelling voor teams die volledige trace-zichtbaarheid nodig hebben voor latency- en foutanalyses, maar geen prompt- of response-inhoud mogen verzenden naar een extern platform.

Export is additief. Het inschakelen van een SigNoz OTEL-bestemming vervangt of onderbreekt TrueFoundry's eigen interne trace-opslag niet. Beide paden ontvangen dezelfde spans van dezelfde asynchrone NATS-publicatie.

Wat SigNoz Doet met de Traces

SigNoz is gebouwd rond een op maat gemaakte OpenTelemetry Collector die telemetriedata accepteert en naar ClickHouse schrijft. De collector is geconfigureerd om data te verwerken via standaard OTLP-protocollen, biedt protocolvertaling voor naadloze integratie met bestaande monitoringtools en verwerkt data met metadata-verrijking voordat deze naar de opslag wordt geschreven.

De ingestion-pipeline volgt de OpenTelemetry Collector-architectuur met receivers, processors en exporters. De OTLP-receiver accepteert trace spans via zowel gRPC op poort 4317 als HTTP op poort 4318. Een batch processor groepeert spans voor efficiëntie vóór de export. De signozspanmetrics processor genereert RED-metrics (Rate, Error en Duration) rechtstreeks uit span-data, zodat request rate, error rate en latency-percentielen beschikbaar zijn als opvraagbare metrics zonder afzonderlijke instrumentatie. Trace spans worden geschreven naar de tabel distributed_signoz_index_v3 in ClickHouse. Gegenereerde metrics stromen naar de tabel signoz_metrics.distributed_samples_v4.

SigNoz Cloud gebruikt een architectuur per tenant. Elke tenant krijgt zijn eigen SigNoz-instantie, zijn eigen ClickHouse voor de opslag van telemetriedata, zijn eigen OTel collector voor ingestion en zijn eigen regionale endpoint. Gedeelde infrastructuur verzorgt de initiële ingestion: een OpenTelemetry gateway ontvangt telemetrie, batcht deze en stuurt deze door naar een Redpanda streaming-buffer voordat de SigNoz-instantie per tenant deze verbruikt en naar ClickHouse schrijft. Dit betekent dat het endpoint ingest.<region>.signoz.cloud:443 een gedeelde ingestion-laag is. De header signoz-ingestion-key routeert de data na ingestion naar de juiste pipeline per tenant.

De SigNoz query service leest uit ClickHouse met behulp van geoptimaliseerde SQL-queries die het kolomgerichte opslagformaat benutten voor aggregatie over grote volumes span-data. De Traces explorer toont individuele spans die gefilterd kunnen worden op service name, operation, status en duration, zoals hieronder weergegeven.

‍

De Metrics explorer accepteert PromQL-compatibele queries tegen de gegenereerde RED-metrics. Omdat de gateway standaard gen_ai.* attributen naast tfy.* attributen uitzendt, kan SigNoz zowel generieke HTTP-prestatiedata als LLM-specifieke data in dezelfde trace-weergave tonen.

Het Integratie-oppervlak

De TrueFoundry AI Gateway verbindt met SigNoz via twee OTEL exporter-configuraties: één voor traces en één voor metrics. Beide gebruiken HTTP en Proto-encoding. De header signoz-ingestion-key is vereist op beide exporters. Het endpoint-formaat bevat de regio als subdomein en maakt verbinding op poort 443 via HTTPS. De configuratie is toegankelijk onder AI Gateway → Controls → Settings → OTEL Config in het TrueFoundry dashboard, zoals hieronder weergegeven.

‍

OTEL Traces Exporter Configuratie

OTEL Metrics Exporter Configuratie

De regio is afgeleid van de SigNoz Cloud ingestion URL die zichtbaar is in de accountinstellingen. Voor een ingestion URL van https://ingest.in2.signoz.cloud is de regio in2 en wordt het traces-endpoint https://ingest.in2.signoz.cloud:443/v1/traces. De ingestion key is een authenticatiegegeven op workspace-niveau, beschikbaar onder Settings → Ingestion Settings in het SigNoz Cloud dashboard.

In tegenstelling tot self-hosted observability-doelen waar het verkeer binnen het cluster blijft via plain HTTP, is SigNoz Cloud een extern endpoint dat bereikbaar is via het openbare internet. De gateway exporter zet een TLS-verbinding op naar poort 443 en verzendt spans in protobuf-gecodeerde OTLP/HTTP-batches. Het op NATS gebaseerde asynchrone exportpad in de gateway betekent dat zelfs als het SigNoz ingestion endpoint tijdelijk onbereikbaar is, de gateway requests normaal blijft verwerken. Spans die niet kunnen worden afgeleverd, worden op exporter-niveau gedropt en gelogd zonder fouten aan de aanroeper te tonen.

Beide exporters kunnen onafhankelijk worden ingeschakeld. Het inschakelen van alleen de traces exporter stuurt span-data naar SigNoz, terwijl de metrics-export uitgeschakeld blijft. Het inschakelen van beide stuurt span-data naar de tabel distributed_signoz_index_v3 en metric-data naar de tabel signoz_metrics.distributed_samples_v4, van waaruit SigNoz de RED-metric-weergaven in de Metrics explorer genereert.

Filteren op Service in SigNoz

De gateway stelt service.name in op tfy-llm-gateway voor alle spans als resource-attribuut. In de SigNoz Traces explorer isoleert het filteren op service.name = tfy-llm-gateway al het gateway-verkeer. Filteren op tfy.span_type = ChatCompletion vernauwt dit verder tot LLM-inferentie-requests. Het attribuut tfy.data_routing.destination identificeert welk model of virtueel model het request heeft verwerkt en kan worden gebruikt om latency-distributies te groeperen per model.

Architectuuroverzicht

Een request komt binnen in de TrueFoundry AI Gateway en wordt volledig in het geheugen verwerkt. De gateway stuurt het request door naar de LLM-provider en streamt de response terug naar de client. Nadat de response is voltooid, publiceert de gateway een span naar NATS met de volledige request- en response-attributen, aantallen tokens en latency. De OTEL exporter pakt de span asynchroon op uit NATS en stuurt deze via OTLP/HTTP met de header signoz-ingestion-key naar het regionale SigNoz-ingestion-endpoint op poort 443. De gedeelde SigNoz OTel gateway ontvangt de span en batcht deze in Redpanda. De per-tenant SigNoz collector leest uit Redpanda en past de signozspanmetrics processor toe om RED-metrics te genereren. Vervolgens schrijft deze spans naar distributed_signoz_index_v3 en metrics naar signoz_metrics.distributed_samples_v4 in de ClickHouse-instantie per tenant. De SigNoz query service leest uit ClickHouse en toont de trace in de Traces explorer en de gegenereerde metrics in de Metrics explorer.

Er zijn geen sidecars vereist. Er zijn geen SDK-wijzigingen vereist. Er wordt geen instrumentatiecode toegevoegd aan enige applicatie. De enige configuratiewijziging is het toevoegen van twee OTEL exporter endpoints in de OTEL Config instellingen van de TrueFoundry AI Gateway. De gateway genereert en publiceert de spans al. De exporter-configuratie en de ingestion key bepalen waar ze naartoe gaan.

Het architecturale principe dat deze integratie laat werken, is de volledige scheiding tussen het request-pad en het telemetrie-exportpad. De gateway publiceert telemetrie naar NATS nadat de response al is verzonden. Het SigNoz ingestion endpoint kan traag, tijdelijk onbeschikbaar of geografisch ver weg zijn, zonder enige invloed op de latency of betrouwbaarheid van de gateway. OTEL-portabiliteit betekent dat dezelfde span-data die vandaag naar SigNoz stroomt, naar elk ander OTLP-compatibel backend kan stromen zonder de gateway-configuratie te wijzigen, afgezien van de endpoint URL en de authenticatie-header.

‍