Агентке неге басқа бақылану үлгісі керек
Кәдімгі API сұрауында басталу, өңдеуші және жауап анық болады. AI агенті цикл қосады. Ол модельді таңдайды, құрал шақыру керегін шешеді, қашықтағы жүйені күтеді, нәтижені оқиды және модельге қайта жүгінуі мүмкін. Бір пайдаланушы сұрауында бірнеше модель шақыруы, іздеу сұрауы, құрал орындауы, қайталап көруі және саясат тексеруі болуы ықтимал. «Сұрау сәтсіз аяқталды» деген бір журнал жазбасы уақытты немесе бюджетті қай тармақ жұмсағанын көрсетпейді.
Бақылану осы жолды байланысқан трейстер, метрикалар және журналдар арқылы көрнекі етеді. OpenTelemetry тресті сұраудың жолы, ал span сол жолдағы операция деп сипаттайды. Пайдаланушы көретін агент іске қосылуына бір түбір span, модель инференсіне, retrieval-ге, құралдарға, қорғаныс тексерулеріне және сериализацияға бала spans жасаңыз. Модельдер мен құрал атауларының кардиналдылығы төмен болсын. Сұрауға тән идентификаторларды трейс контекстіне немесе құрылымдалған журналға салыңыз, метрика белгісіне емес. Сонда оператор бір іске қосылуда не болғанын, бұл қаншалықты жиі қайталанатынын және қай workflow әсер алғанын бөлек көре алады.
Бұл мақала провайдерге тәуелсіз сызбаны қолданады. Нақты usage өрістері мен төлем ережелерінің дереккөзі провайдердің құжаттамасы болып қала береді. OpenTelemetry GenAI span келісімдері және GenAI метрика келісімдері өзгеріп жатқан интеграцияларға ортақ сөздік береді.
Агент циклін көтеретін trace schema
Түбір span-ды қолданба сұрауды қабылдаған сәтте жасаңыз, бірінші модель шақыруын күтпеңіз. Операция атауы invoke_agent сияқты болсын. Service, deployment, environment, workflow нұсқасы және сезімтал емес tenant класы атрибуттарын қосыңыз. Conversation ID тек бар болса және retention саясаты рұқсат етсе жазылсын. Пайдаланушы хабарын, толық prompt-ты немесе құрал payload-ын метрика белгісіне салмаңыз.
Әр бала span бір операциялық сұраққа жауап берсін. Пайдалы ең аз жиынтық:
| Span | Не жазу керек |
|---|---|
| agent.run | workflow атауы мен нұсқасы, нәтиже, әрекет саны, ұзақтық |
| gen_ai.inference | провайдер, сұралған және жауап моделі, операция, streaming, аяқталу себебі, токендер |
| gen_ai.retrieval | индекс не дереккөзі класы, сұрау режимі, нәтиже саны, cache hit |
| gen_ai.tool | құрал атауы мен түрі, авторизация шешімі, timeout, нәтиже |
| guardrail.check | саясат нұсқасы, шешім, себеп коды, ұзақтық |
Сәтсіз операцияда span status және error.type орнатыңыз. Қайталап көру үшін нөмір, backoff ұзақтығы және себеп коды бар уақыт белгіленген event жазыңыз. Retry екінші түбір іске қосылу емес. Ол сол логикалық операцияның тағы бір әрекеті, желіге сұрау жіберілгенде жеке client span-мен белгіленеді. Бұл дашбордтың пайдаланушы сұрауларын екі рет санауына жол бермейді және провайдер әрекеттерін көрсетеді.
Келесі JSON экспортталатын жазбаның мысалы ғана, белгілі бір провайдердің payload форматы емес. Мұнда мазмұн емес, санауыштар мен кодтар бар.
{
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"span_id": "00f067aa0ba902b7",
"parent_span_id": "b7ad6b7169203331",
"name": "chat model",
"kind": "CLIENT",
"status": "OK",
"attributes": {
"gen_ai.operation.name": "chat",
"gen_ai.provider.name": "provider.example",
"gen_ai.request.model": "model.example",
"gen_ai.response.model": "model.example-2026-01",
"gen_ai.usage.input_tokens": 820,
"gen_ai.usage.output_tokens": 146,
"gen_ai.response.finish_reasons": ["stop"],
"app.agent.attempt": 1
}
}
Span атауы операция класын сипаттасын, ID немесе пайдаланушы мәтінін емес. Semantic convention нұсқасын instrumentation метадеректерінде сақтаңыз. Провайдер есептелетін және өңделген токендерді бөлек берсе, екеуін ішкі есепте сақтап, құн үшін есептелетін санды пайдаланыңыз. Бір сұраудың client және server instrumentation деректерін қабаттарын белгілемей қоспаңыз, әйтпесе токендер екі рет саналады.
Correlation ID және контекст тарату
Trace ID сервистерді байланыстырады. Span ID бір операцияны білдіреді. Қолданбадағы request ID қолдау үшін пайдалы, бірақ trace context орнына жүрмейді. W3C traceparent тақырыбын API gateway, агент сервисі, retrieval сервисі және құрал адаптерлері арқылы таратыңыз. OpenTelemetry контекст тарату нұсқаулығы қашықтағы контексті шығарып, бала span жасауды түсіндіреді. Сол контексті құрылымдалған журналға қосып, жазбадан трейске өтуге болады.
Қолдауға қысқа идентификатор керек болса, бөлек кездейсоқ request ID жасаңыз. Оның trace ID-мен сәйкестігін жоғары кардиналды метрикада емес, журналда сақтаңыз. Queue үшін контексті хабар метадеректеріне енгізіп, өңдеу кезінде consumer span жасаңыз. Бір ата-анасы жоқ параллель жұмыстарда span links пайдаланыңыз. Ашық шекарада келген tracing header-лерін сенімсіз дерек деп тексеріңіз және ішкі baggage-ті провайдерге немесе сыртқы құралға жібермеңіз. Baggage ішінде credentials не жеке дерек болуы мүмкін.
Құрал spans агенттің нақты әрекетін көрсетеді
Айырмашылық пайдалы болса, модель шешімі мен қолданба орындауын бөлек белгілеңіз. Модель span құрал сұралғанын, ал құрал span қолданбаның нақты не орындағанын көрсетеді. Құрал span-ында тұрақты tool.name, function, extension немесе datastore түрі, саясат шешімі және сыртқы операция болсын. Құпия ашылмайтын болса ғана request әдісін не сұрау класын қосыңыз. Access token, SQL параметрлері, құжат мазмұны немесе query бар толық URL сақталмасын.
Әр құрал шақыруында басталу мен аяқталу уақытын, timeout конфигурациясын, нәтиже класын, retry санын және шектелген нәтиже көлемін жазыңыз. Timeout, бизнес бас тартуы, саясат тыйымы және upstream 5xx әртүрлі себеп кодтарына ие болуы керек. Құрал басқа сервиске жүгінсе, контексті таратыңыз. Жергілікті команда орындалса, тек команда тобын және шығу класын жазыңыз, пайдаланушы енгізуін емес.
Құрал шақыруына жатпайтын күтуді де көрсетіңіз. Queue кідірісіне, rate-limit ұйқысына, ашық circuit breaker-ге және streaming жауабына spans қосыңыз. Әйтпесе модель span-ының уақыты concurrency слотының күтуін жасыруы мүмкін. Multi-agent workflow-та әр делегацияланған workflow-ға атау беріп, оны ата-аналық трейске байланыстырыңыз. Әр ішкі ойға немесе күй ауысуына жаңа трейс жасамаңыз.
Токендер мен құнды есептеу
Провайдер жауабында usage болғанда, соны есептің негізі етіңіз. Input, output, cached және reasoning токендерінің, суреттер мен құрал бірліктерінің бағалары әртүрлі болуы мүмкін. OpenAI токендер нұсқаулығы tokenization модель мен тілге байланысты екенін және аяқталған сұрау үшін жауаптағы usage объектісі сенімді екенін түсіндіреді. Жергілікті tokenizer алдын ала бюджет бағалайды, бірақ провайдер usage-ін алмастырмайды.
Әр модель әрекеті үшін provider, requested model, response model, token category, count, currency, pricing-table version және cost center сақтаңыз. Жауаптан кейін мынадай есеп қолданылады:
cost = input_billable_tokens * input_price
+ cached_input_tokens * cached_input_price
+ output_billable_tokens * output_price
+ provider_units * unit_price
Бағалар effective date бар конфигурация болсын, exporter ішіне жазылған тұрақты мән емес. Шикі сан мен есептелген соманы сақтап, кейінгі прайс түзетуін тексеруге мүмкіндік беріңіз. Барлық әрекеттерді қосыңыз, өйткені сәтсіз шақыру да токен жұмсауы мүмкін. Баға кешігіп не болжамды келсе, соманы уақытша деп белгілеп, провайдер есебімен салыстырыңыз.
Иесі өзгерте алатын өлшемдерді көрсетіңіз: workflow, модель отбасы, орта, tenant класы және нәтиже. User ID, prompt немесе еркін құрал аргументтерін метрика өлшемі етпеңіз. Құн дашборды жалпы соманы, аяқталған іске қосу құнын, іске қосуға шаққан токендерді, retry үлесін және қымбат модель үлесін көрсетсін. Зиянсыз кідірістегі output токендерінің өсуі шектелмеген жауапты, циклді немесе өзгерген prompt-ты білдіруі мүмкін.
Кідіріс үлестірімдері: p50, p95 және p99
Орташа мән queue күтуі немесе баяу құрал кезіндегі пайдаланушы көретін құйрықты жасырады. Түбір run және маңызды spans ұзақтығын секундпен histogram ретінде жазыңыз. Time to first token, streaming бөліктері арасындағы уақыт және толық аяқталу уақытын өлшеңіз. Провайдер бергенде server, queue және network уақытын бөліңіз.
p50 әдеттегі жағдайды, p95 баяу пайдаланушыларды, p99 сирек ауыр құйрықты көрсетеді. Бұлар үлестірім квантильдері, үш орташа емес. Нақты SLO-ға сәйкес секундтың бөліктерінен минуттарға дейін bucket таңдаңыз және өлшем бірлігін бірізді ұстаңыз. Prometheus histogram_quantile функциясы bucket-тен квантильді бағалайды. Классикалық histogram үшін алдымен le бойынша агрегаттаңыз.
histogram_quantile(
0.95,
sum by (le, workflow) (
rate(agent_run_duration_seconds_bucket[10m])
)
)
Trace ID-ді метрика белгісіне салмаңыз. Кідірісті workflow, модель отбасы, аймақ және нәтиже сияқты басқарылатын аз өлшемге бөліңіз. Trace үлгісі p95 неге өзгергенін түсіндіреді. Параллель бала spans ұзақтығын қоспаңыз, trace ішіндегі critical path-ты пайдаланыңыз.
Қателер, retry және rate limit
Alerts жасамай тұрып қате таксономиясын анықтаңыз. Client validation, саясат бас тартуы, authentication, rate limit, timeout, upstream server error, қате модель жауабы, құрал ақауы және cancellation бөлек болсын. Провайдер кодтарын тұрақты кластарға бейімдеп, шектелген түпнұсқа кодты сақтаңыз. Пайдаланушының күтілетін cancellation-ын сервер ақауынан ажыратыңыз.
Әр retry-де себеп, әрекет нөмірі, backoff және соңғы нәтиже болуы керек. Контракт рұқсат етсе ғана jitter бар шектелген exponential backoff қолданыңыз. Validation, authorization, саясат шешімі немесе детерминдік schema қатесін қайталамаңыз. Толық агент іске қосылуына және әр әрекетке deadline қойыңыз. Түбір span retry_count, attempt_count және соңғы нәтижені хабарлайды, әр әрекет өз status-ын сақтайды. Retry көп болса, табыс пайызы жақсы болғанда да құн өседі.
Fallback модель таңдауын event не span ретінде жазыңыз. Дашборд rate limit, latency, safety policy және capability check себептерін бөлуі керек. Құралдың бұзылған аргументтері мен schema repair циклдерін бөлек бақылаңыз. Repair рұқсат етілсе, итерация санын шектеп, шекке жеткенде loop_limit шығарыңыз.
Құпиялылық, редакциялау және sampling
Prompt пен құрал деректері жеке, құпия немесе security-sensitive ақпарат ұстауы мүмкін. Қауіпсіз әдепкі мән — мазмұнсыз metadata, token counters, fingerprint және себеп кодтары. Debugging үшін мысал керек болса, consent, қысқа retention, encryption, access log және field-level redaction бар бөлек басқарылатын сақтау орнын пайдаланыңыз. Деректі export-қа дейін редакциялаңыз.
Attribute allowlist қолданыңыз. Authorization header, cookie, API key, байланыс деректері, шот нөмірі, query бар URL және құжат мәтінін алып тастаңыз. Hashing деректі автоматты түрде аноним етпейді. Prompt fingerprint-ті prompt-тан бөлек сақтап, кім байланыстыра алатынын құжаттаңыз. Редакциялауды шынайы құпиялар мен көптілді жеке дерек бар fixtures арқылы тексеріңіз.
Sampling көлемді азайтады, бірақ инцидентті жасырмауы тиіс. Trace дәйектілігі үшін parent-based sampling қолданыңыз. Collector ішінде tail sampling арқылы қате, timeout, қымбат және баяу traces сақталып, қалыпты сәтті іске қосулар аз мөлшерде алынсын. OpenTelemetry sampling спецификациясы recording пен export-ты ажыратады, сондықтан жергілікті sampler қымбат атрибуттарды жасамай қоя алады. Метрикаларды sampling жасамай сақтаңыз, traces-ті investigation үшін қолданыңыз.
OpenTelemetry, Grafana және Sentry бірге
Агентке OpenTelemetry API мен semantic conventions қосып, OTLP-ті OpenTelemetry Collector-ге жіберіңіз. Collector batching, memory limit, redaction, sampling және routing атқарсын. Traces, metrics және logs-ты сәйкес backends-ке бірдей service, version, environment, region және deployment атрибуттарымен экспорттаңыз. Production sampling-ке дейін staging ортада бір толық тресті тексеріңіз.
Grafana ортақ операциялық көрініс береді. Volume, success ratio, түбір latency p50/p95/p99, first-token уақыты, токендер, estimated cost, retry rate, құрал ұзақтығы және провайдер күйі панельдерін жасаңыз. Панельдерді trace search және runbook-қа байланыстырыңыз. Grafana alert rules құжаттамасы query, condition, evaluation period және notification ұғымдарын сипаттайды. Sentry issue grouping, error context және trace inspection қосады. Оның Trace API бір трейстің spans және errors деректерін береді. Қай error backend қолданылса да тек редакцияланған дерек жіберіп, sampling-ті ашық баптаңыз.
Операторға пайдалы SLO және alerts
SLO Collector денсаулығын емес, пайдаланушыға көрінетін уәдені білдіруі керек. Availability-ді server, provider немесе tool error жіктелмей аяқталған run үлесі ретінде анықтаңыз. Latency-ді таңдалған шектен төмен түбір run үлесі ретінде есептеңіз. Құн өнімге шектеу болса, budget SLI-ді бөлек бақылаңыз.
Мақсаттарды өлшенген baseline мен өнім талабынан таңдаңыз. Күтілетін latency немесе correctness-і әртүрлі workflow-ларды бөліңіз. Error budget-ті ұзақ терезеде, ал deploy үшін қысқа diagnostic view-да көрсетіңіз. Grafana SLO құжаттамасы SLI query, budget consumption, fast-burn және slow-burn alerts туралы түсіндіреді. Оператор әрекет ете алғанда ғана page жасаңыз. Баяу trend ticket-ке айналсын.
Пайдалы alerts: root run қателерінің тұрақты өсуі, error budget-тің жылдам жұмсалуы, контракттан жоғары p95, provider rate limit серпіні, retry ratio өсуі, missing usage record, күтпеген cost rate және тұрып қалған queue. Alert-ке workflow, region, deployment, current value, threshold, trace search link, owner және runbook қосыңыз. Pending period жалғыз үлгінің page жасауына жол бермейді. Хабарларды service және severity бойынша топтаңыз. Дереу әрекет жоқ болса, alert емес, панель керек.
Белгіден себепке дейінгі ақау іздеу
SLO немесе пайдаланушы хабарынан бастап, бір representative trace таңдаңыз. Түбір span-ның бала spans толық екенін және gateway, queue, tool boundary арқылы context тарайтынын тексеріңіз. Spans жоғалса, application code-қа тимей тұрып exporter, sampling decision және context injection күйін қараңыз.
Баяу run үшін queue delay, first-token time, output duration, retrieval және tool critical path салыстырыңыз. Қалыпты p50 кезінде жоғары p99 көбіне tail dependency, concurrency limit немесе retry-ге нұсқайды. p50 жылжуы deployment, model, prompt немесе region өзгерісін білдіруі мүмкін. Cost серпінінде response model, token category, workflow version және attempts бойынша топтап, usage-ті провайдер есебімен салыстырыңыз.
Қате кезінде wrapper exception-нан емес, бірінші failed span-нан бастаңыз. Status, error.type, provider code, timeout budget және retry events қараңыз. Tool rejection, provider outage, malformed model response және parser bug айырмасын белгілеңіз. Redaction қауіпсіз diagnostic code-ты өшірмегенін тексеріңіз. Күтілетін policy block-ты product outcome деп санаңыз да, оның үлесі күтпеген өзгергенде ғана alert жасаңыз.
Сезімтал емес, детерминдік fixtures қолданатын synthetic request жиынтығын ұстаңыз. Instrumentation, model, prompt немесе routing өзгергеннен кейін traces, metrics, token records және errors бір correlation ID арқылы келгенін тексеріңіз. Архитектуралық контекст үшін production AI agent architecture, AI agent evaluations, prompt injection and MCP security және hybrid RAG with pgvector материалдарын қараңыз. Бұл тақырыптар қандай spans керек екенін және SLO шегін анықтайды, ал бақылану бейтарап дәлел қабаты болып қалады.