OpenTelemetry GenAI Conventions: Een Gemeenschappelijk Vocabulaire voor AI Observability

OpenTelemetry geeft GenAI-systemen een gedeeld telemetrievocabulaire, maar het is geen voltooide universele schema. In juni 2026 verplaatste het project zijn GenAI-, providerspecifieke en MCP-semantische conventies naar een dedicated repository, zodat deze onafhankelijk konden itereren en versioneren. Die repository merkt de GenAI-conventies momenteel aan als Development, en vanaf 21 augustus 2026 heeft het geen officiële release. De kans is nog steeds aanzienlijk: gemeenschappelijke namen voor modeloperaties, tokengebruik, agentstappen, MCP-calls, content-events en evaluatieresultaten kunnen het vertaalwerk over instrumentatie- en observability-backends verminderen. De engineering-houding moet adoptie met versiebewustzijn zijn—niet de aanname dat gen_ai.* al bevroren is.

Twee teams kunnen geldige OpenTelemetry uitzenden en het nog steeds oneens zijn over wat een LLM-call betekent. Transportinteroperabiliteit en semantische interoperabiliteit zijn verschillende problemen. OTLP kan telemetrie tussen systemen verplaatsen; semantische conventies maken de velden binnen die telemetrie consistenter interpreteerbaar. Voor GenAI wordt het tweede probleem nog actief gestandaardiseerd.

1. Waarom GenAI Meer Nodig Heeft Dan Generieke APM

Generieke APM blijft nuttig voor throughput, latency, fouten, afhankelijkheden en service health. GenAI voegt semantiek toe die die signalen op zichzelf niet beschrijven.

Probabilistisch gedrag. Hetzelfde logische verzoek kan verschillende outputs genereren, dus debugging vereist vaak het gevraagde en geserveerde model, generatie-instellingen, respons-identifiers en—waar het beleid dit toestaat—relevante input- of output-context. Volledige content is nuttig bewijs, maar het is niet altijd gepast of noodzakelijk om te bewaren.

Token economics. Aantallen verzoeken zijn nog steeds van belang voor belasting en rate limiting, maar ze zijn onvoldoende voor kosten- en modelefficiëntie-analyses. Een klein aantal calls met een lange context kan meer kosten dan een groot aantal korte calls. Huidige GenAI-metrics omvatten tokengebruik en duur van de operatie, samen met time-to-first-chunk en time-per-output-chunk metingen.

Agent-structuur. Een modelcall is slechts één operatie binnen vele agents. Planning, tool-uitvoering, retrieval, workflows en MCP-calls kunnen het resultaat bepalen. Observability heeft daarom een vocabulaire nodig voor de uitvoering rondom de inferentie, niet alleen de provider API-grens.

Contentgevoeligheid. Prompts en outputs bevatten vaak gebruikers- of bedrijfsgegevens. OpenTelemetry kan beschrijven hoe die content moet worden vastgelegd, maar of deze moet worden vastgelegd, bewaard, geëxporteerd, geredigeerd of beperkt, blijft een beslissing op het gebied van data governance.

2. Wat de Conventies Nu Omvatten

De meest nuttige manier om het huidige werk te lezen is per signaal en operatie, in plaats van uit te gaan van één volwassenheidsladder. De dedicated GenAI-repository merkt de algemene conventies aan als Development.

Model- en inferentie-spans. Huidige conventies definiëren GenAI-clientoperaties, waaronder inferentie, embeddings, retrievals, response fetching, geheugenoperaties en tool-uitvoering. Veelvoorkomende attributen zijn onder meer gen_ai.provider.name, gen_ai.operation.name, gevraagde en respons-modelidentifiers en input/output-tokengebruik. Span-timing levert de duur van de operatie; dedicated metrics standaardiseren tokengebruik en latency-gerelateerde metingen.

Agent- en framework-spans. De agent-conventies definiëren operaties zoals create_agent, invoke_agent, invoke_workflow, plan en execute_tool. Deze spans kunnen een geïnstrumenteerd uitvoeringspad meeneembaar maken voor reconstructie. Ze leggen het privé-redeneren van een model niet bloot en verschijnen niet automatisch, tenzij het relevante framework of de instrumentatie ze uitzendt.

MCP-conventies. MCP heeft zijn eigen Development-conventies voor client- en server-spans, W3C Trace Context-propagatie, transportcorrelatie, tool-bewuste attributen en metrics zoals mcp.client.operation.duration en mcp.server.operation.duration. De waarde is continuïteit over de MCP-grens—niet de belofte dat elke MCP-implementatie de conventies al uitzendt.

Metrics en providerspecifieke conventies. De repository definieert client-, server-, workflow-, agent- en tool-metrics en voegt providerspecifieke conventies toe voor systemen zoals OpenAI, Anthropic, Azure AI Inference en AWS Bedrock.

3. Content Capture Is een Opt-In Beleidsbeslissing

Het huidige event gen_ai.client.inference.operation.details kan chatgeschiedenis, parameters, inputs en outputs onafhankelijk van de hoofd-trace dragen. Het vereiste niveau is expliciet Opt-In, en de OpenTelemetry-documentatie waarschuwt dat ondersteuning voor events nog niet in elke taal beschikbaar is.

Dat is een betere standaardinstelling dan prompts en completions te behandelen als gewone diagnostische tekst. OpenTelemetry definieert de vorm van de telemetrie; het bepaalt niet uw bewaartermijn, regionale opslag, toegangsbeleid, wettelijke basis of redactievereisten. Dat blijven verantwoordelijkheden van de operator en de backend.

Schrijf voor een productie-implementatie het beleid voordat u content inschakelt: welke omgevingen volledige content mogen vastleggen, wat wordt gefilterd of afgekapt, waar geëxporteerde telemetrie naartoe mag, hoe lang het wordt bewaard en wie het kan ophalen.

4. Wat Dit Betekent voor een Gateway

Een gateway is een sterk emissiepunt voor het modelverkeer dat er daadwerkelijk doorheen gaat. Het observeert gevraagde en geserveerde modellen, latency, provider-resultaten, tokengebruik, routinggedrag en kosteninputs zonder elk applicatieteam te vragen die verzameling onafhankelijk te herbouwen. Het is op zichzelf geen volledige agent-trace: app-lokale planning, retrieval, tool-werk of calls die de gateway omzeilen, vereisen instrumentatie op die lagen.

TrueFoundry exporteert al via OpenTelemetry. AI Gateway ondersteunt OTLP-export voor traces en metrics naar compatibele observability-platformen. De huidige technische documentatie van TrueFoundry beschrijft bovendien provider spans die gebruikmaken van eigentijdse attributen zoals gen_ai.provider.name, gen_ai.operation.name, gen_ai.request.model, gen_ai.response.model, gen_ai.usage.input_tokens en gen_ai.usage.output_tokens, naast TrueFoundry-specifieke uitbreidingen voor gateway-context en kosten. (OpenTelemetry export-documentatie; TrueFoundry's gateway-instrumentatiegids.)

MCP-zichtbaarheid kan binnen hetzelfde operationele vlak bestaan. TrueFoundry's Metrics Dashboard volgt MCP-verkeer, servers, tools, fouten en latency voor calls die via de AI/MCP Gateway worden gerouteerd. Dat is een aanvulling op—en geen vervanging van—applicatie- of harness-instrumentatie voor agent-lokale stappen. (Metrics Dashboard; MCP Gateway-overzicht.)

De agent-runtime vormt de aanvullende observability-grens. TrueForge, TrueFoundry's open-source agent harness, voert de model/tool-loop uit met MCP-tools, skills, sandboxing, goedkeuringen, contextbeheer en permanente sessies. Het SDK-model biedt een expliciete Agent → Session → Turn → Event-hiërarchie, met gestreamde events voor MCP-initialisatie, modelberichten, tool-responses, goedkeuringen en turn-voltooiing. Deze runtime-events bevatten context op agent-niveau die een gateway niet alleen uit model- en MCP-verkeer kan afleiden.

De claim die veilig is voor publicatie is bewust beperkter dan een integratieclaim: dit artikel beweert niet dat TrueForge momenteel de nieuwste OpenTelemetry GenAI-semantische conventies uitzendt. In plaats daarvan biedt TrueForge een open, inspecteerbaar runtime-oppervlak dat geïnstrumenteerd of gecorreleerd kan worden met de OTLP-traces die TrueFoundry AI Gateway al exporteert. Die scheiding is een nuttige architectuur: de harness weet wat de agent doet; de gateway weet wat de policy-grens heeft overschreden; OpenTelemetry geeft deze geïnstrumenteerde lagen een gemeenschappelijk transport en een steeds vaker gedeeld vocabulaire.

Externe trace-export beschikt over een expliciete content-bediening. TrueFoundry's OTel-integratiegidsen documenteren een optie Exclude Request Data die tfy.input, tfy.output en tfy.input_short_hand uit geëxporteerde spans verwijdert, terwijl structurele telemetrie zoals tokens, latency en model-metadata behouden blijft. Dat is een nuttige egress-bediening voor die TrueFoundry-inhoudsvelden; teams moeten nog steeds eventuele aanvullende standaard- of aangepaste attributen beoordelen die ze uitzenden. (voorbeeld integratiedocumentatie.)

Evaluatie blijft een afzonderlijke berekening. TrueFoundry ondersteunt externe evaluatieworkflows over traces, terwijl de OpenTelemetry-conventie een standaardlocatie biedt om het resultaat van een evaluator weer te geven. Voeg deze niet samen tot één claim: telemetrie bevat bewijslast; evaluators interpreteren deze. (online evaluatie.)

5. Een Inzetbare Houding

Scheid OTLP-portabiliteit van de volwassenheid van semantische conventies. Het is nu al nuttig om traces en metrics te exporteren via OpenTelemetry, zelfs terwijl GenAI-veldnamen zich verder ontwikkelen.

Pinnen en testen van de semantiek die u daadwerkelijk uitzendt. De GenAI-repository is in Development, oudere kerndefinities zijn verplaatst en taalondersteuning is ongelijkmatig. Behandel uw uitgezonden attributenset als een interface met versiebeheer en test deze tegen de backend en instrumentatiebibliotheken die u gebruikt.

Instrumenteer elke handhavings- of uitvoeringsgrens voor wat deze daadwerkelijk kan zien. Een gateway is uitstekend geschikt voor model- en via de gateway gerouteerd MCP-verkeer. Agent/harness-instrumentatie is nog steeds nodig voor planning, lokale tools, retrieval, statusovergangen en ander werk dat die gateway nooit passeert.

Instrumenteer de harness-grens wanneer u agent-semantiek nodig hebt. Als u TrueForge gebruikt, bieden het sessie-, turn- en eventmodel u expliciete runtime-identifiers en tool/approval-events om te correleren met gateway-traces. Neem alleen de correlatie-metadata mee die uw observability-beleid toestaat; kopieer standaard geen gevoelige event-payloads naar span-attributen.

Maak het vastleggen van inhoud opt-in via beleid. Minimaliseer en filter inhoud vóór export, en stel vervolgens retentie- en toegangsbepalingen in binnen de observability-backend. Verwar een OpenTelemetry-veldnaam niet met een data-governancebeleid.

Houd evaluatie gescheiden, maar correleer deze. Bereken kwaliteit of veiligheid met de evaluator die geschikt is voor de workload, en gebruik vervolgens een standaard evaluation-result event (waar ondersteund) om het resultaat te koppelen aan de operatie die de response heeft gegenereerd.

Gebruik aangepaste attributen als uitbreidingen, niet als vervangingen. Productspecifieke velden zoals TrueFoundry's gateway- en kostenmetadata zijn nuttig. Houd de standaardattributen ernaast, zodat generieke tooling een gemeenschappelijk oppervlak behoudt.

6. Waar de Standaard Ophoudt

De semantische conventies lossen een vocabulaireprobleem op, niet elk observability-probleem. De toegewijde OpenTelemetry GenAI-repository is nog steeds in Development; de dekking van implementaties varieert per taal en bibliotheek; en backends kunnen verschillen in hoe ze dezelfde telemetrie indexeren, opvragen, renderen, bewaren of prijzen. Zelfs een perfecte dekking van semantische conventies beschrijft alleen wat de instrumentatie kan observeren—het legt geen verborgen modelredeneringen bloot en maakt ongeïnstrumenteerde uitvoering niet zichtbaar.

Voor TrueFoundry is de nuttige claim concreet: AI Gateway kan traces en metrics exporteren via OTLP en documenteert actuele gen_ai.* attributen naast TrueFoundry-specifieke uitbreidingen. Dat geeft teams een op standaarden gebaseerd exportpad zonder te pretenderen dat de onafhankelijk evoluerende GenAI-conventies bevroren zijn. Als een specifieke versie van semantische conventies een vereiste is voor inkoop of governance, valideer dan de exacte uitgezonden attributenset en de taal/backend-ondersteuning waarvan u afhankelijk bent.

Referenties

• OpenTelemetry — GenAI semantic conventions overview (huidige status: Development).
• OpenTelemetry — GenAI client spans, metrics, en agent/framework spans.
• OpenTelemetry — MCP semantic conventions voor client/server spans, propagatie en metrics.
• OpenTelemetry — GenAI events, inclusief opt-in inference details en gen_ai.evaluation.result.
• OpenTelemetry — core semantic-conventions v1.42.0, die GenAI-definities heeft verplaatst naar de dedicated repository.
• TrueFoundry — OpenTelemetry trace and metrics export; AI Gateway instrumentation guide; Metrics Dashboard; MCP Gateway overview.
• TrueFoundry — online evaluation, als een afzonderlijke berekening over observability-bewijslast.
• TrueForge — agent harness overview en SDK concepts, ter documentatie van de Agent → Session → Turn → Event-hiërarchie en runtime-events voor model-, MCP-, tool-, approval- en completion-activiteit. Dit bericht claimt geen native conformiteit van die events met de nieuwste GenAI-semantische conventies.

OpenTelemetry GenAI-status en veldnamen worden beschreven vanuit de huidige dedicated GenAI semantic-conventions repository zoals gecontroleerd op 21 augustus 2026. De repository bevindt zich in Development en heeft op die datum geen officiële release. TrueFoundry productverklaringen zijn beperkt tot huidige openbare documentatie en engineeringmateriaal: OTLP-export, gateway-observability, MCP-metrics, gedocumenteerde gen_ai.* attributen, en export-time filtering van gespecificeerde tfy.* inhoudsvelden. Dit bericht claimt geen conformiteit met een specifieke niet-uitgebrachte OpenTelemetry GenAI repository commit.