Hoe u provider-neutrale LLM-waarneembaarheid kunt opbouwen met OpenTelemetry

LLM-waarneembaarheid wordt verstoord wanneer elk applicatieteam de antwoorden van de provider in zijn eigen indeling registreert. Tijdens een incident moeten platformteams concrete vragen beantwoorden: welk team heeft het verzoek gedaan, welk sleutelbereik API is gebruikt, welk model is aangevraagd, welke provider het daadwerkelijk heeft aangeboden, of er een nieuwe poging of terugval heeft plaatsgevonden, hoeveel tokens er zijn verbruikt, welke latentiebucket is gewijzigd en welke foutklasse de fout heeft veroorzaakt. Ze hebben deze antwoorden ook nodig zonder onbewerkte aanwijzingen, aanvullingen, providersleutels of klant-ID's naar generieke logbestanden te kopiëren.

Het praktische antwoord is om de multi-model API gateway te instrumenteren als controlepunt voor observatie. Tracering op applicatieniveau is nog steeds van belang, maar de gateway is waar providerselectie, nieuwe pogingen, fallbacks, gebruiksaccounting, verzoekeigendom en privacyhandhaving kunnen worden genormaliseerd voordat telemetrie downstream-tools bereikt. Voor teams die een enterprise LLM API exploiteren, wordt dit het verschil tussen verspreide foutopsporingsgegevens en een providerneutraal bedrijfsmodel.

Definieer eerst het observatiecontract

Begin met een schriftelijk attribuutcontract, niet met dashboardscreenshots. Het contract moet de minimale metagegevens definiëren die elk LLM-verzoek moet uitzenden, welke velden de gateway mogen verlaten, welke velden beperkt zijn en welke velden nooit worden geëxporteerd.

Een nuttig basiscontract omvat metagegevens over eigendom, routering, model, gebruik, latentie en uitkomst. Eigendomskenmerken identificeren de organisatie, het team, de omgeving, de werklast, de applicatie en API sleutelbereik. Routeringskenmerken identificeren de gatewayroute, de beleidsversie, de aangevraagde provider, het aangevraagde model, de geselecteerde provider, het geselecteerde model, het aantal nieuwe pogingen, het aantal terugval en of streaming is gebruikt. Gebruikskenmerken leggen invoertokens, uitvoertokens, in de cache opgeslagen invoertokens, redeneertokens indien beschikbaar, aantal verzoeken en geschatte kostenklasse vast. Uitkomstkenmerken omvatten de status, de foutcode van de provider indien veilig, de genormaliseerde foutklasse, het validatieresultaat, de time-outstatus en het uiteindelijke responsmodel.

Houd de contractprovider neutraal. Een providerspecifieke fout, zoals een snelheidslimietreactie, een overbelaste modelreactie, een mislukte schemavalidatie, een veiligheidsweigering, een time-out of een contextvensterfout, moet worden toegewezen aan een genormaliseerde foutklasse die dashboards over verschillende providers kunnen groeperen. De oorspronkelijke foutcode van de provider kan nuttig zijn, maar moet worden behandeld als beperkte diagnostische gegevens en niet als een primaire dashboarddimensie.

Gebruik een Gateway-Centered Span-model

Een duidelijke traceringsstructuur voorkomt dat LLM-telemetrie een platte stapel reeksen wordt. Gebruik één binnenkomende aanvraagreeks voor toepassingen, één logische LLM-bewerkingsreeks en onderliggende reeksen voor het werk dat de gateway uitvoert.

Een typische hiërarchie ziet er als volgt uit:

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

De inkomende aanvraagreeks vertegenwoordigt het verzoek van de beller aan de gateway. De logische LLM-bewerkingsspanne vertegenwoordigt de voor de gebruiker zichtbare LLM-taak, zelfs als de gateway meerdere providerpogingen doet. De pogingen van de provider leggen elke daadwerkelijke oproep naar een upstream-model API vast. Ophaal-, tool- en validatiereeksen moeten onderliggende onderdelen van de logische bewerking zijn wanneer ze deel uitmaken van het produceren van het uiteindelijke antwoord.

Deze scheiding is van belang tijdens incidenten. Als een verzoek terugvalt van het ene model naar het andere, kan de logische bewerking slagen terwijl de eerste poging van de provider mislukt. Als de uiteindelijke uitvoer de schemavalidatie mislukt, kan de poging van de provider technisch gezien succesvol zijn, terwijl de logische bewerking mislukt. Zonder aparte reeksen verbergen dashboards providerfouten achter succesvolle antwoorden van eindgebruikers of overschatte fouten die met succes zijn hersteld.

Breng OpenTelemetry GenAI-attributen in kaart achter een interne mapper

Er bestaan ​​semantische conventies voor OpenTelemetry, zodat producenten van telemetrie algemene namen en attributen gebruiken voor codebases, bibliotheken en platforms.Het OpenTelemetry-project verwijst nu Generative AI-conventies naar een aparte GenAI-opslagplaats, en die conventies definiëren modelaanvraag- en responskenmerken zoals providernaam, aangevraagd model, responsmodel, invoertokens, uitvoertokens, redeneringstokens en in de cache opgeslagen invoertokens.

Gebruik die GenAI-kenmerken waar ze passen, maar verspreid geen ruwe attribuutnamen door de gatewaycode. Wikkel ze achter een kleine telemetriemapper. Die mapper moet een intern verzoekrecord accepteren en gestandaardiseerde span-attributen produceren.

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
}

De mapper kan OpenTelemetry GenAI-attributen voor de standaardvelden en privé-gateway-attributen voor de zakelijke context uitzenden. Bewaar privékenmerken onder een gecontroleerde naamruimte, bijvoorbeeld llm_gateway.organization_id, llm_gateway.team_id, llm_gateway.key_scope, llm_gateway.route_policy en llm_gateway.workload_class.

Dit ontwerp biedt leveranciersneutrale telemetrie en beschermt de codebase tegen churn. GenAI-conventies zijn nog steeds in ontwikkeling, dus de mapper is de plek waar namen kunnen veranderen zonder elke handler, module voor opnieuw proberen, streaming-adapter en validatiecomponent te bewerken.

Scheid metagegevens van gevoelige inhoud

LLM-traceringen zijn ongebruikelijk gevoelig omdat de nuttigste foutopsporingsgegevens dezelfde gegevens kunnen zijn die niet algemeen mogen worden bewaard: aanwijzingen, opgehaalde documenten, toolparameters, voltooiingen, gebruikers-ID's, klantgegevens ID's en onbewerkte providerreferenties. De standaardhouding moet op de eerste plaats waarneembaarheid van metagegevens zijn.

Aanbevolen standaardvelden zijn onder meer prompthash, promptsjabloon-ID, promptversie, schema-ID, toolnaam, ophaalverzameling, routenaam, tokenaantallen, latentie, genormaliseerde foutklasse en validatiestatus. Deze velden beantwoorden veel operationele vragen zonder onbewerkte inhoud te exporteren.

Het vastleggen van onbewerkte prompts en voltooiingen moet opt-in zijn, in de tijd beperkt, met toegangscontrole en worden geredigeerd vóór de export. Schakel het niet wereldwijd in als gemaksfunctie. Wanneer het vastleggen van inhoud nodig is voor een productie-incident, koppelt u een foutopsporingsvlag aan een beperkt aantal verzoeken, stuurt u deze traceringen naar een beperkte backend en stelt u een korte bewaarperiode in.

Hashing-ID's leiden niet automatisch tot anonimisering. Als de invoerruimte klein of voorspelbaar is, kunnen gehashte waarden worden omgekeerd door te raden. Voor gevoelige klant- of gebruikers-ID's kunt u het verwijderen, vervangende ID's, bucketing, afkapping of ingetoetste hashing met strikte sleutelcontroles overwegen. Gebruik hashes in de eerste plaats voor een stabiele correlatie wanneer het risico wordt begrepen, en niet als algemeen privacyantwoord.

Privacy afdwingen in de Collector

OpenTelemetry-richtlijnen zeggen dat gevoelige gegevens moeten worden verwerkt voordat ze worden geëxporteerd. De Collector kan telemetrie-attributen verwijderen, hashen, filteren, redigeren of transformeren met behulp van processors zoals attributen, filteren, redigeren en transformeren. Dat maakt de Collector tot een tweede verdedigingslinie na de gateway-instrumentatie zelf.

Een praktische Collector-pijplijn zou een toelatingslijst moeten gebruiken voor attributen met een laag risico, standaard onbewerkte prompt- en antwoordvelden moeten verwijderen, waarden moeten maskeren die overeenkomen met geblokkeerde patronen, en traceringen met een hogere gevoeligheid afzonderlijk moeten routeren wanneer het vastleggen van inhoud expliciet is ingeschakeld. De kenmerkenprocessor van OpenTelemetry Collector ondersteunt acties zoals verwijderen en hash. De redactieprocessor is ontworpen om kenmerken te verwijderen die niet op een toelatingslijst staan ​​en waarden te maskeren die overeenkomen met geblokkeerde patronen.

De gateway kan bijvoorbeeld voorkomen dat standaard onbewerkte inhoud wordt uitgezonden, terwijl de Collector nog steeds kenmerken verwijdert zoals llm.prompt.raw, llm.completion.raw, provider.api_key, authorization en cookie als deze verschijnen vanwege een bug of bibliotheekintegratie. Beschouw dit als een diepgaande controle, en niet als een reden om terloops onveilige gegevens uit te zenden.

Opnieuw proberen, terugval en validatie van instrumenten afzonderlijk

Opnieuw proberen en terugval zijn vaak onzichtbaar in de verzamelde API statistieken. Die onzichtbaarheid veroorzaakt twee operationele problemen. Ten eerste kan de latentie afnemen omdat een succesvol antwoord meerdere mislukte pogingen kan verbergen.Ten tweede kunnen de kosten stijgen omdat een enkel gebruikersverzoek meerdere upstream-modelaanroepen kan veroorzaken.

Elke providerpogingsperiode moet het aantal pogingen, de reden voor de nieuwe poging, de geselecteerde provider, het geselecteerde model, het time-outbudget, de latentie, het tokengebruik, indien beschikbaar, en de uitkomst bevatten. Als er een fallback plaatsvindt, moet de fallback-reeks het oorspronkelijke routebeleid, de fallback-reden en het model dat daadwerkelijk wordt gebruikt voor het uiteindelijke antwoord identificeren.

Gestructureerde uitvoervalidatie moet zijn eigen span of gebeurtenis zijn. Leg schema-ID, schemaversie, validatieresultaat, aantal reparatiepogingen en eindstatus vast. Sla standaard niet de volledige ongeldige uitvoer op. Een validatiefout is operationeel anders dan een transportfout bij een provider, en dashboards mogen deze niet door elkaar laten vervagen.

Bouw dashboards rond vragen, niet rond providers

Provider-neutrale observatie moet operationele vragen direct beantwoorden. Nuttige dashboards omvatten p95- en p99-latentie per model, provider, team, omgeving en werklastklasse; tokengebruik per team en route; uitvalpercentage per genormaliseerde foutklasse; versterking van nieuwe pogingen door routebeleid; terugvalfrequentie per aangevraagd model; contextvensterfouten door promptsjabloon; mislukte gestructureerde uitvoervalidatie per schema; en voorbeelden van traceringen voor mislukte, dure of langzame verzoeken.

Houd de facturering en rapportage van het totale gebruik buiten de traceringen. Tail sampling is handig voor het opsporen van fouten, maar kan de totalen vertekenen. Tokentotalen, aanvraagtellingen en kostenboeken moeten afkomstig zijn van niet-bemonsterde tellers, aanvraaggrootboeken of systemen voor afstemming van facturen. Traceringen moeten verklaren waarom een ​​duur of traag verzoek heeft plaatsgevonden; ze zouden niet de enige bron van financiële waarheid moeten zijn.

Gebruik staartsteekproeven voor hoogwaardige sporen

De staartsteekproefprocessor van OpenTelemetry Collector kan steekproeven nemen nadat reeksen zijn voltooid, inclusief beleid op basis van attributen en numerieke waarden. Dat is handig voor LLM-verkeer, omdat u vaak pas weet of een tracering waardevol is nadat het antwoord is voltooid.

Bewaar traceringen voor providerfouten, validatiefouten, zeer hoge latentie, ongewoon duur tokengebruik, fouten in het contextvenster, terugvalpogingen en handmatig getagde verzoeken. Proef routinematig succesvol verkeer tegen een lager tarief. Hierdoor blijven de sporen behouden die incidenten kunnen verklaren, terwijl het opslagvolume wordt beheerd.

Een redelijk beleidsmodel is eenvoudig: houd altijd fouten bij, houd verzoeken altijd boven een latentie- of tokendrempel, bewaar altijd met foutopsporing getagde sporen en bemonster op probabilistische wijze gewone succesvolle verzoeken. Herzie drempels als het verkeer verandert. Een drempel die nuttig is tijdens de vroege acceptatie kan te laag zijn zodra het productieverkeer groeit.

Voeg contracttests toe voor telemetrie

Telemetrie moet worden getest als een API contract omdat downstream-dashboards, waarschuwingen, kostencontroles en incidentworkflows ervan afhankelijk zijn. Voeg tests toe die representatieve gateway-aanvragen uitvoeren en bevestig dat de vereiste bereiken en attributen worden verzonden.

De tests moeten verifiëren dat een succesvol verzoek de logische LLM-bewerkingsspanne, een providerpogingspanne, het aangevraagde model, het responsmodel, de providernaam, het tokenaantal indien beschikbaar, de metagegevens van het team of het sleutelbereik, de versie van het routebeleid en de uiteindelijke status uitzendt. Tests voor nieuwe pogingen moeten het aantal pogingen en de redenen voor nieuwe pogingen bevestigen. Fallback-tests moeten zowel de mislukte poging als de uiteindelijke succesvolle providerpoging bevestigen. Validatietests moeten het schema-ID, de validatiestatus en het aantal reparatiepogingen bevestigen.

Beveiligingstests zijn net zo belangrijk. Beweer dat onbewerkte providersleutels, autorisatieheaders, cookies, onbewerkte aanwijzingen, onbewerkte voltooiingen en niet-goedgekeurde klant-ID's ontbreken in geëxporteerde telemetrie.Deze tests moeten mislukken wanneer een ontwikkelaar een nieuw span-kenmerk toevoegt zonder het te classificeren.

Implementatiechecklist

• Kenmerkcontract: Definieer vereiste, optionele, beperkte en verboden kenmerken.
• Span-hiërarchie: Afzonderlijke inkomende verzoeken, logische LLM-bewerkingen, providerpogingen, nieuwe pogingen, terugval, ophaalaanroepen, tool aanroepen en validatie.
• Semantische toewijzing: Gebruik OpenTelemetry GenAI-kenmerken waar ze passen en privé-gatewaykenmerken voor eigendoms- en routeringscontext.
• Privacybeleid: Standaard ingesteld op hashes, sjabloon-ID's, schema-ID's, toolnamen, tokenaantallen, latentie en foutklassen in plaats van onbewerkt content.
• Verzamelprocessors: Verwijder verboden velden, redigeer geblokkeerde patronen, zet attributen met een laag risico op de toelatingslijst en stuur gevoelige traceringen afzonderlijk door.
• Samplingbeleid: Maak een staartsteekproef van hoogwaardige traceringen en bewaar de verzamelde statistieken unsampled.
• Dashboards: Creëer weergaven rond latentie, gebruik, fouten, nieuwe pogingen, fallbacks, validatie en kostenfactoren.
• Waarschuwingen: Waarschuwing over genormaliseerde foutklassen, p99-latentieverschuivingen, versterking van nieuwe pogingen, fallback-pieken, validatiefouten en token afwijkingen.
• Contracttests: Beweer dat de vereiste telemetrie aanwezig is en gevoelige telemetrie afwezig.

Afwegingen om expliciet te beslissen

Instrumentatie op gatewayniveau levert snel consistente metadata op, maar kan applicatiespecifieke context missen, tenzij teams gestructureerde verzoekmetadata doorgeven, zoals tenant, workflow, promptsjabloon en functienaam. Maak die metagegevens onderdeel van het gateway-aanvraagcontract in plaats van te vertrouwen op logbestanden in vrije vorm.

Het volledig vastleggen van inhoud verbetert de foutopsporing en evaluatie, maar verhoogt de lasten op het gebied van privacy, beveiliging, retentie en toegangscontrole. Veel teams zouden moeten beginnen met alleen hashes, sjabloon-ID's, schema-ID's en geredigeerde fragmenten.

Provider-neutrale foutklassen maken dashboards bruikbaar voor meerdere model-API's, maar ze comprimeren provider-specifieke details. Bewaar onbewerkte foutcodes van de provider alleen als dit veilig is, en beperk de toegang daartoe.

OpenTelemetry GenAI-conventies verminderen de lock-in, maar de conventies zullen blijven evolueren. Een interne mapper biedt u de voordelen van standaardisatie zonder dat onstabiele attribuutnamen door de codebase lekken.

Conclusie

Provider-neutrale LLM-observatie is niet alleen maar tracering die wordt toegevoegd aan modelaanroepen. Het is een operationeel contract op de gatewaylaag: consistente spanwijdten, genormaliseerde model- en provider-metagegevens, eigendomscontext, tokengebruik, zichtbaarheid van nieuwe pogingen en terugval, privacycontroles, samplingregels en tests die voorkomen dat gevoelige gegevens lekken.

Begin met de gateway, omdat deze al de beslissingen ziet die er het meest toe doen: wie het verzoek heeft ingediend, welk beleid het heeft gerouteerd, welke provider het heeft aangeboden, wat het in tokens heeft gekost, hoe lang het heeft geduurd, of de herstellogica heeft gewerkt en wat er is mislukt. Zodra die basis stabiel is, kunnen applicatieteams een rijkere workflowcontext toevoegen zonder dat elk team zijn eigen LLM-observatiesysteem hoeft uit te vinden.

Gerelateerd lezen

• fallback routing-telemetrie