Интеграцияларда сквозная трассировка: Correlation ID және бірыңғай логтар

Неліктен сквозная трассировка қажет

Интеграциялар монолитты бағдарлама тәрізді бұзылмайды. Бір ақау жиі бірнеше жерде көрінеді: құжат бухгалтерияға жетпейді, мәліметтер витринасында бос жол пайда болады, ал қолдау қызметінде тек қолданушы шағымын көрінеді. Барлығы жерде мәселе бар сияқты көрінуі мүмкін, алайда бастапқы себебі әдетте біреу.

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

Сквозная трассировка интеграциялары қарапайым сұрақтарға ұзын қоңыраулар мен скриншоттарды жібермей жауап беруге көмектеседі. Мысалы: құжат қай жерде (кезекте ме, өңдеуде ме, қателікпен ме немесе мақсатты жүйеде ме), қай қадамда ақау шықты және оны кім бірінші көрді, бұл бір реттік ақау ма әлде ұжымдық мәселе ме, жол бойында қандай деректер өзгерді және өзгеріс заңды екенін дәлелдеуге бола ма.

Іс тоқтаған кезде бизнес әдетте сұрайды: «қанша өтініш/төлем/шот өтпей қалды және қашан жұмыс істейтін болады». Қауіпсіздік (ИБ) бөлек сұрайды: «кім сұраныс жіберді, қайдан, қандай аккаунтпен, деректер алмастырылған жоқ па». Бірдей із жоқ болса, болжам жасаудан басқа жол қалмайды.

Тәжірибеден мысал: шот ERP-ден интеграциялық шинге, одан кейін келісу жүйесіне және соңғы есепке алу жүйесіне жіберіледі. Бір жерде шарт нөмірі өрісі жоғалады. Соңында құжат қабылданбайды, ал әр жүйеде бұл жеке қате ретінде көрінеді. Трассировка құжат тарихын бүтіндей сақтайды және қай жерде деректер жоғалғанын минуттар ішінде көрсетуге мүмкіндік береді.

Correlation ID қарапайым тілмен

Correlation ID — сұранысқа немесе құжатқа берілетін және әртүрлі жүйелер арқылы өткенде сақталатын бірыңғай идентификатор. Ол әсемдік үшін емес, бір өтудің барлық логтары мен оқиғаларын тез жинау үшін қажет: API-ге кіргеннен бастап деректің соңғы жазбасына немесе сыртқы сервиске жауапқа дейін.

Correlation ID құжат нөмірімен тең емес. Құжат нөмірі бизнестен келеді (мысалы, «Шот N 54821»), әртүрлі ортада қайталануы мүмкін, қайта жасалғанда өзгеруі мүмкін немесе тек бір жүйеде ғана болуы мүмкін. Correlation ID техникалық сипатта: ол бастапқыда пайда болады және кейін құжат басқа бизнес-нөмір алған жағдайда да өзгермейді.

Ол request id-ден де ерекшеленеді. Request id жиі бір HTTP-сұрау шегінде немесе бір сервис ішінде өмір сүреді және әр жаңа шақыруда өзгереді. Correlation ID бүкіл тізбекті байланыстырады: бір кіріс сұрауы, бірнеше ішкі шақырулар, кезектердегі хабарлар, интеграциялық қабаттағы өңдеу және кері жауаптар.

Оны қайда жасаған ыңғайлы? Кіріс шлюзінде немесе сырттан сұранысты қабылдайтын бірінші сервисде. Егер Correlation ID заголовокта келсе — оны қабылдап, тексеру керек. Егер жоқ болса — жаңа жасалып, әрі қарай барлық жерге өткізілуі тиіс: API заголовкаларында, кезек хабарларының метадеректерінде, файл атында немесе техникалық белгілерде.

Correlation ID форматы бірегей, қысқа және тұрақты болуы тиіс (header және логтарға сыйсын), жеке деректер мен «мағынаны» қамтымауы керек (клиент, сома және т.б. кодталмауы тиіс) және оператор телефон арқылы айтуға ыңғайлы оқылуы керек. Практикада көбінесе UUID немесе белгілі өлшемді қысқа қауіпсіз токен қолданылады. Ең маңыздысы — бір форматқа келісіп алу және оны әр лог-оқиғада бекіту.

ID-ні API, кезек пен файлдар арқылы қалай өткізу

Сквозная трассировка жұмыс істегені үшін Correlation ID әрқашан құжатпен бірге жүруі керек, тіпті алмасу форматы өзгерген жағдайда да.

API-де ID-ні заголовокта (X-Correlation-Id сияқты) жіберу ең оңай. Сонда шлюзде, сервистерде және логтарда оны денені өзгертпей оқуға болады.

Кезектер мен брокерлерде метадеректерді (properties/headers) пайдалану ыңғайлы. Ондай мүмкіндігі болмаса, Correlation ID-ні денеге бөлек өріс ретінде қойыңыз. Ең бастысы — бір орын таңдап, барлық жерде солай ұстану.

Файлдармен жұмыс қиынырақ: «заголовктар» жоқ. Әдетте үш тәсіл көмектеседі: файл атына Correlation ID қосу, жанында кішкене мета-файл сақтау немесе мазмұнның басына өріс қосу (формат мүмкіндік берсе). Негізгі талап — қабылдаушы өңдеуді бастамас бұрын ID-ні ала білуі тиіс.

Бұтақталғанда (fan-out) бір жалпы Correlation ID-ні негізгі ретінде қалдырып, әр бұтаққа екінші деңгейлі идентификатор (мысалы, Child-Id немесе Step-Id) қосыңыз. Қайта қосу кезінде (fan-in) сол басты ID-ні пайдаланып, кірген Child-Id тізімін сақтаңыз, сонда не қосылғаны көрінеді.

Ретрайлар мен дубликаттар жаңа Correlation ID тудырмауы керек. Бастапқы идентификатор сақтансын, ал қасында талпыныс нөмірін (attempt=2) және идемпотентті кілтті жазыңыз. Сол кезде іздеу кезінде көрінеді: бұл бір операцияның қайталануы, жаңа транзакция емес.

Бірыңғай лог форматы: әр жазбада не болуы керек

Бірдей лог форматы бір сұрауға байланысты құжат тарихын барлық сервистерден тез жинауға қажет. Олай болмаған жағдайда сквозная трассировка әртүрлі файлдар мен әртүрлі өріс атауларынан қолмен іздеу болып қалады.

Минималды өрістер жиі міндетті болуы тиіс:

• timestamp (уақыт белдеуін қоса)
• system (сервис/модуль атауы) және version
• environment (prod, stage және т.б.)
• correlation_id (қажет болса request_id)
• status (успех, ошибка, отмена, ретрай)

Көбіне duration_ms, operation (не істелді), endpoint немесе queue/topic, сондай-ақ doc_id (ішкі құжат идентификаторы) қосу пайдалы. Сонда бірдей операцияларды жүйелер арасында салыстыру және қай жерде уақыт өсіп жатқанын көру оңай болады.

Лог деңгейлері бойынша қарапайым ереже: INFO факт пен нәтижені жазады (басталды, аяқталды, қанша уақыт алды, қандай негізгі ID-лар). WARN — сұраныс формаль түрде өтті, бірақ тәуекел бар: қайта талпыныс, деградация, жарамсыз деректер, сыртқы жүйедегі таймаут. ERROR — операция орындалмай қалғанда және талдау қажет болғанда.

Қателерді біркелкі логтаңыз, оларды топтастыру мүмкін болуы үшін: бірдей error_code, тұрақты қате түрі, қысқа хабарлама «ерекше детальдарсыз» және бөлек өріс error_fingerprint (мысалы, код + орын). Стек пен шикі жауаптарды бөлек өрістерге салып, деңгейге байланысты қосқан дұрыс, осылайша шудан көз ашылады.

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

Орталықтандырылған лог жинау және іздеу

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

Жинауға тек қосымшалардың логтары емес, API-шлюз, интеграциялық шина, хабар брокері, фондық тапсырмалар, ОС пен қажетті жерлерде дерекқордың диагностикалық оқиғалары сияқты жазбаларды қосу керек. Сол кезде Correlation ID бүкіл тізбек бойынша көрінеді, тек бір сервис ішінде емес.

Бастапқыда атауларды жазу ережелерін келісіңіз. Бір сервис бүгін billing деп аталып, ертең billing-service болып, тестте тағы басқа ат болса — фильтрлер жұмысын тоқтатады. Сол сияқты өрістерді бір рет бекітіп алу қажет: system/service, environment, correlation_id, request_id, error_code, duration_ms қалай жазылатынын.

Іздеу үшін негізгі сүзгілер жеткілікті: Correlation ID басты кіріс нүктесі, қателікке дейін және кейін уақыт интервалы, сервис/жүйе, қате коды немесе исключение класы, орта (dev/test/prod). Жұмыс сценариі осылай: продта «шот тұрып қалса», оператор API жауаптан немесе кезек хабарынан Correlation ID алып, жарты минут ішінде оқиғалар тізбегін көреді: сұранысты қабылдау, кезекке қою, өңдеушідегі қате, ретрайлар, финалдық статус.

Бұл тек қана логтардың сақталу мерзімі, қолжетімділіктер (кім не көре алады) және орталар бойынша айқын бөлініс алдын ала орнатылғанда жұмыс істейді, әйтпесе тесттік оқиғалар боевикке араласып кетеді.

Құжаттың жүйелер арасындағы маршрут картасы

Маршрут картасы — бұл бір құжаттың (тапсырыс, өтініш, шот) өтетін қадамдарының тізімі және өтпелі статустары. Негізінде бұл интеграциялар үшін трек-номер: құжат қай жерде болды, оған не жасалды және қай қадамда тұрып қалғаны.

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

Қандай статустар шын мәнінде көмектеседі

Статустар жауапкершілікті бөлетіндей болуы керек. Оңай тәсіл: интеграциялық проблемаларды (жеткізілді/жеткізілмеді, таймаут, тасымалдау қатесі) бизнес-қателерден (валидация, құқықтар, контрагент табылмады) бөлектеу; «күтуде» (кезекте, растауды күту) қосып, «сәттілік» (растау, жабу) анық көрсету.

Ондаған статус жасауға тырыспаңыз. 8-12 анық статустың болуы 40 анықталмағаннан жақсы.

Картаны логтар мен метрикаларға қалай байланыстыруға болады

Маршрут картасы трассировкадағы сол идентификаторларға негізделуі керек: Correlation ID және қажет болса құжат ID. Сонда бір Correlation ID бойынша орталық логтарды ашып, қателіктермен қатар «қалыпты» өту нүктелерін де көруге болады.

Практикалық әдіс: әр қадамда қысқа оқиға жазып отыру (кім, қайда, не істеді, нәтиже) және бірден маршрут күйін жаңарту. Метрикалар (мысалы, «қабылданды» пен «растау» арасы) қай жерде үнемі кешігулер болатынын көрсетеді, тіпті айқын қателер жоқ кезде де.

Үлкен өзгеріссіз енгізу: қадамдық жоспар

Сквозная трассировка әдетте технологиянан гөрі масштабтан тұрып қалады: бәрін бірден қамтитын болуға тырысады. Жұмыс істейтін тәсіл — ең маңызды ағымды таңдап, оны басынан аяғына дейін көрінетін ету.

Жиі ұшатын жоспар:

1. Бір ең ауыр маршрутты таңдаңыз және қадамдарды қысқа сипаттаңыз: қандай жүйелер қатысады, қай жерде API, қай жерде кезек, қай жерде файл.
2. Ережелерге келісіңіз: Correlation ID форматы, оны қайда сақтау (заголовок, хабардың өрісі, файл аты), логта қандай өрістер міндетті (уақыт, жүйе, операция, нәтиже, ұзақтық, Correlation ID).
3. Әр қадамның кірісінде және шығысында ID генерациясы мен өткізілуін қосыңыз. Егер қадам ID-сіз сұранысты қабылдайтын болса, ол жаңа жасауы керек және әрі қарай өткізуі тиіс.
4. Орталықтандырылған лог жинауды және минималды іздеуді орнатыңыз: «Correlation ID бойынша барлық оқиғаларды көру». Кейін бірнеше сақталған сұрау немесе қарапайым дашборд қосыңыз.
5. Маршрут картасын ресімдеңіз: күтілетін қадамдар тізбегі мен негізгі статустар. Оның үстіне тұрып қалуларға (N минут ішінде келесі қадам жоқ) және қайталанатын қателерге алертер қойыңыз.

Алғашқы нәтижелерден кейін қысқа инциденттік жаттығу өткізіңіз. Командаға тесттік Correlation ID беріп, 10 минут ішінде сұраңыз: құжат қазір қай жерде, қай қадамда ақау шықты, соңғы сәтті әрекет қандай болды. Нәтижелер бойынша регламенттерді жаңартыңыз: бірінші кім логтарды қарауы тиіс, тикетке не қосу керек, қашан эскалация жасау. Осындай тәсілді интеграторлар (мысалы, GSE.kz) жүйелер арасындағы тар жерлерді жылдам табу үшін қолданады.

Мысал: құжат 4 жүйеден қалай өтеді

Маршрутты елестетіңіз: бухгалтерия шот жасайды, ол тексеруден өтеді, контрагентке жіберіледі және мұрағатқа түседі. Қатысатын жүйелер: ERP (дерек көзі), тексеру сервисі (валидация), интеграциялық қабат (шина/API), ECM (құжат сақтау).

Correlation ID мүмкіндігінше ертерек — құжат пайда болған кезде — жасалуы жақсы. Көбіне оны бастапқы жүйе (ERP) "Отправить" батырмасы кезінде генерациялайды және одан әрі барлық шақыруларында, хабарлар мен файлдарда береді. Егер бастапқы жүйе жасай алмаса, интеграциялық қабат Correlation ID бере алады, бірақ сол кезде оны бастапқы жүйеге қайтарып, құжат карточкасына жазып қою маңызды.

Содан кейін құжат қадамдар арқылы өтеді және логтарда бірдей тірек өрістер тіркеледі: Correlation ID, Document ID (ішкі нөмір), system, step, status, timestamp, error (болса). Маршрут картасында бұл статустар тізбегі ретінде көрінеді:

• ERP: CREATED -\u003e SENT
• Validation: RECEIVED -\u003e VALIDATED
• Integration: ENQUEUED -\u003e DELIVERED
• ECM: STORED -\u003e INDEXED

Ретрай болса, қайталану мен жаңа құжатты ажырату маңызды. Практикалық тәсіл: Correlation ID сол қалпында қалады, ал талпыныс үшін attempt (1, 2, 3) немесе retry=true өрісі қосылады. Сонда Correlation ID бойынша іздегенде көрінеді: бұл бір құжат, тек қайта жеткізілу болды.

Инцидентті тезірек талдау: қысқа тергеу сценарийі

Жылдамдықтың құпиясы — жүйелер арасында жалпы жіптің болмауы емес, сол жіптің болуы: бір Correlation ID және маршрут картасы. Алдын ала контекст жинаңыз: уақыт (минутқа дейін), симптом (не дұрыс емес), кім байқады (қолданушы, оператор, мониторинг) және қандай маршрут зардап шеккені (мысалы: сайт -> CRM -> ERP -> қойма). Бұл іздеуді бірден тарылтады.

Келесі мақсат — сыртқы белгіні пайдаланып Correlation ID табу. Сыртқы белгі ретінде құжат нөмірі, қолданушы логині, сома мен валюта, операция түрі немесе сыртқы идентификатор қолданылуы мүмкін.

Қысқа жұмыс сценариі:

• Бірінші «көрінетін» жүйенің логынан сыртқы белгі бойынша жазбаны тауып, Correlation ID алыңыз.
• Осы ID бойынша барлық жүйелерден оқиғаларды жинап, уақыт бойынша сұрыптаңыз.
• Маршрут картасымен салыстырыңыз: қабылдау (received), өңдеу (processed) және жіберу (sent) растамаларын қай жерде күту керек.
• Егер растау N-қадамда жоғалса, көрші оқиғаларды тексеріңіз: ретрай болған ба, сыртқы жүйеден жауап болды ма, таймаут болды ма.
• Қорытындыны факт негізінде жасаңыз: нақты лог жолы, нақты қадам, нақты қате коды.

«Деректер қатесі» мен «инфрақұрылым қатесін» ажырату үшін қайталанушылық пен ақаудың сипатына қараңыз. Деректер қатесі бір құжатқа тән (қате формат, өрістің жоқтығы, бизнес-ережеге қайшы), ал инфрақұрылымдық қателер көбінесе топпен жүреді (таймауттар, сервис жоқ, кезек тұтынылмайды).

Постмортем үшін артефактілерді сақтаңыз: Correlation ID, уақыт аралығы, зақымдалған жүйелер тізімі және қадам, бастапқы payload (жеке деректер маскировкасы арқылы), маңызды лог жолдары мен қате кодтары, қайта талпыныс саны.

Қателер мен тұзақтар

Ең жиі кездесетін қате — Correlation ID өте кеш пайда болады. Оны бір сервистің ішінде ғана жасап, сұраныс API-шлюз, балансировщик немесе бірінші микросервис арқылы өткенге дейін бірегей идентификатор болмағандықтан тізбектің бастауы жоғалады.

Екінші мәселе — ID асинхрондық жерде жоғалуы. Кезектер, кешіктірілген тапсырмалар, жоспарлаушылар мен batch өңдеулер жиі өз алдына өмір сүреді: хабар кезекке салынғанда бір заголовкпен қойылады, ал воркер оны оқығанда логтарда Correlation ID болмауы мүмкін, себебі оны контекстке тасымалдамаған.

Арнайы тұзақ — уақыт. Әртүрлі жүйелер оны әртүрлі форматта немесе уақыт белдеулерінде жазса, оқиғалар дұрыс сұрыпталмай қалады. Бұл қысқа кешігулер кезінде айқын байқалады.

Көбіне логтар тым шулы немесе тым кедей болады. Бірінші жағдайда «метод сәтті шақырылды» шуында жоғылып кетесіз, екінші жағдайда — тарихты жабыстыратын өрістер болмайды: Correlation ID, жүйе атауы, өңдеу қадамы, статус, ұзақтық.

Ең қауіпті қате — деректер ағуы. Логтарға кездейсоқ жеке деректер, токендер, парольдар, API кілттері немесе құжат мазмұны түсіп қалуы мүмкін. Бұдан кейін бұл мәліметтер орталық лог қоймасында сақталып, оған әдетте боевик деректер базасына қарағанда көбірек адамдардың қолы жетеді.

Тағы бір мәселе — «сәттілік» анықтамалары әртүрлі болуы. Бір жүйе үшін 200 OK барлық жұмыстың дұрыс өткенін білдіруі мүмкін. Басқасы үшін сәттілік — БД-да жазба пайда болды. Үшінші үшін — сыртқы контрагенттен растау алу. Жалпы анықтама болмаса, «жолда» ме әлде «тұрып қалды» ма айыру қиын болады.

Жылдам өз-өзін тексеру:

• Correlation ID ең бірінші кірісте жасалады және жол бойы өзгермейді.
• ID кезектер мен жоспарлаушылар арқылы API-дегідей қатал түрде тасымалданады.
• Уақыт бірдей форматта жазылады (формат пен уақыт белдеуі).
• Әр лог жазбасында минимум: ID, жүйе, қадам, статус, ұзақтық.
• Құпиялар мен жеке деректер маскировкаланған немесе мүлде жазылмаған.

Продқа шығар алдында жылдам чеклист

Шығару алдында трассировка нақты инцидентте жұмыс істейтінін тексеріңіз, тек стендте емес. Ең қарапайым тест: бір транзакцияны (құжат, өтініш, төлем) алып, оны бір идентификатор арқылы 2 минут ішінде таба аласыз ба тексеріңіз.

Көбіне түнгі кезекте құтқаратын минималды тексерістер:

• Бірдей Correlation ID барлық кіріс және шығыс шақыруларда бар: HTTP заголовкалар, кезек хабарлары, файл аты немесе файл алмастыруда метадеректер.
• Негізгі жүйелердегі логтар бір стильде жазылады: бірдей өрістер (correlation_id, system, operation, status, duration_ms) және бірдей уақыт (ISO формат, бір уақыт белдеуі).
• Correlation ID бойынша іздеу негізгі нүктелерде «басынан аяғына дейін» оқиғаларды таба алады: API-шлюз, шина/кезек, өңдеу сервисі, база/сақтау.
• Маршрут картасы (және мониторинг кестесі де болса) ағымдағы қадамды және тоқтаудың себепін көрсетеді: валидация қатесі, таймаут, сыртқы жүйенің бұзылуы, кезек толып қалу.
• Ақаулар кезінде мінез-құлық анықталған және тексерілген: шектеулі ретрайлар, дедупликация (екі еселенген құжаттар болмауы үшін), таймауттарды түсінікті өңдеу.

Қауіпсіздікті жеке тексеріңіз. Логтарға арналған қолжетімділікті рөлдерге сай орнатыңыз және сезімтал өрістер жазылғанда олар маскировкаланғанына көз жеткізіңіз (ЖСН, телефондар, карта нөмірлері). Егер сәйкестендіру қажет болса, қауіпсіз отпечаток (хеш) немесе соңғы 4 символды жазып қойыңыз, толық идентификатор емес.

Практикалық сынақ: тесттік құжат жіберіп, бір қадамда жасанды таймаут шақырып, Correlation ID бойынша құжат қай жерде тоқтап қалғанын және жүйенің кейін не істегенін (қайта жіберу, күту, DLQ-ға жіберу, бас тарту) тексеріңіз.

Келесі қадамдар: нәтижені бекіту және масштабтау

Әсер ережелер командада әдетке айналғанда пайда болады. Бірінші сәттіліктен кейін стандарттарды бекітіп, оларды әзірлеу мен қолдаудың бөлігіне айналдырыңыз.

Пилоттан бастаңыз: ең проблемалы 1-2 маршрутты (мысалы, «CRM -> шина -> ERP») таңдаңыз және әр қадамға иелер тағайындаңыз. Иесі Correlation ID жоғалмауын және логтардың оқылуын қамтамасыз етеді.

Одан әрі әдетте мына негізгі қадамдар жеткілікті: қысқа лог стандарты бекіту (міндетті өрістер және қателер ережесі), Correlation ID-нің API, кезектер мен фондық тапсырмалар арқылы өтуін тексеру, сақтау мен іздеуді алдын ала орнату (сақтау мерзімі, көлем, қолжетімділік, маскировка), дежурство мен эскалация келісімі, постмортем өткізу және әрбір маңызды қателік соң код, логтар мен регламенттерді жаңарту.

Шкалалау шексіз жобаға айналмасын десеңіз, қарапайым метрикаларға келісіңіз: бір ID бойынша қанша инцидент шешілген, орташа уақыт бастапқы себепке жетуге, жүйелер шекарасында қанша рет ID жоғалған.

Егер лог сақтау және іздеу үшін инфрақұрылым қажет болса (логтарды сақтау серверлері, интеграция, қолдау), тәжірибелі жүйелік интеграторды тарту мағынасы бар. Мысалы, GSE.kz интеграциялық жұмыстардан бөлек дата-орталық инфрақұрылымы мен 24/7 қолдауды ұсынады, бұл трассировка өндірісте тұрақты жұмыс істеуі үшін пайдалы.