Gdy operacja obejmuje żądanie HTTP, kolejkę i jedną lub kilka usług zewnętrznych, jej logi są rozproszone między różnymi procesami. Bez wspólnej wartości badanie incydentu wymaga wyszukiwania według czasu, użytkownika lub treści — kryteriów, które mogą być niejednoznaczne albo wrażliwe. Identyfikator korelacyjny w PHP pozwala grupować zdarzenia powiązane z operacją i odtworzyć jej przebieg.
Aby to działało, identyfikator musi mieć jasno określone źródło, być jawnie przekazywany przez granice asynchroniczne i pojawiać się w logach w spójny sposób. Nie jest to kompletne rozwiązanie z zakresu obserwowalności ani poświadczenie: służy do powiązania zdarzeń, ale sam nie wyjaśnia, co zawiodło, ani kto jest uprawniony.
Jakie problemy rozwiązuje, a co pozostaje poza zakresem
Identyfikator korelacyjny to nieprzezroczysta wartość przypisana do żądania lub operacji. Po dodaniu jej do logów aplikacji pozwala odnaleźć komunikaty wygenerowane w różnych komponentach, które mają tę samą wartość. Można na przykład powiązać odebranie żądania z przekazaniem zadania do kolejki, jego przetworzeniem i odpowiedzią zewnętrznego API.
Ułatwia to diagnozę, gdy logi są scentralizowane i można je przeszukiwać według pól. Nie gwarantuje jednak, że wszystkie komponenty poprawnie zarejestrowały identyfikator ani nie mierzy czasu trwania, wolumenu czy zbiorczych błędów. Metryki służą do obserwowania trendów i generowania alertów; ślady rozproszone pokazują powiązania i czasy między komponentami; logi dostarczają zdarzeń i kontekstu. Są to uzupełniające się sygnały.
Korelacji nie należy też mylić z uwierzytelnianiem, autoryzacją ani tożsamością użytkownika. Znajomość identyfikatora nie powinna dawać dostępu do danych ani pozwalać na wykonanie operacji. Jeśli wartość zostanie ujawniona w adresie URL lub systemie zewnętrznym, może stać się widoczna dla większej liczby osób, niż zakładano.
Określenie miejsca generowania i sposobu walidacji
W aplikacji typowym miejscem rozpoczęcia kontekstu jest middleware HTTP odbierający żądanie. Może zaakceptować przychodzący identyfikator, aby zachować ciągłość z proxy lub wcześniejszą usługą, albo wygenerować nowy, jeśli go brakuje. Zasady muszą być jawne: zaufanie wszystkim wartościom z zewnątrz może dopuścić nieprawidłowe lub nadmiernie długie dane albo wartości przygotowane w celu zanieczyszczenia logów.
W przypadku ruchu publicznego bezpiecznym rozwiązaniem jest zawsze generowanie wewnętrznego identyfikatora, a jeśli trzeba zachować wartość przychodzącą — traktowanie jej jako niezaufanej danej i ścisła walidacja. Inną możliwością jest akceptowanie wartości z nagłówka wyłącznie od zaufanych komponentów, na podstawie reguł skonfigurowanych na brzegu sieci. Wybór zależy od architektury i od tego, kto może wywoływać usługę.
Format powinien być łatwy do walidacji i zgodny z systemami, które go przenoszą. Można użyć losowej wartości wygenerowanej przez systemowe źródło kryptograficzne, na przykład random_bytes(), i zakodować ją przy użyciu ograniczonego alfabetu. Nie należy tworzyć jej na podstawie znaczników czasu, adresów IP ani danych osobowych. Unikatowy identyfikator nie musi ujawniać informacji biznesowych.
$correlationId = bin2hex(random_bytes(16));
Ten przykład generuje losową wartość szesnastkową; nie narzuca uniwersalnego formatu. Określ maksymalną długość, dozwolone znaki i nagłówek używany przez komponenty, na przykład X-Correlation-ID. Jeśli platforma stosuje już standard śledzenia, nie twórz bez potrzeby równoległego mechanizmu: korelacja logów i kontekst śladu mogą współistnieć, ale nie są tym samym pojęciem.
Propagowanie kontekstu przez każdą granicę
W middleware zwaliduj lub utwórz identyfikator na początku żądania i dodaj go do kontekstu logowania. Jeśli jest zwracany klientowi w odpowiedzi, upewnij się, że nie ujawnia dodatkowych informacji i że zasady zaufania są jasne. Pozostałe części aplikacji powinny otrzymywać kontekst przez jawną zależność, a nie polegać na trudnych do testowania zmiennych globalnych.
W procesie PHP przekazuj identyfikator do usług rejestrujących istotne zdarzenia. W przypadku zadań asynchronicznych umieść go w metadanych komunikatu lub w przeznaczonym do tego polu payloadu — zgodnie z konwencjami systemu kolejkowego. Podczas odbierania komunikatu odtwórz kontekst przed wykonaniem zadania i wyczyść go po zakończeniu. Jest to szczególnie ważne w długo działających procesach, w których ten sam worker obsługuje kolejne komunikaty: niewyczyszczony kontekst może przedostać się do innej operacji.
Podczas wywoływania zewnętrznego API przekaż wartość w uzgodnionym nagłówku tylko wtedy, gdy dostawca go obsługuje i udostępnienie wartości jest właściwe. Nie wysyłaj niepotrzebnych danych wewnętrznych. W przypadku integracji, które nie zachowują nagłówków, zarejestruj identyfikator wraz z lokalnym wynikiem wywołania; nie zakładaj, że system zdalny zwróci go we własnych logach.
Jeśli żądanie tworzy kilka niezależnych zadań, każde z nich może zachować identyfikator operacji źródłowej. Jeśli natomiast trzeba rozróżniać podoperacje, przypisz każdej własny identyfikator i zachowaj powiązanie za pomocą kontekstu śladu lub niewrażliwych pól biznesowych. Unikaj ponownego używania tej samej wartości w różnych znaczeniach bez ich udokumentowania.
Używanie identyfikatora w logach strukturalnych, a nie zamiast obserwowalności
Zapisuj identyfikator jako pole strukturalne, na przykład correlation_id, zamiast umieszczać go wyłącznie w tekście komunikatu. Dzięki temu platforma logów może filtrować i grupować zdarzenia bez polegania na przybliżonym wyszukiwaniu. Zachowaj jednolitą konwencję w aplikacji, workerach i integracjach oraz sprawdź, czy serializator go nie pomija.
Umieszczaj go w zdarzeniach przydatnych podczas diagnozowania: odebraniu żądania, utworzeniu komunikatu, rozpoczęciu i zakończeniu zadania oraz wyniku wywołania zewnętrznego. Nie trzeba powtarzać go w każdym wierszu, jeśli system zapewnia trwały kontekst dla danej operacji. W takim przypadku sprawdź, czy kontekst jest resetowany między żądaniami i czy logi pozostają zrozumiałe, gdy dany komponent go nie obsługuje.
Nie używaj identyfikatora jako etykiety metryki o wysokiej kardynalności. Utworzenie osobnego szeregu czasowego dla każdego żądania może zwiększyć koszty i zmniejszyć użyteczność metryk. Nie rejestruj też razem z nim tokenów, haseł, danych płatniczych, pełnej treści komunikatów ani zbędnych danych osobowych. Stosuj firmowe zasady minimalizacji danych oraz kontroli dostępu i retencji logów.
Ponowne próby, odroczone wykonania i błędy
Ponowienie tego samego zadania zwykle zachowuje pierwotny identyfikator korelacyjny: nadal jest częścią tej samej operacji logicznej. Aby rozróżnić próby, zapisuj numer próby lub przypisz jej osobny identyfikator, nie zastępując pierwotnego kontekstu. Dzięki temu można zbadać zarówno pełny przebieg, jak i przyczynę każdego wykonania.
Jeśli zadanie zaplanowano do wykonania znacznie później, zachowaj identyfikator jako trwałe metadane; nie polegaj na pamięci procesu ani zakończonej sesji HTTP. Jeśli zadanie rozpoczyna nową, autonomiczną operację, określ, czy dziedziczy kontekst źródłowy, czy otrzymuje nowy identyfikator, i zarejestruj powiązanie między nimi. Taka decyzja zapobiega mieszaniu niepowiązanych zadań przez zbyt szeroki zakres korelacji.
Jeśli kolejka lub usługa zewnętrzna odrzuca metadane, udokumentuj tę granicę i zachowaj kontekst w komponencie, nad którym masz kontrolę. Aplikacja powinna nadal działać, gdy brakuje identyfikatora: wygeneruj go przy wejściu do procesu albo wyraźnie zarejestruj, że kontekst był niedostępny.
Testy i kontrole operacyjne
- Przetestuj middleware z brakującym, prawidłowym i nieprawidłowym identyfikatorem; potwierdź, że stosuje określoną politykę, a wartość nie przekracza limitów.
- Sprawdź, czy identyfikator żądania pojawia się w logach usług wewnętrznych oraz w metadanych komunikatu wysyłanego do kolejki.
- Uruchom komunikat w workerze i sprawdź, czy kontekst trafia do logów oraz jest czyszczony przed obsługą kolejnego komunikatu.
- Zasymuluj ponowienie próby i potwierdź, że pierwotna korelacja zostaje zachowana, a próbę można odróżnić.
- Sprawdź wynik wywołania zewnętrznego i obsługę błędów, nie ujawniając w logach sekretów ani wrażliwych treści.
- Upewnij się, że dashboardy i alerty nie wymagają wyszukiwania pojedynczych identyfikatorów w metrykach.
Kontrola end-to-end powinna śledzić testową operację od wejścia HTTP przez zadanie aż po integrację, z wykorzystaniem tego samego pola do wyszukiwania w logach. Jeśli identyfikatora brakuje na którymś etapie, wskaż dokładną granicę: middleware, serializację komunikatu, konsumenta, klienta HTTP lub konfigurację loggera. Ta obserwacja pokazuje, gdzie poprawić propagowanie, zamiast bez potrzeby dodawać kolejne logi.
Praktycznym rozwiązaniem jest utrzymywanie niewielkiego, jawnego i niewrażliwego kontekstu, z jasno określonymi zasadami zaufania i cyklem życia. Dzięki temu identyfikator korelacyjny w PHP skraca czas poszukiwań podczas incydentu, nie zastępując kontroli bezpieczeństwa, śladów, metryk ani starannie zaprojektowanych logów.
