Телеметрияны аяқтауды соңғы сигналға қалдырмаңыз

Процесс тоқтағанда жоғалған span көбіне span-ның өзіндегі қатені білдірмейді. Әдетте қолданба end() әдісін дұрыс шақырады, SDK нәтижені кезекке салады, ал оркестратор бір секундтан кейін процесті сол кезекпен бірге жояды. Backend-та бұл трассадағы кездейсоқ бос орын сияқты көрінеді. Шын мәнінде, бұл қолданбаның өмірлік циклі мен exporter өмірлік циклі арасындағы алдын ала болжанатын жарыс.

Телеметрияны аяқтауды штаттық shutdown процесінің бөлігі ретінде жобалау керек. Оны релиз алдындағы соңғы кеште SIGTERM өңдегішіне қосуға болмайды. Бұл HTTP сервистеріне, consumer процестеріне, cron тапсырмаларына, миграцияларға және қысқа LLM тапсырмаларына бірдей қатысты. Олардың тоқтау жолы әртүрлі, бірақ ортақ бір жағымсыз белгісі бар: процесс телеметрия жадтан шыққанға дейін жойылып кетуі мүмкін.

end() өлшеуді аяқтайды, жеткізуді емес

span.end() шақыруы аяқталу уақытын белгілеп, span-ды процессорлар тізбегіне береді. Бұл backend деректерді алып қойды деген сөз емес. Пакетпен өңдеу кезінде осы екі оқиғаның арасында жадтағы кезек, жіберу таймері, сериализация, желі сұрауы, қабылдаушының жауабы және кейде collector-дің тағы бір кезегі болады.

Бұл айырмашылықты тәжірибелі командалардың өзі жиі елемейді. Олар «span-дарды жабамыз» дейді, бірақ «агент оларды бір кезде жібереді деп үміттенеміз» дегенді меңзейді. Ұзақ жұмыс істейтін процесте мұндай үміт кейде ақталады: бірнеше секундтан кейін келесі batch жіберіледі. Ал 400 миллисекунд жұмыс істеп, аяқталған командада күтуге уақыт жоқ.

OpenTelemetry спецификациясы бұл кезеңдерді нақты бөледі. Процессордың OnEnd әдісі Span.End кезінде синхронды шақырылады, бірақ BatchSpanProcessor дайын span-дарды кейін жинақтайды. Спецификацияда және SDK ортасының айнымалыларында көрсетілген әдепкі мәндер тұзаққа айналуы мүмкін: жіберулер арасындағы кідіріс 5 секунд, кезектің ең үлкен көлемі 2048, пакет көлемі 512, ал экспорт тайм-ауты 30 секунд.

Контейнеріңіз SIGTERM алып, 10 секундтық grace period қолданса, тоқтаудың басында аяқталған span жоспарлы flush-ты 5 секунд күтуі мүмкін. Содан соң exporter желіні процестің өмірінен ұзақ күтуі ықтимал. Мұнда телеметрия «кейде жоғалмайды». Мұнда бір-біріне қайшы таймерлер алдын ала қойылған.

Аяқталмаған span-дарға да бөлек назар аударыңыз. Код сигнал алып, бірден шықса, белсенді HTTP сұраулары, дерекқор операциялары және модель шақырулары өздерінің end() әдістеріне жетпеуі мүмкін. Flush процессор ешқашан алмаған деректерді сақтай алмайды. Алдымен жаңа жұмыстың келуін тоқтатып, ағымдағы жұмыстың аяқталуына немесе саналы түрде тоқтатылуына мүмкіндік беріңіз.

BatchSpanProcessor-ге уақыт болғанша ыңғайлы

Пакеттік процессор production ортасында дерлік әрдайым керек. Ол желі сұрауларының санын азайтып, қолданба ағындарын exporter кідірісінен қорғайды. «Ештеңе жоғалмасын» деп бүкіл сервисті синхронды SimpleSpanProcessor-ге ауыстыру оңай шешім сияқты көрінеді. Бірақ бұл көбіне мәселені сұрау latency-іне ауыстырып, қабылдаушы баяу болғанда қателердің көбеюіне әкеледі.

BatchSpanProcessor бір маңызды шартпен жұмыс істейді: кезек босап үлгеретіндей процесс жеткілікті ұзақ жұмыс істеуі керек. Ол мерзімді таймер іске қосылғанда, кезек пакет көлеміне жеткенде немесе шақырушы flush сұрағанда пакет жібереді. Кезек толса, жаңадан аяқталған span-дарды тастай бастайды. Shutdown басталғаннан кейін жасалған span-дар да жоғалуы мүмкін.

OpenTelemetry-дің self-observability семантикалық келісімдерінде эксплуатацияда пайдалы бір деталь бар. Толған кезек үшін queue_full мәнін, ал процессор жабылғаннан кейін аяқталған span-дар үшін span өңдеу метрикасындағы error.type өрісінде already_shutdown мәнін қолдану ұсынылады. Бұл метриканы қолдау SDK нұсқасы мен тіліне байланысты, бірақ оны тексеру бақыланатын сигналдар тізіміне енуі керек.

Екі түрлі жоғалтуды шатастырмаңыз:

• queue_full қолданба процессор өңдегеннен тезірек аяқталған span жасағанын білдіреді.
• Exporter тайм-ауты немесе қатесі процессор деректерді алғанымен, бөлінген уақытта жіберуді аяқтамағанын білдіреді.
• already_shutdown SDK-ны жауып қойғаннан кейін де код жұмыс істеп, span аяқтағанын білдіреді.
• span.end() болмауы қолданба операциясының қалыпты аяқталуға жетпегенін көрсетеді.

Бұл қателердің жауапты иелері әртүрлі. already_shutdown кезінде кезекті үлкейту мағынасыз. Кезек толғанда exporter тайм-аутын арттыру да көмектеспейді. Алдымен жоғалтудың түрін атаңыз, содан кейін баптауды өзгертіңіз.

Shutdown жұмысты тоқтатқаннан кейін жүруі керек

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

HTTP сервисі үшін реттілік әдетте мынадай:

1. SIGTERM немесе басқа тоқтату сигналын алып, процесті draining күйіне ауыстырыңыз.
2. Readiness күйін өшіріп, балансерден жаңа қосылымдар мен тапсырмаларды қабылдауды тоқтатыңыз.
3. Белсенді сұрауларды алдын ала таңдалған дедлайнға дейін күтіңіз, содан кейін қалған контекстерді тоқтатыңыз.
4. Span жасай алатын consumer-лерді, пулдарды және фондық орындаушыларды жабыңыз.
5. Телеметрия provider-ін жеке тайм-аутпен shutdown жасап, нәтижесін тексеріңіз.

Үшінші тармақты «біраз күтейік» деп алмастыруға болмайды. Белсенді жұмыс бірліктерінің санын есептеңіз. HTTP-та бұл сұраулар, кезекте хабарламалар, batch pipeline-да worker алып қойған элементтер. Shutdown сигналы осы есептегішті азаю режиміне ауыстырады. Ол нөлге жеткенде немесе дедлайн біткенде телеметрияның аяқталуына болады.

Go тілінде defer tp.Shutdown(ctx) main ішінде тұрып, main қате тармағында os.Exit(1) шақыратын үлгі өте қауіпті. os.Exit deferred функцияларды орындамайды. Node.js-та осындай қате exception өңделгеннен кейін бірден process.exit(1) шақыру болып көрінеді. Java-да Runtime.getRuntime().halt() shutdown hook-тарын айналып өтеді. Бұл үш нұсқа бұзылған процесс үшін орынды болуы мүмкін, бірақ қалыпты басқару тармағына айналмауы тиіс.

Мына Go қаңқасында реттілік анық көрінеді. Ол нақты exporter-ге тәуелді емес, бірақ дедлайнның қайда болуы керегін көрсетеді:

rootCtx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
defer stop()

<-rootCtx.Done()

server.SetReady(false)
server.StopAccepting()

workCtx, cancelWork := context.WithTimeout(context.Background(), 20*time.Second)
err := workers.Drain(workCtx)
cancelWork()
if err != nil {
    logger.Error("work drain failed", "error", err)
}

telemetryCtx, cancelTelemetry := context.WithTimeout(context.Background(), 5*time.Second)
err = tracerProvider.Shutdown(telemetryCtx)
cancelTelemetry()
if err != nil {
    logger.Error("telemetry shutdown failed", "error", err)
}

Бұл мысал желі толық істен шыққанда жеткізуге кепіл бермейді. Оның басқа мақсаты бар: процесс өз кезегін жіберуге тырыспай тұрып жоймайды және журналда сәтсіздік анық белгіленеді.

Тайм-ауттар grace period ішіне сыйуы керек

Shutdown тайм-аутын кездейсоқ таңдауға болмайды. Ол платформа беретін жалпы уақыт бюджетінің бөлігі. Kubernetes, systemd, контейнерлік runtime, supervisor және serverless орта әртүрлі жұмыс істейді, бірақ соңғы trace-ті жіберіп үлгердіңіз бе, оған ешқайсысы мән бермейді. Сыртқы дедлайн біткенде процесс өмір сүруін тоқтатады.

Бюджетті соңынан бастап есептеңіз. Оркестратор процеске 30 секунд берсін. Балансер трафик жіберуді тоқтатуға 2 секунд, белсенді сұрауларға 18 секунд, consumer-лерге 6 секунд және телеметрияға 4 секунд қажет болуы мүмкін. Бұл әмбебап сандар емес, тек есептеу үлгісі. Егер белсенді операция заңды түрде бір минутқа созылса, 30 секундтық grace period OpenTelemetry-ге қатысы жоқ себеппен-ақ келісіміңізге қайшы келеді.

Exporter-ге толық shutdown-ға қарағанда аз уақыт берілуі керек. Әйтпесе сыртқы дедлайн оны желі шақыруының ортасында тоқтатады. OTEL_BSP_EXPORT_TIMEOUT мәнін terminationGracePeriodSeconds немесе systemd тайм-аутына тең қоймаңыз. Кезеңдер арасындағы ауысуға, код орындалуына және ағындардың жоспарлануына қор қалдырыңыз.

Конфигурация әдетте былай көрінеді:

OTEL_BSP_SCHEDULE_DELAY=1000
OTEL_BSP_EXPORT_TIMEOUT=4000
OTEL_BSP_MAX_QUEUE_SIZE=4096
OTEL_BSP_MAX_EXPORT_BATCH_SIZE=512
APP_DRAIN_TIMEOUT=20s
APP_TELEMETRY_SHUTDOWN_TIMEOUT=5s

OTEL_BSP_SCHEDULE_DELAY мәнін азайту қалыпты жұмыстағы орташа күтуді қысқартады, бірақ жіберу жиілігін арттырады. Бұл шығын мен жүктеме параметрі, дұрыс shutdown-ның орнына жүрмейді. Үлкен кезек қысқа burst кезінде қор береді, бірақ жад жұмсайды және желі өткізу қабілетін арттырмайды. Егер exporter тұрақты түрде қалып жатса, кезек артта қалуды тек ұзағырақ жасырады.

Shutdown-қа беретін контекст тайм-ауты барлық SDK-де ішкі фондық ағындарды бірдей автоматты түрде тоқтатпауы мүмкін. Таңдалған іске асырудың құжаттамасын оқып, оны нақты exporter-мен тексеріңіз. Спецификация Shutdown және ForceFlush сәттілік, қате немесе тайм-аут туралы хабарлай алуы керек дейді, ал нақты API тілге қарай өзгереді.

ForceFlush қысқа процестерге керек, бірақ қауіпті ортада сақтық қажет

OpenTelemetry ForceFlush тек шынымен қажет жерде шақырылуы тиіс екенін нақты айтады және мысал ретінде FaaS ортасын келтіреді: invocation аяқталғаннан кейін орта жоспарлы batch жіберілгенше процесті тоқтатуы мүмкін. Бұл пайдалы бағдар, бірақ әр сұраудан кейін flush жасауға себеп емес.

Ұзақ жұмыс істейтін API сервисінде әр HTTP жауабынан кейін flush жасау пакеттік телеметрияны қымбат синхронды жеткізуге айналдырады. Желідегі жұмыс, соңғы кідіріс көбейеді, ал қабылдаушы істен шыққанда жүз пайыз кепіл бәрібір болмайды. Қалыпты сервис жұмыс кезінде batch-ке, тоқтағанда shutdown-ға сүйенеді.

Қысқа тапсырмада жағдай өзгеше. CSV оқып, сыртқы API шақырып, 200 миллисекундта аяқталатын скрипт бес секундтық немесе бес минуттық жоспарлаушыны ешқашан күтпейді. Ол SDK өмірлік цикліне өзі жауап беруі керек. Барлық жұмыс аяқталған соң Shutdown шақырып, нәтижесін күтіп, содан кейін ғана шығу кодын қайтаруы тиіс.

ForceFlush пен Shutdown мағынасын ажыратыңыз:

• ForceFlush processor-ге берілген деректерді жіберуді сұрайды, бірақ provider-ді жаппайды.
• Shutdown pipeline жұмысын тоқтатады, flush әсерін қамтиды және ресурстарды босатады.
• Shutdown-тан кейін жұмысты қайта іске қосу ескі provider-ге сүйенбеуі керек.
• Flush қатесі әрекеттің аяқталмағанын білдіреді, деректер процестен тыс жерде қауіпсіз сақталғанын емес.

Serverless функциясында экземпляр келесі invocation-ды өңдей алатын және әр шақырудан кейін provider-ді жабу қажет емес жағдайда handler қайтарылмас бұрын ForceFlush шақыруға болады. Бірақ алдымен оның құнын өлшеңіз. Жоғары ағын кезінде бұл әр invocation-ға желі жұмысын қосады. Егер орта әр тапсырмаға жаңа процесс жасаса, provider-ді аяқтау әдетте түсініктірек әрі қауіпсіз.

Фондық тапсырмалар SDK-ны көбіне тым ерте жабады

Тапсырмалар кезегі мен HTTP серверінің тұзақтары әртүрлі. Сервер event loop пен белсенді қосылымдар арқылы процесті ұстап тұрады. Worker хабарлама алып, бірнеше goroutine немесе promise іске қосып, брокерге хабарламаны растауы мүмкін. Содан кейін фондық операциялар әлі жүріп жатса да, тапсырма аяқталды деп есептейді.

Ең жағымсыз нұсқада worker тапсырманың ата-ана span-ын жасап, модельге үш параллель сұрау жібереді, негізгі ағыннан span.end() шақырып, shutdown-қа өтеді. Екі ішкі операция әлі орындалып жатады. Олардың span-дары processor жабылғаннан кейін аяқталуы мүмкін немесе контекст тоқтағанда мүлде аяқталмайды. Бақылау жүйесінде ең қымбат шақырулары жоқ қысқа тапсырманы көріп, latency мен шығын туралы қате қорытынды жасайсыз.

Worker әрі қарай өмір сүруі керек болса, бір хабарламаны растағаннан кейін telemetry provider-ді жаппаңыз. Provider-ді бүкіл worker процесі тоқтағанда аяқтаңыз. Тапсырманың өзінде есептегіш немесе құрылымдалған конкуренттілік қолданыңыз: ата-ана span ішкі операциялар аяқталғанын немесе тоқтатылғанын белгілегеннен кейін ғана аяқталсын.

Node.js үшін қолмен process.exit() шақыру әсіресе қауіпті. Event loop exporter-дің жабылмаған желі сұрауын аяқтауға үлгеруі мүмкін еді, бірақ күшпен шығу оған мүмкіндік бермейді. process.exitCode орнатып, await арқылы бақыланатын тоқтауды аяқтап, қатені жазып, процестің табиғи түрде бітуіне мүмкіндік берген дұрыс. Кітапхана немесе runtime процесті тым ұзақ ұстаса, оны бірден шығумен емес, нақты қай дескриптор ұстап тұрғанын анықтау арқылы шешіңіз.

Scheduled job келісіміне финализацияның анық кезеңін қосыңыз. Оның нәтижесі процестің қалыпты журналына түсуі керек: іске қосу идентификаторы, өңделген элементтер саны, телеметрия shutdown нәтижесі және ұзақтығы. Келесі инцидент trace-тағы бос орынды көрсеткенде, бұл журнал exporter жоғалуын процестің апатты жойылуынан ажыратуға көмектеседі.

«Flush аяқталды» хабарынан гөрі бүкіл тізбекті тексеріңіз

«Flush аяқталды» журналы пайдалы, бірақ оқиғаның соңғы сақтау жүйесінде қолжетімді екенін дәлелдемейді. Exporter batch-ті collector-ге сәтті жеткізуі мүмкін, ал collector деректерді өз кезегіне қоюы, лимитке байланысты тастауы немесе ары қарай жеткізбеуі ықтимал. Трасса бірнеше тәуелсіз істен шығу шекарасынан өтеді.

Production-да іске қосатын дәл сол тізбекті тексеріңіз: қолданба, жергілікті SDK, желі, collector немесе gateway, backend. Exporter-ді жадтағы объектімен алмастыратын unit-тестпен шектелмеңіз. Мұндай тест шақыру ретін тексереді, бірақ DNS, TLS, proxy, кезек лимиттері және контейнердің тоқтау уақытын жасырады.

Мына сценарийді әр орындау процесінің түрі үшін CI жүйесіне қосқан жөн.

1. run_id, мысалы UUID жасаңыз және оны тест іске қосылымының түбір span-ына атрибут ретінде қосыңыз.
2. Бірнеше ішкі span жасап, бір бөлігін бірден, біреуін аздаған кідірістен кейін аяқтаңыз.
3. Қолданба SIGTERM кезінде пайдаланатын shutdown жолын іске қосыңыз, бөлек тест функциясын емес.
4. Таңдалған уақыт ішінде соңғы backend-та run_id пайда болғанын күтіңіз.
5. Қабылдаушы әдейі кідіргенде және таймер сыртқы grace period-ке жақын болғанда тестті қайталаңыз.

Бір ғана trace бар-жоғын тексермеңіз. Аяқталған span-дардың күтілетін санын, түбір span статусын және ішкі операция ұзақтығын салыстырыңыз. Ішкі span-дар жоғалғанымен, түбірдің жетуі шынайы сияқты көрінетін, бірақ жалған сурет жасайды.

Кезектің толуына арналған бөлек тест қосыңыз. Exporter-ді уақытша баяулатып, кезекті аз санмен шектеп, оның сыйымдылығынан көп span аяқтаңыз. Команда метрикадан немесе журналдан басқарылатын жоғалтуды көруі керек. Егер жасанды түрде жасалған queue_full байқалмаса, нақты инцидентте ол туралы аналитик шағымынан кейін ғана білесіз.

Pipeline-дің өзін бақылаңыз

Ешкім бақыламайтын телеметрия үнсіз бұзылады. Қабылдаушы қолжетімді болуы мүмкін, бірақ exporter қате endpoint қолданады. Collector сұрауды қабылдағанымен, өз кезегіне тіреледі. Процесс уақытында жабылуы мүмкін, бірақ SDK кезегі shutdown басталғанға дейін толып қойған болады.

Әр сервис үшін шағын сигналдар жиынтығын жинаңыз: аяқталған қолданба сұрауларының саны, экспортталған span-дар саны, export қателері, кезектен тасталғандар, shutdown ұзақтығы және SIGTERM алынған сәттегі белсенді тапсырмалар саны. Барлық SDK бірдей метрика жарияламайды, сондықтан бір бөлігін журналдан немесе exporter қабатынан алуға болады. Маңыздысы нақты панель емес, жұмыс ағынын телеметрия ағынымен салыстыру мүмкіндігі.

Тек exporter қателерінің абсолют санын ескертіп тұратын alert жасамаңыз. Үш сұрауы бар түнгі сервиске бір қате маңызды болуы мүмкін, ал миллиондаған span жасайтын ағындық consumer бір реттік ақауға шыдайды. Сәтсіз өңдеу үлесін, тайм-ауттар қатарын және кезектің өсуін бақылаңыз. Ең пайдалы салыстыру - бизнес операцияларының саны мен дәл сондай service name және операция түрі бар түбір span-дар саны.

Shutdown журналдары құрылымдалған болуы керек. Оларға тоқтау себебі, draining басталғандағы белсенді тапсырмалар саны, drain уақыты, SDK shutdown нәтижесі және exporter қатесі кіргені пайдалы. Сұрау payload-тарын немесе prompt-ты толық күйінде жазбаңыз. Телеметрия қолданба журналынан да көп жүйе арқылы өтуі мүмкін, сондықтан артық деректер қолжетімділікке қатысты бөлек мәселеге айналады.

Бұл LLM сервистерінде ерекше байқалады: модельге жасалған қысқа сұрау ұзақ retry тізбегін, tool call-дарды және фондық тексерулерді тудыруы мүмкін. Клиентке жауап бергеннен кейін процесс бірден аяқталса, қымбат сұраудың себебін түсіндіретін span-дардан айырылуыңыз мүмкін. AI Router LLM шақыруларын бір OpenAI-үйлесімді endpoint арқылы бағыттауға мүмкіндік береді, бірақ телеметрияны дұрыс аяқтау қолданба мен оның runtime міндеті болып қалады.

Production-ға қоспас бұрын тексеру тізімі

Бұл тізімді OpenTelemetry баптауларының емес, тоқтау келісімінің тексеруі деп қабылдаңыз. Кез келген тармаққа нақты жауап болмаса, келесі қайта іске қосу деректерде бос орын қалдыруы мүмкін.

• Процестің shutdown-ына бір иесі бар және cleanup аяқталмай тұрып күшпен шығуды шақырмайды.
• SIGTERM кезінде сервис telemetry provider жабылғанға дейін жаңа жұмыс қабылдамайды.
• Белсенді HTTP сұраулары, хабарламалар мен фондық операцияларда drain үшін жеке дедлайн бар.
• Exporter тайм-ауты барлық қолданба кезеңдерінен кейін сыртқы kill-ге дейін қалатын уақыттан қысқа.
• Журналдар мен метрикалар кезек толуын, жіберу қателерін, тайм-ауттарды және shutdown-тан кейін кеш аяқталған span-дарды көрсетеді.

Deployment конфигурациясын да тексеріңіз. preStop hook SIGTERM өңдегішін алмастырмайды, өйткені оның реті мен қолжетімді уақыты платформаға байланысты. Readiness probe consumer хабарламаларды ала берсе, көмектеспейді. Grace period-ті ұзарту код сигналдан кейін 20 миллисекундта os.Exit немесе process.exit шақырса, мәселені шешпейді.

Жақсы соңғы тексеріс қарапайым әрі жағымсыз: жүктеме кезінде процеске SIGTERM жіберіп, мұны ондаған рет қайталаңыз да, басталған, аяқталған және жеткізілген түбір операциялар санын салыстырыңыз. Тесті нақты collector және production-дағыдай желі ережелері бар ортада өткізіңіз. Осы сынақтан кейін жоғалған әр span-ды түсіндіре алмасаңыз, конфигурация келесі deploy-ға әлі дайын емес.