Registrazione degli errori di rete (NEL)

Maud Nalpas

Introduzione

La registrazione degli errori di rete (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 di reporting per segnalare gli errori a un server.

Panoramica dell'API di reporting legacy

Per utilizzare l'API di reporting legacy, 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 da quella del tuo sito, l'endpoint deve supportare le richieste di 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 eseguita durante la risposta della pagina principale.

Spiegazione dei campi dell'intestazione

Ogni configurazione dell'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 Obbligatorio. Un numero intero non negativo che definisce la durata dell'endpoint in secondi. Un valore "0" fa sì che il gruppo di endpoint venga rimosso dalla cache di reporting dello user agent.
endpoints Array<Object> Obbligatorio. Un array di oggetti JSON che specificano l'URL effettivo del raccoglitore di report.
include_subdomains booleano Facoltativo. Un valore booleano che abilita il gruppo di endpoint per tutti i sottodomini dell'host dell'origine corrente. Se omesso o 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 altri punti che si integrano con l'API di 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 il gruppo elenca diversi raccoglitori in endpoints. Se vuoi inviare un report a più server contemporaneamente, il backend dovrà inoltrarlo.

In che modo il browser invia i report?

Il browser raggruppa periodicamente i report e li invia agli endpoint di reporting che hai configurato.

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 nell'elaborazione di attività con priorità più alta o se l'utente si trova su una rete lenta e/o congestionata. Il browser può anche dare la priorità all'invio dei report relativi a un'origine specifica, se l'utente è un visitatore frequente.

L'utilizzo dell'API Reporting non comporta problemi di prestazioni (ad es. contesa di rete con la tua 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 una singola 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 agli URL.

Failover e bilanciamento del carico

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

Il browser farà del suo meglio per inviare un report a al massimo un endpoint in un gruppo. È possibile assegnare un weight agli endpoint per distribuire il carico, con ogni endpoint che riceve una frazione specificata del traffico di reporting. È anche possibile assegnare una priority agli endpoint per configurare i raccoglitori di fallback.

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

Esempio: crea un agente di raccolta di riserva all'indirizzo 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 della registrazione degli errori di rete

Configurazione

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

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

Poi, invia l'intestazione della risposta NEL per iniziare a raccogliere gli errori. Poiché NEL è un'opzione di attivazione per un'origine, devi inviare l'intestazione una sola volta. Sia NEL sia Report-To si applicheranno alle richieste future alla stessa origine e continueranno a raccogliere gli 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 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}

Sottorisorse

Esempio: se example.com carica foobar.com/cat.gif e la risorsa non viene caricata:

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

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

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

Debug delle configurazioni dei report

Se non vedi i report sul tuo server, vai a chrome://net-export/. Questa pagina è utile per verificare che le configurazioni siano corrette e che i report vengano inviati correttamente.

Che dire di ReportingObserver?

ReportingObserver è un meccanismo di reporting correlato, ma diverso. Si basa su chiamate JavaScript. Non è adatto alla registrazione degli errori di rete, poiché gli errori di rete non possono essere intercettati tramite JavaScript.

Server di esempio

Di seguito è riportato un server Node di esempio che utilizza Express. Mostra come configurare il reporting 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