Registrazione degli errori di rete (NEL)

Eric Bidelman

Maud Nalpas

Introduzione

Network Error Logging (NEL) è un meccanismo per raccogliere 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 e poi si integra con l'API di reporting per segnalare gli errori a un server.

Attenzione : per configurare il logging degli errori di rete per il tuo sito, devi utilizzare l'API di reporting precedente che si basa sull'intestazione Report-To. Questo perché la nuova API di reporting, che si basa sull'intestazione Reporting-Endpoints, non supporta il logging degli errori di rete. Scopri di più in Supporto dei browser. In futuro, verrà invece sviluppato un nuovo meccanismo per il logging degli errori di rete. Una volta disponibile, passa dall'API di reporting precedente al nuovo meccanismo.

Panoramica della versione precedente dell'API di reporting

Intestazione Report-To precedente

Per utilizzare la versione precedente dell'API di reporting, devi impostare un'intestazione della risposta HTTP Report-To. Il suo valore è un oggetto che descrive un gruppo di endpoint per cui il browser segnala errori a:

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

Se l'URL dell'endpoint si trova su un'origine diversa dal tuo sito, l'endpoint dovrebbe 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 per segnalare 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 prendere in considerazione i sottodomini quando segnali errori utilizzando il campo include_subdomains.

Campo	Tipo	Descrizione
group	stringa	Campo 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. Se il valore è "0", il gruppo di endpoint viene rimosso dalla cache dei report dello user agent.
endpoints	Array<oggetto>	Obbligatorio. Un array di oggetti JSON che specifica l'URL effettivo del raccoglitore di report.
include_subdomains	boolean	Campo facoltativo. Un valore booleano che attiva il gruppo di endpoint per tutti i sottodomini dell'host dell'origine attuale. Se il valore è 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. Usa questo nome in altre posizioni 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 tuo backend dovrà inoltrarli.

In che modo il browser invia i report?

Il browser raggruppa periodicamente i report e li invia agli endpoint di reporting da te 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 forniti fuori banda dalla tua app, il che significa che il browser controlla quando i report vengono inviati ai tuoi server.

Il browser tenta di consegnare report in coda al momento più opportuno. Potrebbe avvenire non appena sono pronti (per fornire un feedback tempestivo allo sviluppatore), ma il browser può anche ritardare la pubblicazione se è occupato a elaborare lavori con priorità più elevata o se in quel momento l'utente si trova su una rete lenta e/o congestionata. Il browser può anche dare priorità all'invio dei report su una determinata origine, se l'utente è un visitatore frequente.

Quando utilizzi l'API di reporting, i problemi di rendimento sono minimi o nulli (ad es. contesa di rete con la tua app). Inoltre, non c'è modo di controllare quando il browser invia 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 combinandole 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 che hai inviato l'intestazione Report-To, il browser memorizza nella cache gli endpoint in base ai relativi valori max_age e invia tutti questi avvisi/errori della console ai tuoi URL.

Failover e bilanciamento del carico

La maggior parte delle volte configuri un raccoglitore URL per gruppo. Tuttavia, poiché i report possono generare una buona quantità di traffico, la specifica include funzionalità di failover e bilanciamento del carico ispirate al record SRV DNS.

Il browser farà del proprio meglio per inviare un report al massimo endpoint in un gruppo. È possibile assegnare un weight agli endpoint per distribuire il carico, con ogni endpoint che riceve una determinata frazione del traffico di reporting. Puoi anche assegnare un priority agli endpoint 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 del logging degli errori di rete

Imposta

Per utilizzare NEL, imposta 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"
    }]
  }

Dopodiché, invia l'intestazione della risposta NEL per iniziare a raccogliere gli errori. Poiché NEL è un'autorizzazione per un'origine, è sufficiente inviare l'intestazione una sola volta. Sia NEL che Report-To si applicano alle richieste future alla stessa origine e continueranno a raccogliere errori in base al valore max_age utilizzato per configurare il raccoglitore.

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 degli errori di rete:

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

Attenzione: l'intestazione Report-To utilizza un trattino. In questo caso, report_to utilizza un trattino basso.

Risorse secondarie

Punto chiave: NEL funziona tra navigazioni e recuperi delle risorse secondarie. Per le risorse secondarie, invece, la pagina contenitore non ha visibilità nei report NEL sulle richieste multiorigine che effettua.

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

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

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

Dal momento che example.com non ha visibilità nei log del server di foobar.com, non ha visibilità nemmeno nei suoi 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 gli elementi siano configurati correttamente e i report vengano inviati correttamente.

E quando si utilizza ReportingObserver?

ReportingObserver è un meccanismo di segnalazione correlato, ma diverso. Si basa sulle chiamate JavaScript. Non è adatto per il logging degli errori di rete, poiché gli errori di rete 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

• Monitorare l'applicazione web con l'API di reporting (post principale sull'API di reporting)
• Guida alla migrazione dall'API di reporting da v0 a v1
• Specifica: API di reporting precedente (v0)
• Specifica: nuova API di reporting (v1)