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, ne prend pas en charge la journalisation des erreurs réseau. Pour en savoir plus, consultez Navigateurs compatibles. À la place, un nouveau mécanisme de journalisation des erreurs réseau sera développé à l'avenir. Une fois qu'elle sera 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 auquel le navigateur doit signaler 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 préliminaires CORS. (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 de prendre en compte les sous-domaines lors du signalement des 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. Une valeur de "0" entraîne la suppression du groupe de points de terminaison du cache de rapports de l'user-agent.
endpoints	Tableau<Objet>	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 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 dans d'autres emplacements 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. 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 permettant de fournir 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électionnera 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 devra transférer les rapports.

Comment le navigateur envoie-t-il des rapports ?

Le navigateur regroupe régulièrement les rapports et les envoie aux points de terminaison de reporting 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 hors bande depuis votre application, ce qui signifie que le navigateur contrôle le moment où les rapports sont envoyés à vos serveurs.

Le navigateur tente de diffuser les rapports mis en file d'attente au moment le plus opportun. Cela peut se faire 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 diffusion s'il est occupé à traiter des tâches plus prioritaires, 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 si l'utilisateur la consulte fréquemment.

L'utilisation de l'API Reporting n'entraîne que peu ou pas de problèmes de performances (par exemple, une contention 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 tous ces avertissements/erreurs de console désagréables à vos URL.

Basculement et équilibrage de charge

La plupart du temps, vous configurerez un collecteur d'URL par groupe. Toutefois, étant donné que les rapports peuvent générer un trafic important, 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 envoyer un rapport à au plus 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 de reporting. Vous pouvez également attribuer un priority 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 sur 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 Network Error Logging

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

Ensuite, envoyez l'en-tête de réponse NEL pour commencer à collecter les erreurs. Comme 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 vers 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 un champ max_age et un champ report_to. Utilisez ce dernier pour référencer le nom du 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

Point clé  : NEL fonctionne pour les navigations et les récupérations de sous-ressources. En revanche, pour les sous-ressources, la page conteneur n'a aucune visibilité sur les rapports NEL concernant les requêtes interorigines qu'elle effectue.

Exemple : Si example.com charge foobar.com/cat.gif et que le chargement de cette ressource échoue :

• 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 viennent d'être générés sur le client.

Comme example.com n'a pas de visibilité sur 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 vous ne voyez pas de rapports s'afficher sur votre serveur, accédez à chrome://net-export/. Cette page est utile pour vérifier que tout est configuré correctement et que les rapports sont envoyés comme prévu.

Qu'en est-il de ReportingObserver ?

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

Exemple de serveur

Vous trouverez ci-dessous un exemple de serveur Node qui utilise Express. Il 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

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