Jak używać Spring Boot 3.4 do propagowania śladów z niestandardowych nagłówków

Obsługa niestandardowych śladów nagłówka w Spring Boot 3.4

Wyobraź sobie, że masz usługę internetową Spring Boot 3.4, która płynnie współpracuje z dwoma klientami. Pierwszy klient używa Spring Boot 3+, dzięki czemu propagacja śladów jest dziecinnie prosta. Bez dodatkowego wysiłku uzyskasz piękną kompleksową ciągłość śledzenia 🪄. Dzienniki wydają się czyste i połączone, jak za dotknięciem czarodziejskiej różdżki.

Jednak sprawy przybierają inny obrót, gdy w grę wchodzi klient numer dwa. Zamiast standardowych nagłówków śledzenia wysyłają niestandardowe nagłówki, takie jak `ot-custom-traceid` i `ot-custom-spanid`. Chociaż te niestandardowe nagłówki zawierają prawidłowe informacje o śledzeniu, Spring Boot nie propaguje tych śladów. Wynik? Tracisz możliwość łączenia śladów klienta z dziennikami po stronie serwera.

Stwarza to lukę w obserwowalności. W przypadku klienta widoczna jest pełna ścieżka żądania w różnych usługach. W przypadku klienta drugiego widzisz tylko dzienniki po stronie serwera, brakuje krytycznego śledzenia klienta. To jak zobaczyć połowę układanki – wiesz, że czegoś brakuje, ale nie możesz złożyć elementów w całość. 😓

W tym artykule przyjrzymy się, jak rozwiązać ten problem bez polegania na Spring Cloud Sleuth, pozostając wiernym ekosystemowi Spring Boot 3.4. Na koniec będziesz wiedział, jak propagować i kontynuować ślady z niestandardowych nagłówków, zapewniając płynną obserwowalność w całym systemie.

Niestandardowa propagacja śledzenia nagłówka w Spring Boot

Jednym z kluczowych elementów rozwiązania tego problemu jest CustomTraceFilter. Ten filtr rozszerza Filtr Once PerRequest class, zapewniając, że logika nagłówka śledzenia będzie działać tylko raz dla każdego żądania HTTP. Filtry w Spring Boot są niezwykle przydatne podczas globalnego modyfikowania żądań lub odpowiedzi. Na przykład, jeśli klient wysyła informacje o śledzeniu, takie jak ot-custom-traceid Lub ot-niestandardowy-hiszpański w nagłówkach niestandardowych ten filtr przechwytuje żądanie, wyodrębnia te nagłówki i propaguje je do mapowanego kontekstu diagnostycznego (MDC). Dodając identyfikatory śledzenia do MDC, zapewniamy, że identyfikatory te będą widoczne w logach generowanych podczas przetwarzania żądania.

MDC jest kluczową częścią platform rejestrowania, takich jak SLF4J i Logback. Pozwala nam przechowywać informacje kontekstowe dla bieżącego wątku, takie jak niestandardowe identyfikatory śledzenia. Używanie poleceń takich jak MDC.put I MDC.jasnezapewniamy, że system rejestrowania uwzględnia szczegóły śledzenia i pozwala uniknąć zanieczyszczenia pomiędzy równoczesnymi żądaniami. Na przykład, jeśli Klient Drugi wyśle ​​„ot-custom-traceid” jako „8f7ebd8a73f9a8f50e6a00a87a20952a”, ten identyfikator jest przechowywany w MDC i uwzględniany we wszystkich dalszych dziennikach, tworząc spójną ścieżkę śledzenia.

Z drugiej strony w przypadku wychodzących żądań HTTP kluczową rolę odgrywa przechwytywacz RestTemplate. Wdrażając ClientHttpRequestInterceptor, możemy dołączyć te same nagłówki śledzenia („ot-custom-traceid” i „ot-custom-spanid”) do żądań wychodzących. Zapewnia to utrzymanie ciągłości śledzenia, gdy aplikacja wywołuje inne mikrousługi. Na przykład, gdy serwer przetwarza żądanie o identyfikatorze śledzenia `8f7ebd8a73f9a8f50e6a00a87a20952a`, dołącza ten identyfikator do wychodzących nagłówków, dzięki czemu usługi podrzędne mogą bezproblemowo rozpoznawać i propagować śledzenie.

Na koniec testy jednostkowe napisane za pomocą MockMvc weryfikują całą konfigurację, symulując żądania HTTP i weryfikując propagację nagłówka. W rzeczywistych aplikacjach testowanie ma kluczowe znaczenie, aby zapewnić prawidłową obsługę nagłówków śledzenia. Na przykład wysyłając żądanie GET z niestandardowymi nagłówkami i sprawdzając odpowiedź lub dzienniki, możemy potwierdzić, że filtr i przechwytywacz działają zgodnie z oczekiwaniami. To kompleksowe podejście rozwiązuje problem bez polegania na starszych zależnościach, takich jak Spring Cloud Sleuth. Ostatecznie połączenie filtrów, przechwytywaczy i MDC zapewnia ciągłość śledzenia nawet wtedy, gdy klienci korzystają z niestandardowych nagłówków, dzięki czemu system jest solidny i w pełni obserwowalny. 🌟

// Solution 1: Extract and Propagate Custom Trace Headers Manually
// Import necessary Spring Boot and Micrometer libraries
import org.slf4j.MDC;
import org.springframework.http.HttpHeaders;
import org.springframework.web.filter.OncePerRequestFilter;
import javax.servlet.FilterChain;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class CustomTraceFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
            throws IOException {
        String traceId = request.getHeader("ot-custom-traceid");
        String spanId = request.getHeader("ot-custom-spanid");
        try {
            if (traceId != null) {
                MDC.put("traceId", traceId); // Add traceId to Mapped Diagnostic Context
            }
            if (spanId != null) {
                MDC.put("spanId", spanId);
            }
            filterChain.doFilter(request, response); // Continue request processing
        } finally {
            MDC.clear(); // Ensure MDC is cleared after processing
        }
    }
}

// Register the filter in your configuration class
@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean<CustomTraceFilter> traceFilter() {
        FilterRegistrationBean<CustomTraceFilter> registrationBean = new FilterRegistrationBean<>();
        registrationBean.setFilter(new CustomTraceFilter());
        registrationBean.addUrlPatterns("/*");
        return registrationBean;
    }
}

// Import necessary libraries
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@WebMvcTest
public class CustomTraceFilterTest {
    @Autowired
    private MockMvc mockMvc;

    @Test
    public void testCustomTraceHeaders() throws Exception {
        mockMvc.perform(get("/test-endpoint")
                .header("ot-custom-traceid", "12345")
                .header("ot-custom-spanid", "67890"))
                .andExpect(status().isOk());
    }
}

// Import necessary libraries
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpRequest;
import org.springframework.http.client.ClientHttpRequestExecution;
import org.springframework.http.client.ClientHttpRequestInterceptor;
import org.springframework.http.client.ClientHttpResponse;
import org.springframework.web.client.RestTemplate;
import java.io.IOException;

public class CustomHeaderInterceptor implements ClientHttpRequestInterceptor {
    @Override
    public ClientHttpResponse intercept(HttpRequest request, byte[] body, ClientHttpRequestExecution execution) throws IOException {
        HttpHeaders headers = request.getHeaders();
        headers.add("ot-custom-traceid", "12345");
        headers.add("ot-custom-spanid", "67890");
        return execution.execute(request, body);
    }
}

// Register the interceptor with RestTemplate
@Configuration
public class RestTemplateConfig {
    @Bean
    public RestTemplate restTemplate() {
        RestTemplate restTemplate = new RestTemplate();
        restTemplate.getInterceptors().add(new CustomHeaderInterceptor());
        return restTemplate;
    }
}

Obsługa niestandardowych śladów nagłówka za pomocą OpenTelemetry w Spring Boot 3.4

Podczas pracy z Spring Boot 3.4 kolejnym skutecznym podejściem do propagowania śladów z niestandardowych nagłówków jest integracja OtwórzTelemetrię. OpenTelemetry, platforma obserwowalności typu open source, pomaga bezproblemowo instrumentować, gromadzić i eksportować ślady. Zapewnia mechanizmy wyodrębniania i wstrzykiwania kontekstu śledzenia, w tym niestandardowych nagłówków, takich jak ot-custom-traceid I ot-niestandardowy-hiszpański, do swojej aplikacji. Wykorzystując TextMapPropagator OpenTelemetry, możesz wypełnić lukę pomiędzy niestandardowymi klientami a systemem obserwowalności.

Aby użyć OpenTelemetry w Spring Boot 3.4, można zaimplementować niestandardowy propagator w celu wyodrębnienia informacji o śledzeniu z niestandardowych nagłówków i dołączenia ich do bieżącego kontekstu śledzenia. Na przykład, gdy serwer otrzyma żądanie przychodzące od Klienta drugiego, OpenTelemetry może przeanalizować niestandardowe nagłówki i zrekonstruować oryginalny kontekst śledzenia. Dzięki temu usługi niższego szczebla widzą te same identyfikatory śledzenia, co pozwala na kompleksową widoczność. W przeciwieństwie do starszych rozwiązań, takich jak Spring Cloud Sleuth, OpenTelemetry jest lekki i zgodny z nowoczesnymi standardami obserwowalności.

Łącząc propagator OpenTelemetry z Micrometer, możesz wzbogacić swoje metryki i rejestrowanie o informacje o śledzeniu. Wyobraź sobie, że widzisz w swoim narzędziu obserwowalności ślady żądań pochodzących zarówno od Klienta Pierwszego, jak i Klienta Drugiego. OpenTelemetry automatycznie obsługuje integracje z Prometheusem, Zipkinem lub Jaegerem, umożliwiając centralizację wizualizacji śladów. Takie podejście gwarantuje, że nawet w przypadku użycia niestandardowych nagłówków żadne dane śledzenia nie zostaną utracone, a debugowanie stanie się znacznie łatwiejsze. 🚀