OpenTelemetry LLM провайдерлерін бірыңғай схемаға қалай келтіреді

LLM observability командада трассировкалар болмағандықтан бұзылмайды. Ол бір дашборд кіріс токендерін prompt_tokens, екіншісі input_tokens деп атағанда, үшіншісі оларды кэш токендерімен араластырғанда, ал төртіншісі пайдаланушы нәтижені үш fallback әрекетінен кейін ғана алған шақыруды сәтті деп санағанда бұзылады.

Әр API жауабының «әмбебап» көшірмесі қажет емес. Әр өрісі бір сұраққа жауап беретін шағын ішкі схема керек, ал провайдердің бастапқы жауабы бөлек жатуы тиіс. Сонда провайдерді ауыстыруға, маршрутизация қосудың және SDK жаңартуларынан өтуге болады, сапа, кідіріс пен шығын туралы есептерді қайта жазудың қажеті болмайды.

Дұрыс схема API атауларын емес, фактілерді сипаттайды

Бір шақыру жазбасы нақты провайдердің сөздігін қайталамай, не болғанын тіркеуі керек. Провайдер токендерді usage.input_tokens, usageMetadata.promptTokenCount немесе prompt_tokens деп атауы мүмкін. Аналитик үшін бұл бір факт: операция қанша кіріс токенін өңдеді.

Мен өрістерді әдетте үш қабатқа бөлемін.

• Жалпы llm.* қабаты нормаланған фактілерді сақтайды және дашбордтар, бюджеттер мен алерт ережелеріне арналған келісім болып қалады.
• gen_ai.* қабаты мағынасы сәйкес келетін жерде OpenTelemetry-дің үйлесімді атрибуттарын қайталайды.
• llm.raw.* қабаты бастапқы сұрау мен жауапқа сілтемені, олардың бақылау қосындыларын, контент түрін және адаптер нұсқасын сақтайды, бірақ бүкіл JSON-ды span атрибуттарына тықпайды.

Мұндай бөлу деректерді тек әдемілік үшін қайталамайды. OpenTelemetry-дегі GenAI стандарттары әлі өзгеріп жатыр. Мысалы, жоба бар инструменттеулерге v1.36.0-ге дейін қолданылған келісім нұсқаларын әдепкі бойынша ауыстырмауды және көшу үшін тұрақтылық ауыстырғышын енгізуді ұсынады. Егер бүкіл есептілігіңіз өзгеруі мүмкін бір атрибут атауына байланып тұрса, кітапхананы жаңарту аналитика инцидентіне айналады.

Бір LLM операциясына арналған ең аз келісім мынадай болуы мүмкін:

{
  "llm.schema.version": "1.0",
  "llm.operation": "chat",
  "llm.provider.requested": "openai",
  "llm.provider.resolved": "anthropic",
  "llm.model.requested": "smart-assistant",
  "llm.model.resolved": "claude-sonnet",
  "llm.request.stream": true,
  "llm.response.finish_reason": "tool_call",
  "llm.outcome": "success",
  "llm.raw.request_ref": "obj://telemetry/req/7f2c",
  "llm.raw.response_ref": "obj://telemetry/res/7f2c",
  "llm.raw.adapter": "anthropic-messages-v3"
}

Мұнда нақтылаусыз model өрісі жоқ. Бұл әдейі жасалған. Жалғыз model көбіне дау туғызады: ол клиент сұраған модельді ме, маршрутизатор таңдаған модельді ме, әлде финалдық жауаптағы жолды ма білдіреді? Бір айдан кейін мұны ешкім есіне түсірмейді, ал шығын графигі нанымды көрініп, шындықты бұрмалайды.

Сұралған модель мен нақты модель бір нәрсе емес

llm.model.requested шақырушы кодтың ниетін сипаттайды. llm.model.resolved орындалуды сипаттайды. Олардың арасында алиас, маршрутизация ережесі, қолжетімділікті тексеру, провайдердің бас тартуы немесе басқа аймаққа ауысу болуы мүмкін.

Бұл айырманы ең қарапайым интеграцияда да жасыруға болмайды. Өнім командасы customer-support жіберді делік. Маршрутизатор алдымен бір модельді таңдап, қуат шектеуіне тап болып, сұрауды басқа модельде орындады. Егер трассировкада тек customer-support қалса, SRE кідірістің өсу себебін көрмейді. Ал тек соңғы физикалық модель қалса, өнім иесі шығынға қандай бизнес ережесі себеп болғанын түсінбейді.

Провайдерге арналған екі бөлек өрісті де қосыңыз. Модель мен провайдер ажырамас жұп емес: бір модель идентификаторы бірнеше жеткізушіде қолжетімді болуы мүмкін, ал прокси сұрауды өзінің инфрақұрылымына бағыттай алады.

Пайдалы жиынтық мынадай:

llm.provider.requested
llm.provider.resolved
llm.model.requested
llm.model.resolved
llm.route.id
llm.route.reason
llm.fallback.count

llm.route.reason exception ішінен алынған еркін мәтін болмауы керек. Сөздікті шектеңіз: direct, cost_policy, latency_policy, capacity, provider_error, data_residency. Әйтпесе мыңдаған бірегей мән пайда болып, агрегация пайдасыз болады.

Fallback-ты retry-мен шатастырмаңыз. Fallback орындалу орнын немесе моделін өзгертеді. Retry сол таңдалған бағытта әрекетті қайталайды. Бір пайдаланушы шақыруында екеуі де болуы мүмкін, ал графикте олардың белгілері әртүрлі. Қайталаулар көбіне желі, лимиттер немесе уақытша тұрақсыздықты көрсетеді. Fallback маршрутизация саясатының жұмысын көрсетіп, жауап сапасын, бағаны немесе өңдеу юрисдикциясын өзгертеді.

Токендерді бір сомаға емес, мақсатына қарай сақтаңыз

total_tokens қысқа API жауабы үшін ыңғайлы, бірақ ақша, промптты оңтайландыру және кэшті талдау үшін пайдасы аз. Нақты есептерде мәтіннің бірдей көлемі оның кәдімгі кіріс ретінде өңделуіне, кэштен оқылуына, кэшке жазылуына немесе reasoning кезінде модельмен жасалуына қарай әртүрлі тұруы мүмкін.

Нормаланған схемаға мына есептегіштерді қосыңыз:

llm.usage.input_tokens
llm.usage.output_tokens
llm.usage.reasoning_output_tokens
llm.usage.cache_read_input_tokens
llm.usage.cache_creation_input_tokens
llm.usage.total_tokens_reported
llm.usage.source

llm.usage.source мәндерінің саны аз болуы керек: provider, gateway, estimated, unavailable. Бұл өріс тергеу кезінде жиі көмектеседі. Қаржы бөлімі инвойспен айырмашылық көрсе, оның API жауабы ма, әлде жергілікті токенизатормен жасалған шамалау ма екенін бірден түсінеді.

OpenTelemetry жүйе қолданылған және тарификацияланған токендерді бөлек берсе, billable tokens көрсетуді ұсынады. Бұл шығын метрикалары үшін орынды, бірақ техникалық есептегіштерді алып тастауға себеп емес. Биллинг токендерін құн есебінде ұстаңыз, ал техникалық санаттарды контекст, кэш және генерацияны талдау үшін сақтаңыз.

Нөлді ойдан қоспаңыз. Провайдер кэштелген токендерді қайтармаса, 0 кэштің нақты болмағанын білдіреді. Бұл «провайдер мәнді хабарламады» деген фактіден бөлек. JSON атрибуттарында мұндай өрісті мүлде жазбаған дұрыс, ал нормаланған қоймада null мәнін llm.usage.source=unavailable немесе бөлудің қолжетімділігін көрсететін бөлек белгімен бірге қолданыңыз.

Тағы бір тұзақ бар: адаптердің мағынасын бекітпей, cache_read_input_tokens мәнін input_tokens үстіне қоспаңыз. Кей API кіріс есептегішіне кэштен оқылған бөлікті қосады, ал кейбірі санаттарды бөлек береді. Ішкі келісім input_tokens толық кіріс пе, әлде тек кэштелмеген кіріс пе екенін ашық айтуы керек. Мен оны толық кіріс көлемі ретінде анықтап, кэш санаттарын оның талдаулары ретінде сақтауды ұсынамын. Сонда негізгі өрістен нені алып тастағанын болжаудың қажеті жоқ.

Құнның шығу тегі мен есеп күйі болуы керек

Ай соңында құнды модель атауынан ғана адал есептеу мүмкін емес. Баға күнге, аймаққа, өңдеу режиміне, токен түріне, batch режиміне және кейде қолжетімділік арнасының өзіне тәуелді. Егер жүйе тек llm.cost.usd=0.004 жазса, бұл санды аудиторға, бюджет иесіне немесе маршрутизацияны өзгертетін инженерге түсіндіре алмайсыз.

Сомамен шектелмей, мыналарды жазыңыз:

{
  "llm.cost.currency": "USD",
  "llm.cost.amount": 0.00428,
  "llm.cost.status": "final",
  "llm.cost.method": "provider_usage",
  "llm.cost.rate_card_id": "2026-07-usage-v4",
  "llm.cost.input_amount": 0.00120,
  "llm.cost.output_amount": 0.00308
}

llm.cost.status ойлағаннан пайдалырақ. Мен төрт күйді қолданамын: final, сома расталған usage пен қолданыстағы тариф арқылы есептелген кезде; estimated, есептегіштердің бір бөлігі ғана белгілі немесе баға шамаланған кестеден алынған кезде; pending, stream әлі аяқталмаған кезде; unavailable, құнды есептеу мүмкін болмаған кезде. Нөл бұл күйлердің ешқайсысын алмастырмайды.

Қаржылық есептер тек final мәндерін қосуы керек. Ал жедел бақылау есептері final + estimated мәндерін анық белгімен көрсете алады. Әйтпесе команда шын мәнінде әлі аяқталмаған stream шақыруы болған «аномалияны» іздеуге бір апта жұмсайды.

Құнды метрика label-іне жазбаңыз. Ақша кардиналдылығы тым жоғары. Құнды сандық метрика ретінде жіберіңіз немесе оқиғалардан қоймада есептеңіз. Labels ішінде модельді, провайдерді, операцияны, ортаны және нәтиже күйін қалдырыңыз. Тариф кестесінің нұсқасы негізгі метрикаға сирек жарайды, бірақ trace немесе есеп жазбасында жақсы жұмыс істейді.

Құралдарға жеке себеп-салдар тізбегі керек

Tool call жай ғана finish reason емес. Ол бүкіл операцияның түрін өзгертеді: модель құрал шақыру ниетін береді, қолданба әрекетті орындайды, содан кейін көбіне нәтижемен модельге қайта жүгінеді. Мұны бір span-ға қыссаңыз, жалпы кідірісті көресіз, бірақ уақыттың нақты қайда кеткенін және қатені кім қайтарғанын түсінбейсіз.

Пайдаланушы операциясына ата-аналық span, ал модельге жүгінулер мен құралдарды орындауға еншілес span жасаңыз. Бір құрал іске қосылғанда мына атрибуттар жеткілікті:

llm.tool.name
llm.tool.call_id
llm.tool.type
llm.tool.attempt
llm.tool.outcome
llm.tool.duration_ms
llm.tool.argument_size_bytes
llm.tool.result_size_bytes

Егер трассировка бэкенді мұны қолдаса және атаулар саны шектеулі болса, құрал атауын span name ретінде қоюға болады. OpenTelemetry-дің GenAI келісімдері tool call орындау операциясы үшін құрал атауына қойылатын талапты күшейтті. Бірақ span атауына тапсырыс идентификаторын, пайдаланушыны немесе файл жолын қоспаңыз. Бұл кардиналдылықтың күрт өсуіне әкеледі.

Құрал аргументтері мен нәтижелері атрибуттарға дерлік ешқашан жарамайды. Оларда мекенжайлар, құжат нөмірлері, SQL, клиент деректері немесе ішкі базадан алынған тұтас беттер болуы мүмкін. Өлшемін, түрін, хэшін және қорғалған диагностикалық объектіге сілтемесін сақтаңыз. Инженерге нақты payload керек болса, оны жалпы observability экранынан емес, trace ID арқылы тексерілетін рұқсатпен сұратуы тиіс.

tool_requested, tool_executed және tool_rejected мәндерін ажыратқан пайдалы. Біріншісі модель әрекет сұрағанын білдіреді. Екіншісі қолданба әрекетті іске қосқанын білдіреді. Үшіншісі саясат, схема валидациясы немесе пайдаланушы орындауды тоқтатқанын білдіреді. Көп команда осы үш жағдайдың бәрін «tool error» деп жазады да, модель сапасы туралы қате қорытынды жасайды.

Бір әрекеттегі қате операцияны әрдайым сәтсіз етпейді

LLM шақыруында кемінде үш нәтиже деңгейі бар: тасымалдау әрекеті, провайдер шақыруы және пайдаланушы операциясы. 400 миллисекундтан кейін сәтті қайталанған алғашқы әрекеттегі HTTP 429 - әрекет қатесі. Ол пайдаланушы операциясының қатесі емес.

OpenTelemetry қате жоқ сәтті аяқталғанда span күйін unset күйінде қалдыруды, ал операция қателікпен аяқталғанда error.type бірге Error орнатуды ұсынады. Сол ұсынымдарда қайталанған немесе өңделген, сондықтан операция қалыпты аяқталған қателерді span-ға жазбау керектігі де көрсетілген.

Практикалық схема мынадай:

• Әр әрекеттің еншілес span-ы желі қатесімен, timeout-пен, 429-мен немесе клиент сәтсіз деп санайтын жауаппен аяқталса, Error алады.
• LLM операциясының ата-аналық span-ы барлық рұқсат етілген әрекеттер мен fallback сәтсіз аяқталғанда ғана Error алады.
• Ата-аналық span-тағы llm.retry оқиғасы себепті, әрекет нөмірін және күту кідірісін тіркейді, бірақ жауаптың толық мәтінін қамтымайды.
• error.type мәнін шектеулі сөздіктен алыңыз: rate_limit, timeout, network, auth, invalid_request, provider_unavailable, content_policy, tool_failure.

Провайдер қатесінің жолын error.type ішіне салмаңыз. Хабарлама сұраудан сұрауға өзгереді, кейде промпт үзіндісін қамтиды, ал мыңдаған бірегей жолды агрегациялау мүмкін емес. Мәтінді қорғалған диагностикалық объектіде қалдыруға болады. Ұсталмаған exception үшін OpenTelemetry exception атауымен оқиға жасауды және түрін, хабарламасын әрі stack trace көрсетуді ұсынады. Оны exception операцияны шынымен аяқтайтын жерде бір рет жазыңыз, wrapper-лердің әр қабатында қайталамаңыз.

Пайдаланушының бас тартуын бөлек белгілеңіз. cancelled мен timeout бірдей емес, content_policy мен provider_unavailable де бірдей емес. Бұл нәтижілердің жауапты иелері мен әрекеттері бөлек: интерфейс бас тартуды түзете алады, промпт командасы policy-ді тексереді, ал SRE қолжетімсіздікпен айналысады.

Бастапқы payload-ты бөлек және түсінікті қолжетімділік саясатымен сақтаңыз

«Debug үшін бәрін сақтайық» деген ой әдетте индекстелетін атрибуттарда жеке деректердің пайда болуына, қымбат қоймаға және әзірлеушілерге трассировкаларға қауіпсіз қолжетімділік бере алмауға әкеледі. Толық payload сирек керек, бірақ күрделі инциденттерде ол шынымен қажет болуы мүмкін. Сондықтан оны бөлек сақтап, жоқ сияқты көрсетпеңіз.

Жұмыс схемасы қарапайым. Сұрауды жібермей тұрып адаптер диагностикалық объект жасайды, белгілі PII өрістерін маскалайды, өлшемін шектейді және нәтижені қорғалған объектілік қоймаға сақтайды. Span ішінде ол тек request_ref, SHA-256, өлшемді, сезімталдық санатын және маскалау нәтижесін береді. Жауаптан кейін дәл осы әрекет response үшін де орындалады.

Атрибуттарға мысал:

{
  "llm.raw.request_ref": "obs://llm/2026/07/23/ab12/request",
  "llm.raw.request_sha256": "a63b...",
  "llm.raw.request_bytes": 18422,
  "llm.raw.response_ref": "obs://llm/2026/07/23/ab12/response",
  "llm.raw.redaction": "pii_masked",
  "llm.raw.retention_class": "debug_7d"
}

request_ref рұқсат тексерілмей браузерден ашылатын URL болмауы керек. Бұл диагностикалық қызметіңіз trace ID, рөл және қолжетімділік себебі бойынша ашуға рұқсат беретін идентификатор. Ерекше сезімтал ағындарда payload мүлде сақтамаңыз: ұзындығын, хэшін, операция түрін, промпт нұсқасын және токен есептегіштерін қалдырыңыз. Хэш мәтінді қалпына келтірмейді, бірақ екі сұраудың бірдей болғанын дәлелдеуге көмектеседі.

Промпт мазмұнын OpenTelemetry GenAI атрибуттарына ойланбастан жазудың қажеті жоқ. GenAI келісімдерінде контентті түсіру өшірулі тұрса, кіріс және шығыс хабарламаларының жаңа өрістері әдепкі бойынша жазылмайды. Бұл жетіспейтін мүмкіндік емес, дұрыс сақтық шарасы.

Бір trace бір пайдаланушы сұрағына жауап беруі керек

Пайдаланушы бір әрекет жасағанда әр SDK шақыруына бөлек trace жасамаңыз. Ата-аналық trace сұрау, кезек тапсырмасы немесе фондық процесс шекарасынан басталып, бүкіл жол бойындағы контексті сақтауы керек: retrieval, маршрут таңдау, LLM шақырулары, tool calls, жауапты тексеру және нәтижені жазу.

LLM бөлігі үшін мынадай иерархияны қолданар едім:

POST /support/reply
  llm.workflow support_reply
    llm.route select_model
    gen_ai.chat attempt=1
    llm.tool.execute search_customer
    gen_ai.chat attempt=2
    llm.output.validate

llm.workflow «пайдаланушы нені көрді?» деген сұраққа жауап береді. gen_ai.chat «нақты модель шақыруы не істеді?» деген сұраққа жауап береді. llm.route «неге дәл осы орындалу таңдалды?» деген сұраққа жауап береді. Бұл нысандарды бір үлкен span-ға араластырмаңыз, әйтпесе оның өрістері соңғы әрекетпен үнемі қайта жазылады.

Метрикалар сол схема үстіне құрылады, бірақ trace-ті алмастырмайды. Метрикаларда ұзақтықтың p50, p95 және p99 мәндерін, error.type бойынша қателер үлесін, түрі бойынша токендерді, құнды және fallback үлесін бақылаңыз. Traces ішінде бір сұрауды зерттеңіз: қандай контекст келді, қандай маршрут тармағы іске қосылды, құрал қанша уақыт алды және қате қайда пайда болды.

Стандартты gen_ai.client.token.usage метрикасы токен түрін атрибут ретінде қолданады және есептегіштер қымбат шамалаусыз қолжетімді болса, оны жіберуді ұсынады. «Жалпы токендер» деп бір histogram жіберіп, одан шығын құрылымын кейін болжауға тырыспаңыз.

Провайдер адаптері қарапайым әрі тексерілетін болуы керек

Адаптер пайдаланушы сценарийінің сәтті болғанын, payload қанша сақталатынын немесе команда бюджетін қалай есептеу керегін шешпеуі тиіс. Оның міндеті қарапайым: провайдердің сұрауы мен жауабын алу, белгілі өрістерді шығару, өлшемдерді келісімге келтіру және жауапта не болмағанын хабарлау.

Адаптерді бекітілген мысалдармен тексеріңіз. Бір мысалда usage бар кәдімгі жауап болсын. Екіншісінде usage тек соңғы фрагментте келетін stream жауабы болсын. Үшіншісінде cache hit және cache creation болсын. Төртіншісінде tool call болсын. Бесіншісінде сәтті қайталанған 429 болсын. Алтыншысында басқа модельге fallback болсын. Бұл мысалдарсыз команда әдетте тек happy path-ты тексереді де, кейін дәл қымбат немесе проблемалы шақыруларды айлап қате есептейді.

Төмендегі нормализация функциясын SDK-дан тәуелсіз контракт тестерімен тексеруге болады:

def normalize_usage(raw: dict) -> dict:
    usage = raw.get("usage") or {}
    return {
        "llm.usage.input_tokens": usage.get("input_tokens"),
        "llm.usage.output_tokens": usage.get("output_tokens"),
        "llm.usage.reasoning_output_tokens": usage.get("reasoning_tokens"),
        "llm.usage.cache_read_input_tokens": usage.get("cache_read_tokens"),
        "llm.usage.cache_creation_input_tokens": usage.get("cache_write_tokens"),
        "llm.usage.source": "provider" if usage else "unavailable",
    }

Бұл код жоқ мәндерді нөлге ауыстырмайды және total_tokens мәнін өздігінен есептемейді. Нақты адаптерде API мағынасын тексеріңіз: кей жауаптар толық input береді, кейбірі тек бөліктерді береді, ал байланыс үзілгенде stream финалдық usage-сыз аяқталуы мүмкін.

Команда OpenAI-үйлесімді шлюз ретінде AI Router қолданса, клиенттің бастапқы моделін және маршрут нақты таңдаған модельді бөлек атрибуттарға жазған пайдалы. Бұл дашбордтарды бір провайдердің форматына байламай, қолданба коды мен нақты орындалу арасындағы байланысты сақтайды.

Схема нұсқасы әдемі өрістер жиынтығынан маңызды

Телеметрия схемасы өзгереді. Жаңа токен түрлері, сервер құралдары, retrieval, multimodal енгізу және жаңа маршрутизация себептері қосылады. Бұл келісімсіз еркін JSON қолдануға себеп емес. Бұл нұсқа мен көшу тәртібі керек дегенді білдіреді.

Әр жазбаға llm.schema.version жазыңыз. Жаңа өрістерді ескі тұтынушылар жұмысын жалғастыратындай қосыңыз. Бар өрістің мағынасын өзгертуді, аты өзгермесе де, үйлесімсіз өзгеріс деп санаңыз. Егер input_tokens енді «барлық кіріс» емес, «кэштелмеген токендер» дегенді білдірсін десеңіз, жаңа өріс жасап, көшу кезеңін енгізіңіз. Әйтпесе тарихи график әртүрлі нәрселерді салыстыра бастайды.

Аптасына бір рет құны жоғары он trace, қателері бар он trace және fallback қолданылған бірнеше trace алыңыз. Оларды қолмен қарап шығыңыз: қай модель сұралғаны, не орындалғаны, токендер неден құралғаны, ақша қайдан шыққаны және шақыру неге солай аяқталғаны түсінікті ме? Осы сұрақтардың кез келгеніне жауап беру үшін адаптер бастапқы кодына кіру керек болса, схемаңыз әлі дайын емес.

Жақсы LLM телеметриясы әр байтты сақтауға да, болашақтағы барлық API-ді алдын ала болжауға да міндетті емес. Ол ниетті орындалумен, белгісіздікті нөлмен, әрекет қатесін пайдаланушы қатесімен және техникалық есептегішті ақша есебімен шатастырмауы керек. Келесі модель ауысымынан кейін барлық есепті соқыр түрде жөндемей өтуге осының өзі жеткілікті.