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 pour que le navigateur signale les erreurs:

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

Si l'URL de votre point de terminaison se trouve sur une origine différente de celle de votre site, le point de terminaison doit accepter 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 configurée 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 de prendre en compte les sous-domaines lors de la création de rapports d'erreurs à l'aide du champ include_subdomains.

Champ Type Description
group chaîne Facultatif. Si aucun nom group n'est spécifié, le point de terminaison est nommé "default".
max_age Nombre Obligatoire. Entier non négatif qui définit la durée de vie du point de terminaison en secondes. Si la valeur est "0", le groupe de points de terminaison est supprimé du cache de création de rapports de l'agent utilisateur.
endpoints Array<Object> Obligatoire. Tableau d'objets JSON qui spécifient l'URL réelle de votre collecteur de rapports.
include_subdomains booléen 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 elle est omise ou si elle est définie sur une autre valeur 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 endroits qui s'intègrent à l'API Reporting pour faire référence à un groupe de points de terminaison spécifique.

Le champ max-age est également obligatoire et 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 permettant de fournir des fonctionnalités de basculement et d'équilibrage de charge. Consultez la section Passage en mode de défaillance 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 le transférer.

Comment le navigateur envoie-t-il des 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.

Quand le navigateur envoie-t-il des rapports ?

Les rapports sont envoyés en dehors de la bande de votre application, ce qui signifie que le navigateur contrôle quand les rapports sont envoyés à vos serveurs.

Le navigateur tente d'envoyer les rapports mis en file d'attente au moment le plus opportun. Cela peut être dès qu'ils sont prêts (afin de fournir des commentaires opportuns au développeur), mais le navigateur peut également retarder la diffusion s'il est occupé à traiter une tâche de priorité plus élevée ou si l'utilisateur se trouve sur un réseau lent et/ou saturé à ce moment-là. Le navigateur peut également donner la priorité à l'envoi de rapports sur une origine particulière en premier, si l'utilisateur est un visiteur fréquent.

L'utilisation de l'API Reporting ne pose que peu ou pas de problèmes de performances (par exemple, conflit de réseau avec votre application). Il n'est pas non plus possible de contrôler le moment où le navigateur envoie les rapports mis 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 toutes ces avertissements/erreurs de console indésirables à vos URL.

Failover et équilibrage de charge

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

Le navigateur s'efforcera d'envoyer un rapport à un seul point de terminaison d'un groupe. Vous pouvez attribuer un weight aux points de terminaison pour répartir la charge, chaque point de terminaison recevant une fraction spécifiée du trafic de création de rapports. Un priority peut également être attribué aux points de terminaison 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 à 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

Configuration

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 la NEL est activée 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 vers la même origine et continueront de collecter les erreurs en fonction de la valeur max_age utilisée pour configurer le collecteur.

La valeur de l'en-tête doit être un objet JSON contenant un champ max_age et report_to. Utilisez ce dernier pour faire référence au 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 est informé
  • Le collecteur NEL de example.com n'est pas notifié

La règle d'or est que NEL reproduit les journaux côté serveur, qui sont générés sur le client.

Étant donné que 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 permet de vérifier que tout est correctement configuré et que les rapports sont correctement envoyés.

Qu'en est-il de ReportingObserver ?

ReportingObserver est un mécanisme de création de rapports lié, mais différent. Il est basé sur des appels JavaScript. Il n'est pas adapté à 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. Il explique comment configurer les 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