Registrazione degli errori di rete (NEL)

Maud Nalpas
Maud Nalpas
X GitHub

Introduzione

Network Error Logging (NEL) è un meccanismo per raccogliendo 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.

Panoramica della versione precedente dell'API di reporting

Per utilizzare la versione precedente dell'API di reporting, devi impostare un'intestazione della risposta HTTP Report-To. È value è un oggetto che descrive un gruppo di endpoint per il browser per segnalare 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, 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 nell'endpoint https://analytics.provider.com/browser-errors per max_age secondi. È importante notare che tutte le successive richieste HTTP effettuate dalla pagina (per immagini, script e così via) vengono ignorati. 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 endpoints un array di dati. Puoi anche scegliere se prendere in considerazione i sottodomini quando crei report usando 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. Il valore "0" il gruppo di endpoint viene rimosso dalla cache dei report dello user agent.
endpoints Array<oggetto> Required. Un array di oggetti JSON che specifica l'URL effettivo del raccoglitore di report.
include_subdomains booleano (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. Utilizza questo nome in altre posizioni che integrano con l'API di reporting per fare riferimento a uno specifico gruppo di endpoint.

Anche il campo max-age è obbligatorio e specifica come a lungo il browser deve utilizzare l'endpoint e segnalare gli errori.

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

In che modo il browser invia i report?

Il browser raggruppa periodicamente i report e li invia ai report che configuri per più endpoint.

Per inviare le segnalazioni, il browser emette un POST richiedi 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 dall'app, ovvero il browser controlla quando i report vengono inviati ai tuoi server.

Il browser tenta di inviare report in coda al momento più opportuno. Ad esempio, non appena sono pronti (per fornire feedback tempestivo allo sviluppatore), ma il browser può anche ritardare la consegna se impegnate a elaborare lavori con priorità più elevata o se l'utente è lento e/o congestionata in quel momento. Il browser potrebbe anche dare priorità all'invio report su una particolare origine, se l'utente è un visitatore frequente.

I problemi di rendimento sono minimi o nulli (ad es. contesa della rete con la tua app) quando utilizzi l'API di reporting. C'è inoltre, non c'è modo di controllare quando il browser invia report in coda.

Configurazione di più endpoint

Una singola risposta può configurare diversi 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 gli endpoint nella cache in base ai relativi valori max_age e invia tutti questi malfunzionamenti avvisi/errori agli 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 e di bilanciamento del carico ispirati al DNS Record SRV.

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

Configurazione

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. Da NEL è un'attivazione per un'origine, devi inviare l'intestazione una sola volta. Sia NEL che Report-To si applicherà alle richieste future alla stessa origine e continuerà per raccogliere errori in base al valore max_age utilizzato per la configurazione il raccoglitore.

Il valore dell'intestazione deve essere un oggetto JSON contenente un parametro max_age e report_to. Utilizza quest'ultimo per fare riferimento al nome del gruppo raccoglitore degli 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 la risorsa non funziona per caricare:

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

La è che NEL riproduce i log lato server, appena generati il cliente.

Poiché example.com non ha visibilità sul server di foobar.com log, inoltre non ha visibilità nei suoi rapporti 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