Journalisation des erreurs réseau (NEL)

Maud Nalpas
Maud Nalpas
X GitHub

Introduction

La journalisation des erreurs réseau (NEL) est un mécanisme permettant de collecter les erreurs réseau côté client à partir d'une origine.

Il utilise l'en-tête de réponse HTTP NEL pour indiquer au navigateur de collecter les erreurs réseau, puis s'intègre à l'API Reporting pour signaler les erreurs à un serveur.

Présentation de l'ancienne API Reporting

Pour utiliser l'ancienne API Reporting, vous devez définir un en-tête de réponse HTTP Report-To. Sa valeur est un objet qui décrit un groupe de points de terminaison auquel le navigateur peut signaler les erreurs:

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

Si votre URL de point de terminaison se trouve sur une origine différente de celle de votre site, le point de terminaison doit être compatible avec les requêtes CORS préliminaires. (par exemple, 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).

Dans l'exemple, l'envoi de cet en-tête de réponse avec votre page principale configure le navigateur pour qu'il signale les avertissements générés par le navigateur au point de terminaison https://analytics.provider.com/browser-errors pendant max_age secondes. Il est important de noter que toutes les requêtes HTTP ultérieures effectuées par la page (pour les images, les scripts, etc.) sont ignorées. La configuration est définie lors de la réponse de la page principale.

Explication des champs d'en-tête

Chaque configuration de point de terminaison contient un nom group, un max_age et un tableau endpoints. Vous pouvez également choisir d'utiliser des sous-domaines lorsque vous signalez des erreurs à l'aide du champ include_subdomains.

Champ Type Description
group chaîne Facultatif. Si aucun nom group n'est spécifié, "default" est attribué au point de terminaison.
max_age number Obligatoire : Entier non négatif qui définit la durée de vie du point de terminaison en secondes. La valeur "0" entraîne la suppression du groupe de points de terminaison du cache des rapports du user-agent.
endpoints Tableau<Objet> Obligatoire : Tableau d'objets JSON qui spécifient l'URL réelle de votre collecteur de rapports.
include_subdomains boolean Facultatif. Valeur booléenne qui active le groupe de points de terminaison pour tous les sous-domaines de l'hôte de l'origine actuelle. Si cette valeur est omise ou s'il existe une valeur autre que "true", les sous-domaines ne sont pas signalés au point de terminaison.

Le nom group est un nom unique utilisé pour associer une chaîne à un point de terminaison. Utilisez ce nom à d'autres emplacements liés à l'API Reporting pour faire référence à un groupe de points de terminaison spécifique.

Le champ max-age est également obligatoire. Il spécifie la durée pendant laquelle le navigateur doit utiliser le point de terminaison et lui signaler les erreurs.

Le champ endpoints est un tableau fournissant des fonctionnalités de basculement et d'équilibrage de charge. Consultez la section Basculement et équilibrage de charge. Il est important de noter que le navigateur ne sélectionne qu'un seul point de terminaison, même si le groupe répertorie plusieurs collecteurs dans endpoints. Si vous souhaitez envoyer un rapport à plusieurs serveurs à la fois, votre backend doit transférer les rapports.

Comment le navigateur envoie-t-il les rapports ?

Le navigateur regroupe régulièrement les rapports et les envoie aux points de terminaison de création de rapports que vous configurez.

Pour envoyer des rapports, le navigateur émet une requête POST avec Content-Type: application/reports+json et un corps contenant le tableau des avertissements/erreurs capturés.

À quel moment le navigateur envoie-t-il des rapports ?

Les rapports sont transmis hors bande depuis votre application, ce qui signifie que le navigateur contrôle l'envoi des rapports à vos serveurs.

Le navigateur tente d'envoyer les rapports en file d'attente au moment le plus opportun. Cela peut être fait dès qu'ils sont prêts (afin de fournir des commentaires en temps opportun au développeur), mais le navigateur peut également retarder la livraison s'il est occupé à traiter des tâches prioritaires, ou si l'utilisateur est sur un réseau lent et/ou encombré à ce moment-là. Le navigateur peut également donner la priorité à l'envoi en priorité des rapports sur une origine particulière, si l'utilisateur est un visiteur régulier.

L'utilisation de l'API Reporting ne présente pas de problèmes de performances (par exemple, des conflits de réseau avec votre application). Il n'existe également aucun moyen de contrôler à quel moment le navigateur envoie des rapports en file d'attente.

Configurer plusieurs points de terminaison

Une seule réponse peut configurer plusieurs points de terminaison à la fois en envoyant plusieurs en-têtes 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"
             }]
           }

ou en les combinant dans un seul en-tête 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"
             }]
           }

Une fois que vous avez envoyé l'en-tête Report-To, le navigateur met en cache les points de terminaison en fonction de leurs valeurs max_age et envoie à vos URL tous ces avertissements et erreurs de la console.

Basculement et équilibrage de charge

La plupart du temps, vous allez configurer un collecteur d'URL par groupe. Toutefois, comme les rapports peuvent générer une bonne quantité de trafic, la spécification inclut des fonctionnalités de basculement et d'équilibrage de charge inspirées de l'enregistrement SRV DNS.

Le navigateur s'efforce de fournir le rapport à au maximum un point de terminaison d'un groupe. Les points de terminaison peuvent se voir attribuer un weight pour répartir la charge, chaque point de terminaison recevant une fraction spécifiée du trafic de rapports. Un priority peut également être attribué à Endpoints pour configurer des collecteurs de remplacement.

Les collecteurs de remplacement ne sont essayés que lorsque les importations vers les collecteurs principaux échouent.

Exemple: Créez un collecteur de remplacement dans 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}
             ]
           }

Configurer la journalisation des erreurs réseau

Préparation

Pour utiliser NEL, configurez l'en-tête Report-To avec un collecteur qui utilise un groupe nommé:

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

Envoyez ensuite l'en-tête de réponse NEL pour commencer à collecter les erreurs. Étant donné que NEL est activé pour une origine, vous n'avez besoin d'envoyer l'en-tête qu'une seule fois. NEL et Report-To s'appliqueront aux futures requêtes à la même origine et continueront à collecter des erreurs en fonction de la valeur max_age utilisée pour configurer le collecteur.

La valeur d'en-tête doit être un objet JSON contenant un champ max_age et un champ report_to. Utilisez ce dernier pour référencer le nom de groupe de votre collecteur d'erreurs réseau:

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

Sous-ressources

Exemple: Si example.com charge foobar.com/cat.gif et que cette ressource ne se charge pas:

  • Le collecteur NEL de foobar.com a été averti
  • Le collecteur NEL de example.com n'est pas averti

En règle générale, NEL reproduit les journaux côté serveur qui viennent d'être générés sur le client.

Comme example.com n'a aucune visibilité sur les journaux du serveur de foobar.com, il n'a pas non plus de visibilité sur ses rapports NEL.

Configurations des rapports de débogage

Si aucun rapport ne s'affiche sur votre serveur, accédez à chrome://net-export/. Cette page est utile pour vérifier que les éléments sont correctement configurés et que les rapports sont correctement envoyés.

Qu'en est-il de ReportingObserver ?

ReportingObserver est un mécanisme de reporting connexe, mais différent. Il est basé sur les appels JavaScript. Elle n'est pas adaptée à la journalisation des erreurs réseau, car les erreurs réseau ne peuvent pas être interceptées via JavaScript.

Exemple de serveur

Vous trouverez ci-dessous un exemple de serveur Node qui utilise Express. Elle montre comment configurer la création de rapports pour les erreurs réseau et crée un gestionnaire dédié pour capturer le résultat.

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

Documentation complémentaire