Logowanie błędów sieciowych (NEL)

Maud Nalpas

Wprowadzenie

Network Error Logging (NEL) to mechanizm zbierania błędów sieci po stronie klienta z źródła.

Używa nagłówka odpowiedzi HTTP NEL, aby poinformować przeglądarkę o konieczności zbierania błędów sieci, a następnie integruje się z interfejsem Reporting API, aby zgłaszać błędy serwerowi.

Omówienie starszej wersji interfejsu Reporting API

Aby korzystać ze starszej wersji interfejsu Reporting API, musisz ustawić nagłówek odpowiedzi HTTP Report-To. Jego wartość to obiekt opisujący grupę punktów końcowych, do której przeglądarka ma zgłaszać błędy:

Report-To:
{
    "max_age": 10886400,
    "endpoints": [{
    "url": "https://analytics.provider.com/browser-errors"
    }]
}

Jeśli adres URL punktu końcowego znajduje się w innym miejscu niż Twoja witryna, punkt końcowy powinien obsługiwać żądania wstępne CORS. (np. Access-Control-Allow-Origin: *; Access-Control-Allow-Methods: GET,PUT,POST,DELETE,OPTIONS; Access-Control-Allow-Headers: Content-Type, Authorization, Content-Length, X-Requested-With).

W tym przykładzie wysłanie tego nagłówka odpowiedzi ze stroną główną powoduje, że przeglądarka jest skonfigurowana do raportowania ostrzeżeń generowanych przez przeglądarkę do punktu końcowego https://analytics.provider.com/browser-errors przez max_age s. Pamiętaj, że wszystkie kolejne żądania HTTP wysyłane przez stronę (dotyczące obrazów, skryptów itp.) są ignorowane. Konfiguracja jest konfigurowana podczas odpowiedzi strony głównej.

Objaśnienie pól nagłówka

Każda konfiguracja punktu końcowego zawiera nazwę group, max_age i tablicę endpoints. Możesz też wybrać, czy podczas raportowania błędów mają być uwzględniane subdomeny, używając pola include_subdomains.

Pole Typ Opis
group tekst Opcjonalnie: Jeśli nie podasz nazwy group, punkt końcowy otrzyma nazwę „default”.
max_age liczba Wymagany. Nieujemna liczba całkowita, która określa czas życia punktu końcowego w sekundach. Wartość „0” spowoduje usunięcie grupy punktów końcowych z pamięci podręcznej raportowania klienta użytkownika.
endpoints Array<Object> Wymagany. Tablica obiektów JSON, które określają rzeczywisty adres URL modułu zbierającego raporty.
include_subdomains wartość logiczna Opcjonalnie: Wartość logiczna, która włącza grupę punktów końcowych dla wszystkich subdomen hosta bieżącego źródła. Jeśli ta wartość zostanie pominięta lub będzie inna niż „true”, subdomeny nie będą raportowane do punktu końcowego.

Nazwa group to unikalna nazwa używana do powiązania ciągu znaków z punktem końcowym. Używaj tej nazwy w innych miejscach, które są zintegrowane z interfejsem Reporting API, aby odwoływać się do konkretnej grupy punktów końcowych.

Pole max-age jest również wymagane i określa, jak długo przeglądarka powinna używać punktu końcowego i zgłaszać do niego błędy.

Pole endpoints to tablica, która zapewnia funkcje przełączania awaryjnego i równoważenia obciążenia. Zobacz sekcję Przełączanie awaryjne i równoważenie obciążenia. Pamiętaj, że przeglądarka wybierze tylko 1 punkt końcowy, nawet jeśli grupa zawiera kilka kolektorów w nagłówku endpoints. Jeśli chcesz wysłać raport do kilku serwerów jednocześnie, Twój backend będzie musiał przekazywać raporty dalej.

Jak przeglądarka wysyła raporty?

Przeglądarka okresowo grupuje raporty i wysyła je do skonfigurowanych przez Ciebie punktów końcowych raportowania.

Aby wysłać raporty, przeglądarka wysyła żądanie POST z Content-Type: application/reports+json i treścią zawierającą tablicę przechwyconych ostrzeżeń/błędów.

Kiedy przeglądarka wysyła raporty?

Raporty są dostarczane poza pasmem z aplikacji, co oznacza, że przeglądarka kontroluje, kiedy raporty są wysyłane na serwery.

Przeglądarka próbuje dostarczyć raporty z kolejki w najbardziej odpowiednim momencie. Może to nastąpić, gdy tylko będą gotowe (aby zapewnić deweloperowi aktualne informacje zwrotne), ale przeglądarka może też opóźnić dostarczenie, jeśli jest zajęta przetwarzaniem zadań o wyższym priorytecie lub jeśli użytkownik korzysta w danym momencie z wolnej lub przeciążonej sieci. Przeglądarka może też priorytetowo traktować wysyłanie raportów o konkretnym źródle, jeśli użytkownik często je odwiedza.

Podczas korzystania z interfejsu Reporting API nie występują problemy z wydajnością (np. rywalizacja o sieć z aplikacją). Nie można też kontrolować, kiedy przeglądarka wysyła raporty z kolejki.

Konfigurowanie wielu punktów końcowych

Jedna odpowiedź może skonfigurować kilka punktów końcowych naraz, wysyłając wiele nagłówków Report-To:

Report-To: {
             "group": "default",
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/browser-reports"
             }]
           }
Report-To: {
             "group": "network-errors-endpoint",
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/network-errors"
             }]
           }

lub łącząc je w jeden nagłówek HTTP:

Report-To: {
             "group": "network-errors-endpoint",
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/network-errors"
             }]
           },
           {
             "max_age": 10886400,
             "endpoints": [{
               "url": "https://example.com/browser-errors"
             }]
           }

Po wysłaniu nagłówka Report-To przeglądarka zapisuje punkty końcowe w pamięci podręcznej zgodnie z ich wartościami max_age i wysyła wszystkie te nieprzyjemne ostrzeżenia i błędy konsoli na Twoje adresy URL.

Przełączanie awaryjne i równoważenie obciążenia

W większości przypadków będziesz konfigurować 1 kolektor adresów URL na grupę. Ponieważ jednak raportowanie może generować duży ruch, specyfikacja obejmuje funkcje przełączania awaryjnego i równoważenia obciążenia inspirowane rekordem SRV DNS.

Przeglądarka dołoży wszelkich starań, aby dostarczyć raport do co najwyżej jednego punktu końcowego w grupie. Punktom końcowym można przypisać weight, aby rozłożyć obciążenie, przy czym każdy punkt końcowy otrzymuje określoną część ruchu związanego z raportowaniem. Punktom końcowym można też przypisać priority, aby skonfigurować kolektory zastępcze.

Kolektory zastępcze są używane tylko wtedy, gdy nie uda się przesłać danych do kolektorów podstawowych.

Przykład: utwórz kolektor zastępczy w https://backup.com/reports:

Report-To: {
             "group": "endpoint-1",
             "max_age": 10886400,
             "endpoints": [
               {"url": "https://example.com/reports", "priority": 1},
               {"url": "https://backup.com/reports", "priority": 2}
             ]
           }

Konfigurowanie rejestrowania błędów sieci

Konfiguracja

Aby używać NEL, skonfiguruj nagłówek Report-To z kolektorem, który używa nazwanej grupy:

Report-To: {
    ...
  }, {
    "group": "network-errors",
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://analytics.provider.com/networkerrors"
    }]
  }

Następnie wyślij nagłówek odpowiedzi NEL, aby zacząć zbierać błędy. Ponieważ NEL jest opcjonalny dla źródła, wystarczy wysłać nagłówek tylko raz. Zarówno NEL, jak i Report-To będą stosowane do przyszłych żądań do tego samego źródła i będą nadal zbierać błędy zgodnie z wartością max_age, która została użyta do skonfigurowania modułu zbierającego.

Wartość nagłówka powinna być obiektem JSON zawierającym pola max_age i report_to. Użyj tej drugiej opcji, aby odwołać się do nazwy grupy kolektora błędów sieci:

GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}

Zasoby podrzędne

Przykład: jeśli example.com wczytuje foobar.com/cat.gif i nie uda się wczytać tego zasobu:

  • Kolektor NEL domeny foobar.com zostanie powiadomiony
  • Kolektor NEL domeny example.com nie jest powiadamiany

Zasadniczo NEL odtwarza logi po stronie serwera, które zostały wygenerowane na kliencie.

example.com nie ma dostępu do logów serwera foobar.com, więc nie ma też dostępu do raportów NEL.

Konfiguracje raportów debugowania

Jeśli nie widzisz raportów na serwerze, wejdź na chrome://net-export/. Ta strona jest przydatna do sprawdzania, czy wszystko jest prawidłowo skonfigurowane i czy raporty są wysyłane we właściwy sposób.

A co z ReportingObserver?

ReportingObserver to powiązany, ale inny mechanizm raportowania. Jest ona oparta na wywołaniach JavaScriptu. Nie nadaje się do rejestrowania błędów sieci, ponieważ nie można ich przechwytywać za pomocą JavaScriptu.

Przykładowy serwer

Poniżej znajdziesz przykładowy serwer Node, który używa Express. Pokazuje, jak skonfigurować raportowanie błędów sieci, i tworzy dedykowany moduł obsługi do przechwytywania wyników.

const express = require('express');

const app = express();
app.use(
  express.json({
    type: ['application/json', 'application/reports+json'],
  }),
);
app.use(express.urlencoded());

app.get('/', (request, response) => {
  // Note: report_to and not report-to for NEL.
  response.set('NEL', `{"report_to": "network-errors", "max_age": 2592000}`);

  // The Report-To header tells the browser where to send network errors.
  // The default group (first example below) captures interventions and
  // deprecation reports. Other groups, like the network-error group, are referenced by their "group" name.
  response.set(
    'Report-To',
    `{
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://reporting-observer-api-demo.glitch.me/reports"
    }],
  }, {
    "group": "network-errors",
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://reporting-observer-api-demo.glitch.me/network-reports"
    }]
  }`,
  );

  response.sendFile('./index.html');
});

function echoReports(request, response) {
  // Record report in server logs or otherwise process results.
  for (const report of request.body) {
    console.log(report.body);
  }
  response.send(request.body);
}

app.post('/network-reports', (request, response) => {
  console.log(`${request.body.length} Network error reports:`);
  echoReports(request, response);
});

const listener = app.listen(process.env.PORT, () => {
  console.log(`Your app is listening on port ${listener.address().port}`);
});

Więcej informacji