Registrazione degli errori di rete (NEL)

Maud Nalpas

Introduzione

Network Error Logging (NEL) è un meccanismo per raccogliere gli errori di rete lato client da un'origine.

Utilizza l'intestazione della risposta HTTP NEL per indicare al browser di raccogliere gli errori di rete, quindi si integra con l'API Reporting per segnalare gli errori a un server.

Panoramica dell'API di reporting precedente

Per utilizzare l'API di reporting precedente, devi impostare un'intestazione della risposta HTTP Report-To. Il suo valore è un oggetto che descrive un gruppo di endpoint a cui il browser deve segnalare gli errori:

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

Se l'URL dell'endpoint si trova su un'origine diversa rispetto al tuo sito, l'endpoint deve supportare le richieste preflight CORS. (ad es. 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).

Nell'esempio, l'invio di questa intestazione della risposta con la pagina principale configura il browser in modo che segnali gli avvisi generati dal browser all'endpoint https://analytics.provider.com/browser-errors per max_age secondi. È importante notare che tutte le richieste HTTP successive effettuate dalla pagina (per immagini, script e così via) vengono ignorate. La configurazione viene impostata durante la risposta della pagina principale.

Spiegazione dei campi di intestazione

Ogni configurazione di endpoint contiene un nome group, max_age e un array endpoints. Puoi anche scegliere se considerare i sottodomini quando segnali gli errori utilizzando il campo include_subdomains.

Campo Tipo Descrizione
group stringa Facoltativo. Se non viene specificato un nome group, all'endpoint viene assegnato il nome "default".
max_age numero Required. Un numero intero non negativo che definisce la durata dell'endpoint in secondi. Un valore pari a "0" comporta la rimozione del gruppo di endpoint dalla cache dei report dello user agent.
endpoints Array<Object> Required. Un array di oggetti JSON che specificano l'URL effettivo del tuo raccoglitore di report.
include_subdomains booleano Facoltativo. Un valore booleano che attiva il gruppo di endpoint per tutti i sottodomini dell'host dell'origine corrente. Se viene omesso o se viene impostato un valore diverso da "true", i sottodomini non vengono segnalati all'endpoint.

Il nome group è un nome univoco utilizzato per associare una stringa a un endpoint. Utilizza questo nome in altre posizioni che si integrano con l'API Reporting per fare riferimento a un gruppo di endpoint specifico.

Anche il campo max-age è obbligatorio e specifica per quanto tempo il browser deve utilizzare l'endpoint e segnalare gli errori.

Il campo endpoints è un array che fornisce funzionalità di failover e bilanciamento del carico. Consulta la sezione Failover e bilanciamento del carico. È importante notare che il browser selezionerà un solo endpoint, anche se l'elenco di gruppo elenca diversi agenti di raccolta in endpoints. Se vuoi inviare un report a più server contemporaneamente, il tuo backend dovrà inoltrare i report.

In che modo il browser invia i report?

Il browser raggruppa periodicamente i report e li invia agli endpoint di reporting configurati.

Per inviare i report, il browser invia una richiesta POST con Content-Type: application/reports+json e un corpo contenente l'array di avvisi/errori acquisiti.

Quando il browser invia i report?

I report vengono inviati fuori banda dalla tua app, il che significa che il browser controlla quando i report vengono inviati ai tuoi server.

Il browser tenta di inviare i report in coda nel momento più opportuno. Questo può avvenire non appena sono pronti (per fornire un feedback tempestivo allo sviluppatore), ma il browser può anche ritardare l'invio se è impegnato a elaborare un lavoro con priorità più alta o se l'utente si trova su una rete lenta e/o congestionata in quel momento. Il browser potrebbe anche dare la priorità all'invio di report su una determinata origine, se l'utente è un visitatore frequente.

L'utilizzo dell'API Reporting non comporta quasi nessun problema di prestazioni (ad es. conflitti di rete con l'app). Inoltre, non è possibile controllare quando il browser invia i report in coda.

Configurazione di più endpoint

Una singola risposta può configurare più endpoint contemporaneamente inviando più intestazioni 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"
             }]
           }

oppure combinandoli in un'unica intestazione 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"
             }]
           }

Dopo aver inviato l'intestazione Report-To, il browser memorizza nella cache gli endpoint in base ai relativi valori max_age e invia tutti gli avvisi/errori della console ai tuoi URL.

Failover e bilanciamento del carico

Nella maggior parte dei casi, configurerai un raccoglitore di URL per gruppo. Tuttavia, poiché i report possono generare una notevole quantità di traffico, la specifica include funzionalità di failover e bilanciamento del carico ispirate al record SRV del DNS.

Il browser farà del suo meglio per inviare un report a un massimo di un endpoint in un gruppo. Agli endpoint può essere assegnato un weight per distribuire il carico, con ogni endpoint che riceve una frazione specificata del traffico dei report. Agli endpoint può anche essere assegnata una priority per configurare i raccoglitori di riserva.

I raccoglitori di riserva vengono provati solo quando i caricamenti sui raccoglitori principali non vanno a buon fine.

Esempio: crea un raccoglitore di riserva in 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}
             ]
           }

Configurazione di Network Error Logging

Configurazione

Per utilizzare NEL, configura l'intestazione Report-To con un raccoglitore che utilizza un gruppo denominato:

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

Invia quindi l'intestazione della risposta NEL per iniziare a raccogliere gli errori. Poiché NEL è un'attivazione per un'origine, devi inviare l'intestazione una sola volta. Sia NEL che Report-To verranno applicati alle richieste future alla stessa origine e continueranno a raccogliere errori in base al valore max_age utilizzato per configurare l'agente di raccolta.

Il valore dell'intestazione deve essere un oggetto JSON contenente un campo max_age e un campo report_to. Utilizza quest'ultimo per fare riferimento al nome del gruppo del raccoglitore di errori di rete:

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

Risorse secondarie

Esempio: se example.com carica foobar.com/cat.gif e il caricamento della risorsa non va a buon fine:

  • Il raccoglitore NEL di foobar.com riceve una notifica
  • Il raccoglitore NEL di example.com non riceve notifiche

La regola generale è che NEL riproduce i log lato server, appena generati sul client.

Poiché example.com non ha visibilità sui log del server di foobar.com, non ha visibilità neanche sui report NEL.

Configurazioni dei report di debug

Se non vedi i report sul tuo server, vai alla pagina chrome://net-export/. Questa pagina è utile per verificare che la configurazione sia corretta e che i report vengano inviati correttamente.

E ReportingObserver?

ReportingObserver è un meccanismo di segnalazione correlato, ma diverso. Si basa su chiamate JavaScript. Non è adatto per il logging degli errori di rete, poiché questi errori non possono essere intercettati tramite JavaScript.

Server di esempio

Di seguito è riportato un esempio di server Node che utilizza Express. Mostra come configurare i report per gli errori di rete e crea un gestore dedicato per acquisire il risultato.

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

Per approfondire