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