Netzwerkfehler-Logging (NEL)

Maud Nalpas
Maud Nalpas
X GitHub

Einführung

Die Netzwerkfehlerprotokollierung (Network Error Logging, NEL) ist ein Mechanismus zum Erfassen von clientseitigen Netzwerkfehlern von einem Ursprung.

Über den NEL-HTTP-Antwortheader wird der Browser angewiesen, Netzwerkfehler zu erfassen. Anschließend werden die Fehler über die Reporting API an einen Server gesendet.

Die alte Reporting API

Wenn Sie die bisherige Reporting API verwenden möchten, müssen Sie einen Report-To-HTTP-Antwortheader festlegen. Der Wert ist ein Objekt, das eine Endpunktgruppe für den Browser beschreibt, an die Fehler gemeldet werden sollen:

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

Wenn sich die Endpunkt-URL an einem anderen Ursprung als Ihre Website befindet, sollte der Endpunkt CORS-Preflight-Anfragen unterstützen. (z.B. 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).

Im Beispiel wird der Browser so konfiguriert, dass er browsergenerierte Warnungen für max_age Sekunden an den Endpunkt https://analytics.provider.com/browser-errors meldet, wenn dieser Antwortheader mit der Startseite gesendet wird. Beachten Sie, dass alle nachfolgenden HTTP-Anfragen von der Seite (z. B. Bilder, Skripts usw.) ignoriert werden. Die Konfiguration wird während der Antwort der Hauptseite eingerichtet.

Kopfzeilenfelder

Jede Endpunktkonfiguration enthält einen group-Namen, ein max_age- und ein endpoints-Array. Im Feld include_subdomains können Sie auch festlegen, ob Subdomains bei der Meldung von Fehlern berücksichtigt werden sollen.

Feld Typ Beschreibung
group String Optional. Wenn kein group-Name angegeben ist, erhält der Endpunkt den Namen „default“.
max_age Zahl Erforderlich. Eine positive Ganzzahl, die die Lebensdauer des Endpunkts in Sekunden definiert. Wenn der Wert „0“ ist, wird die Endpunktgruppe aus dem Berichtscache des User-Agents entfernt.
endpoints Array<Object> Erforderlich. Ein Array von JSON-Objekten, das die tatsächliche URL Ihres Berichts-Collectors angibt.
include_subdomains boolean Optional. Ein boolescher Wert, mit dem die Endpunktgruppe für alle Subdomains des Hosts des aktuellen Ursprungs aktiviert wird. Wenn der Parameter fehlt oder einen anderen Wert als „true“ hat, werden die Subdomains nicht an den Endpunkt gesendet.

Der group-Name ist ein eindeutiger Name, mit dem ein String einem Endpunkt zugeordnet wird. Verwenden Sie diesen Namen an anderen Stellen, an denen die Reporting API eingebunden wird, um auf eine bestimmte Endpunktgruppe zu verweisen.

Das Feld max-age ist ebenfalls erforderlich und gibt an, wie lange der Browser den Endpunkt verwenden und Fehler an ihn melden soll.

Das Feld endpoints ist ein Array, das Failover- und Load Balancing-Funktionen bereitstellt. Weitere Informationen finden Sie im Abschnitt Failover und Load Balancing. Beachten Sie, dass der Browser nur einen Endpunkt auswählt, auch wenn die Gruppe mehrere Collectors in endpoints auflistet. Wenn Sie einen Bericht an mehrere Server gleichzeitig senden möchten, muss Ihr Backend die Berichte weiterleiten.

Wie sendet der Browser Berichte?

Der Browser erstellt regelmäßig Batch-Berichte und sendet sie an die von Ihnen konfigurierten Endpunkte für die Berichterstellung.

Zum Senden von Berichten sendet der Browser eine POST-Anfrage mit Content-Type: application/reports+json und einem Textkörper, der das Array der erfassten Warnungen/Fehler enthält.

Wann sendet der Browser Berichte?

Berichte werden Out-of-Band von Ihrer Anwendung bereitgestellt. Das bedeutet, dass der Browser steuert, wann Berichte an Ihren oder Ihre Server gesendet werden.

Der Browser versucht, Berichte in der Warteschlange zum optimalen Zeitpunkt zu senden. Dies kann geschehen, sobald sie bereit sind, um dem Entwickler zeitnah Feedback zu geben. Der Browser kann die Übermittlung aber auch verzögern, wenn er gerade mit der Verarbeitung von Arbeiten mit höherer Priorität beschäftigt ist oder wenn der Nutzer zu diesem Zeitpunkt ein langsames und/oder überlastetes Netzwerk verwendet. Der Browser kann das Senden von Berichten zu einem bestimmten Ursprung auch zuerst priorisieren, wenn der Nutzer häufig besucht wird.

Bei der Verwendung der Reporting API gibt es kaum bis keine Leistungsbedenken (z.B. Netzwerkkonflikte mit Ihrer App). Außerdem lässt sich nicht steuern, wann der Browser Berichte in der Warteschlange sendet.

Mehrere Endpunkte konfigurieren

Mit einer einzigen Antwort können mehrere Endpunkte gleichzeitig konfiguriert werden, indem mehrere Report-To-Header gesendet werden:

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"
             }]
           }

oder indem Sie sie in einem einzigen HTTP-Header kombinieren:

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"
             }]
           }

Nachdem Sie die Report-To-Header gesendet haben, speichert der Browser die Endpunkte gemäß ihren max_age-Werten im Cache und sendet alle diese üblen Konsolenwarnungen/-fehler an Ihre URLs.

Failover und Load Balancing

In den meisten Fällen konfigurieren Sie einen URL-Collector pro Gruppe. Da die Berichterstellung jedoch viel Traffic generieren kann, enthält die Spezifikation Failover- und Load-Balancing-Funktionen, die vom DNS-SRV-Eintrag inspiriert sind.

Der Browser versucht, einen Bericht an höchstens einen Endpunkt in einer Gruppe zu senden. Endpunkten kann eine weight zugewiesen werden, um die Last zu verteilen. Dabei erhält jeder Endpunkt einen bestimmten Anteil des Berichtstraffics. Endpunkte kann auch ein priority zugewiesen werden, um Fallback-Collectors einzurichten.

Fallback-Collectors werden nur dann verwendet, wenn Uploads an primäre Collectors fehlschlagen.

Beispiel: Erstellen Sie einen Fallback-Collector unter 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}
             ]
           }

Netzwerkfehlerprotokollierung einrichten

Einrichtung

Wenn Sie NEL verwenden möchten, richten Sie die Report-To-Überschrift mit einem Collector ein, der eine benannte Gruppe verwendet:

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

Senden Sie als Nächstes den NEL-Antwortheader, um mit dem Erfassen von Fehlern zu beginnen. Da NEL für einen Ursprung aktiviert werden muss, müssen Sie den Header nur einmal senden. Sowohl NEL als auch Report-To werden auf zukünftige Anfragen an denselben Ursprung angewendet und es werden weiterhin Fehler gemäß dem max_age-Wert erfasst, der zum Einrichten des Collectors verwendet wurde.

Der Headerwert muss ein JSON-Objekt sein, das ein max_age- und ein report_to-Feld enthält. Verwenden Sie letzteren, um auf den Gruppennamen Ihres Netzwerkfehler-Collectors zu verweisen:

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

Unterressourcen

Beispiel: Wenn example.com foobar.com/cat.gif lädt und diese Ressource nicht geladen werden kann:

  • Der NEL-Abholer von foobar.com wird benachrichtigt
  • Der NEL-Abholer von example.com wird nicht benachrichtigt

Als Faustregel gilt, dass NEL serverseitige Protokolle reproduziert, die gerade auf dem Client generiert wurden.

Da example.com keinen Zugriff auf die Serverprotokolle von foobar.com hat, kann es auch nicht auf die NEL-Berichte zugreifen.

Berichtskonfigurationen debuggen

Wenn auf Ihrem Server keine Berichte angezeigt werden, rufen Sie chrome://net-export/ auf. Auf dieser Seite können Sie überprüfen, ob alles richtig konfiguriert ist und Berichte ordnungsgemäß gesendet werden.

Was ist mit ReportingObserver?

ReportingObserver ist ein ähnlicher, aber anderer Berichtsmechanismus. Er basiert auf JavaScript-Aufrufen. Sie eignet sich nicht für die Protokollierung von Netzwerkfehlern, da Netzwerkfehler nicht über JavaScript abgefangen werden können.

Beispielserver

Unten sehen Sie ein Beispiel für einen Node-Server, der Express verwendet. Es wird gezeigt, wie die Berichterstellung für Netzwerkfehler konfiguriert wird, und es wird ein spezieller Handler zum Erfassen des Ergebnisses erstellt.

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}`);
});

Weitere Informationen