Logowanie błędów sieciowych (NEL)

Eric Bidelman

Maud Nalpas

Wstęp

Logowanie błędów sieci (NEL) to mechanizm służący do zbierania błędów sieci po stronie klienta z punktu początkowego.

Korzysta ono z nagłówka odpowiedzi HTTP NEL, aby informować przeglądarkę, że ma zbierać błędy sieci, a potem integruje się z interfejsem API do raportowania, by zgłaszać te błędy do serwera.

Omówienie starszej wersji interfejsu API do raportowania

Starszy nagłówek Report-To

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

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

Jeśli URL punktu końcowego znajduje się w innym źródle 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 zgłasza ostrzeżenia generowane 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ę (w przypadku obrazów, skryptów itp.) są ignorowane. Konfiguracja jest konfigurowana podczas odpowiedzi na stronę główną.

Objaśnienie pól nagłówka

Każda konfiguracja punktu końcowego zawiera nazwę group, max_age i tablicę endpoints. Korzystając z pola include_subdomains, możesz też określić, czy przy zgłaszaniu błędów mają być uwzględniane subdomeny.

Nazwa group to unikalna nazwa używana do powiązania ciągu z punktem końcowym. Używaj tej nazwy w innych miejscach zintegrowanych z interfejsem API do raportowania, by odwołać 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ć mu błędy.

Pole endpoints to tablica do przełączania awaryjnego i równoważenia obciążenia. Więcej informacji znajdziesz w sekcji 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 endpoints. Jeśli chcesz wysłać raport na kilka serwerów jednocześnie, Twój backend musi to zrobić.

W jaki sposób przeglądarka wysyła raporty?

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

Aby wysyłać raporty, przeglądarka wysyła żądanie POST z elementem 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 z aplikacji poza zakresem, co oznacza, że to przeglądarka kontroluje, kiedy raporty są wysyłane na Twoje serwery.

Przeglądarka próbuje dostarczyć raporty w kolejce w najodpowiedniejszym czasie. Przeglądarka może też opóźnić wyświetlenie, gdy tylko będzie gotowe (aby szybko przekazać informacje deweloperowi), ale może też opóźnić dostarczanie, jeśli jej przetwarzanie ma wyższy priorytet lub użytkownik korzysta w danym czasie z wolnej lub zatłoczonej sieci. Przeglądarka może też priorytetowo wysyłać raporty o konkretnym pochodzeniu, jeśli użytkownik jest często odwiedzany.

Podczas korzystania z interfejsu API do raportowania nie musisz mieć żadnych problemów z wydajnością (np. rywalizacji o sieć aplikacji). Nie ma też możliwości kontrolowania, kiedy przeglądarka wysyła raporty w kolejce.

Konfigurowanie wielu punktów końcowych

Pojedyncza odpowiedź może skonfigurować kilka punktów końcowych jednocześnie przez wysłanie wielu 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"
             }]
           }

Gdy wyślesz nagłówek Report-To, przeglądarka zapisze punkty końcowe w pamięci podręcznej zgodnie z wartościami max_age i wyśle wszystkie te nieprzyjemne ostrzeżenia/błędy konsoli do Twoich adresów URL.

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

Najczęściej będziesz konfigurować po jednym kolektorze adresów URL dla każdej grupy. Raportowanie może jednak generować duży ruch, więc specyfikacja obejmuje funkcje przełączania awaryjnego i równoważenia obciążenia inspirowane rekordem SRV DNS.

Przeglądarka dołoży wszelkich starań, aby przesłać raport do co najmniej jednego punktu końcowego w grupie. Do punktów końcowych można przypisać weight, aby rozłożyć obciążenie, przy czym każdy punkt końcowy otrzymuje określoną część ruchu objętego raportowaniem. Do punktów końcowych można też przypisać element priority, aby skonfigurować zastępcze kolektory.

Kolektory zastępcze są używane tylko w przypadku niepowodzenia przesyłania do kolektorów głównych.

Przykład: utwórz zastępczy kolektor w środowisku 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}
             ]
           }

Konfiguruję logowanie błędów sieci

Konfiguracja

Aby użyć NEL, skonfiguruj nagłówek Report-To za pomocą kolektora, który korzysta z grupy nazwanej:

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ż opcja NEL jest włączona dla punktu początkowego, wystarczy wysłać nagłówek tylko raz. Zarówno NEL, jak i Report-To będą stosowane w przypadku przyszłych żądań wysyłanych do tego samego punktu początkowego i będą nadal zbierać błędy zgodnie z wartością max_age użytej do skonfigurowania kolektora.

Wartość nagłówka powinien być obiektem JSON zawierającym pole max_age i report_to. Użyj tego drugiego, 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 wczyta foobar.com/cat.gif i nie uda się wczytać tego zasobu:

• Kolektor NEL użytkownika foobar.com otrzyma powiadomienie
• Kolektor NEL użytkownika example.com nie otrzymuje powiadomienia

Ogólna zasada jest taka, że NEL odtwarza logi po stronie serwera wygenerowane przed chwilą dla klienta.

example.com nie ma dostępu do dzienników serwera foobar.com, więc nie ma wglądu w raporty NEL.

Konfiguracje raportu debugowania

Jeśli nie widzisz raportów na swoim serwerze, wejdź na chrome://net-export/. Przydaje się ona do sprawdzania, czy wszystko jest skonfigurowane prawidłowo, a raporty są prawidłowo wysyłane.

A co z funkcją ReportingObserver?

ReportingObserver to powiązany, ale inny mechanizm raportowania. który opiera się na wywołaniach JavaScriptu. Nie nadaje się do rejestrowania błędów sieciowych, ponieważ błędów sieci nie można przechwycić za pomocą JavaScriptu.

Przykładowy serwer

Poniżej znajdziesz przykładowy serwer węzłów, który używa Express. Pokazuje on, jak skonfigurować raportowanie błędów sieci, oraz tworzy specjalny moduł obsługi do rejestrowania 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

• Monitorowanie aplikacji internetowej przy użyciu interfejsu API do raportowania (główny post o interfejsie API do raportowania)
• Przewodnik po migracji z interfejsu Reporting API z wersji 0 do wersji 1
• Specyfikacja: starszy interfejs API do raportowania (v0)
• Specyfikacja: nowy interfejs API do raportowania (v1)