Journalisation des erreurs réseau (NEL)

Eric Bidelman

Maud Nalpas

Introduction

La journalisation des erreurs réseau (NEL, Network Error Logging) 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.

Attention : Pour configurer la journalisation des erreurs réseau pour votre site, vous devez utiliser l'ancienne API Reporting qui repose sur l'en-tête Report-To. En effet, la nouvelle API Reporting, qui repose sur l'en-tête Reporting-Endpoints, n'est pas compatible avec la journalisation des erreurs réseau. Pour en savoir plus, consultez Compatibilité des navigateurs. Nous développerons à l'avenir un nouveau mécanisme de journalisation des erreurs réseau. Une fois cette fonctionnalité disponible, passez de l'ancienne API Reporting à ce nouveau mécanisme.

Présentation de l'ancienne API Reporting

L'ancien en-tête Report-To

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 puisse signaler des 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 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 tableau max_age et un tableau endpoints. Vous pouvez également choisir de tenir compte des sous-domaines lorsque vous signalez les erreurs à l'aide du champ include_subdomains.

Champ	Type	Description
group	chaîne	Facultatif. Si aucun nom group n'est spécifié, le nom du point de terminaison est "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 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. Booléen qui active le groupe de points de terminaison pour tous les sous-domaines de l'hôte de l'origine actuelle. En cas d'omission ou de toute autre valeur que "true", les sous-domaines ne sont pas signalés au point de terminaison.

Le nom group est un nom unique permettant d'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 indique 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 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.

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

Les rapports sont fournis hors bande à partir de votre application, ce qui signifie que le navigateur contrôle à quel moment les rapports sont envoyés à vos serveurs.

Le navigateur tente de fournir des rapports en file d'attente au moment le plus opportun. Cela peut se produire dès qu'ils sont prêts (afin de fournir des commentaires au développeur en temps opportun), mais le navigateur peut également retarder la livraison s'il est occupé à traiter des tâches de priorité supérieure, ou si l'utilisateur se trouve sur un réseau lent et/ou encombré à 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 régulier.

L'utilisation de l'API Reporting ne présente que peu ou pas de problème de performances (conflit de réseau avec votre application, par exemple). Il est également impossible 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 tous ces avertissements/erreurs de console à vos URL.

Basculement et équilibrage de charge

La plupart du temps, vous configurez un collecteur d'URL par groupe. Toutefois, comme les rapports peuvent générer une grande 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 fera de son mieux pour fournir un rapport à au maximum un 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 des 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 l'importation vers les collecteurs principaux échoue.

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 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 ayant la même origine et continueront à 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 les champs max_age et 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}

Attention : L'en-tête Report-To utilise un trait d'union. Ici, report_to utilise un trait de soulignement.

Sous-ressources

Important : La NEL fonctionne avec les navigations et les extractions de sous-ressources. En revanche, pour les sous-ressources, la page parent n'a aucune visibilité sur les rapports NEL concernant les requêtes multi-origines qu'elle envoie.

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

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

En règle générale, NEL reproduit les journaux côté serveur, qui sont simplement générés sur le client.

Comme example.com n'a pas de visibilité dans les journaux de 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 envoyés correctement.

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. Il explique comment configurer la création de rapports sur 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}`);
});

Complément d'informations

• Surveiller votre application Web avec l'API Reporting (article principal sur l'API Reporting)
• Guide de migration de l'API Reporting v0 vers la version v1
• Spécification: ancienne API Reporting (v0)
• Spécification: nouvelle API Reporting (v1)