Introdução
O registro de erros de rede (NEL) é um mecanismo para coletar erros de rede do lado do cliente de uma origem;
Ela usa o cabeçalho de resposta HTTP NEL para informar ao navegador que precisa coletar erros de rede e, em seguida, se integra à API Reporting para informar os erros a um servidor.
Visão geral da API Reporting legada
O cabeçalho Report-To legado
Para usar a API Reporting legada, você precisará definir um cabeçalho de resposta HTTP Report-To. Seu
value é um objeto que descreve um grupo de endpoints para o navegador
para relatar erros:
Report-To:
{
"max_age": 10886400,
"endpoints": [{
"url": "https://analytics.provider.com/browser-errors"
}]
}
Se o URL de ponto final estiver em uma origem diferente do seu site, o
deve suportar solicitações de simulação do CORS. (por exemplo, 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).
No exemplo, enviar esse cabeçalho de resposta com a página principal
configura o navegador para relatar avisos gerados pelo navegador.
ao endpoint https://analytics.provider.com/browser-errors por max_age segundos.
É importante observar que todas as solicitações HTTP subsequentes feitas pela página
(para imagens, scripts etc.) são ignorados. A configuração é definida durante
a resposta da página principal.
Explicação dos campos de cabeçalho
Cada configuração de endpoint contém um nome de group, max_age e endpoints
matriz. Você também pode escolher se quer considerar subdomínios ao gerar relatórios
usando o campo include_subdomains.
| Campo | Tipo | Descrição |
|---|---|---|
group |
string | Opcional. Se um nome group não for especificado, o endpoint receberá o nome "padrão". |
max_age |
number | Obrigatório. Um número inteiro não negativo que define o ciclo de vida do endpoint em segundos. Um valor de "0" fará com que o grupo de endpoints seja removido do cache de relatórios do user agent. |
endpoints |
Matriz<Objeto> | Obrigatório. Uma matriz de objetos JSON que especificam o URL real do seu coletor de relatórios. |
include_subdomains |
booleano | Opcional. Um booleano que ativa o grupo de endpoints para todos os subdomínios do host da origem atual. Se omitido ou algo diferente de "true", os subdomínios não serão informados ao endpoint. |
O nome group é exclusivo e usado para associar uma string
em um endpoint. Use este nome em outros lugares onde se integre
com a API Reporting para se referir a um grupo de endpoints específico.
O campo max-age também é obrigatório e especifica como
por quanto tempo o navegador deve usar o endpoint e relatar erros a ele.
O campo endpoints é uma matriz para fornecer failover e balanceamento de carga.
atributos de machine learning. Consulte a seção sobre Failover e balanceamento de carga. Está
é importante observar que o navegador selecionará somente um endpoint, mesmo
se o grupo listar vários coletores em endpoints. Se você quiser enviar uma
vários servidores de uma vez, seu back-end precisará encaminhar o
e detecção de ameaças.
Como o navegador envia relatórios?
O navegador agrupa os relatórios periodicamente e os envia ao de endpoints que você configurar.
Para enviar relatórios, o navegador emite um POST
com
Content-Type: application/reports+json e um corpo contendo a matriz de
avisos/erros que foram detectados.
Quando o navegador envia relatórios?
Os relatórios são entregues fora de banda pelo app, ou seja, o navegador controla quando os relatórios são enviados aos seus servidores.
O navegador tenta entregar relatórios na fila no momento mais oportuno. Isso pode acontecer assim que eles estiverem prontos (para oferecer feedback oportuno ao desenvolvedor), mas o navegador também pode atrasar a entrega caso seja ocupado processando trabalhos de prioridade mais alta, ou se o usuário estiver em um ritmo lento e/ou congestionada no momento. O navegador também pode priorizar o envio relatórios sobre uma origem específica primeiro, se o usuário for um visitante frequente.
Há pouca ou nenhuma preocupação com o desempenho (por exemplo, contenção de rede com seu app) ao usar a API Reporting. Há também não é possível controlar quando o navegador envia relatórios na fila.
Como configurar vários endpoints
Uma única resposta pode configurar vários endpoints de uma só vez ao enviar
vários cabeçalhos 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"
}]
}
ou combinando-as em um único cabeçalho 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"
}]
}
Depois que você envia o cabeçalho Report-To, o navegador armazena os endpoints em cache.
de acordo com os valores de max_age e envia todos os erros
avisos/erros aos URLs.
Failover e balanceamento de carga
Na maioria das vezes, você configurará um coletor de URL por grupo. No entanto, já que os relatórios podem gerar uma boa quantidade de tráfego, a especificação inclui failover e balanceamento de carga inspirados pelo DNS Registro SRV.
O navegador fará o possível para entregar um relatório a no máximo endpoint
em um grupo. É possível atribuir um weight aos endpoints para distribuir a carga,
o endpoint que recebe uma fração especificada do tráfego de relatórios. Os endpoints podem
também podem receber um priority para configurar coletores substitutos.
Os coletores substitutos só são testados quando há falha nos uploads dos coletores principais.
Exemplo: crie um coletor substituto em 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}
]
}
Como configurar o registro de erros de rede
Configuração
Para usar a NEL, configure o cabeçalho Report-To com uma
coletor que usa um grupo nomeado:
Report-To: {
...
}, {
"group": "network-errors",
"max_age": 2592000,
"endpoints": [{
"url": "https://analytics.provider.com/networkerrors"
}]
}
Em seguida, envie o cabeçalho de resposta NEL para começar a coletar erros. Desde a NEL
for ativar uma origem, você só precisa enviar o cabeçalho uma vez. Tanto NEL quanto
Report-To será aplicado a solicitações futuras para a mesma origem e continuará
para coletar erros de acordo com o valor max_age usado para configurar
o coletor.
O valor do cabeçalho deve ser um objeto JSON que contenha um max_age e
report_to. Use a segunda para se referir ao nome do grupo de
coletor de erros de rede:
GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}
Sub-recursos
Exemplo: se example.com carregar foobar.com/cat.gif e esse recurso falhar
para carregar:
- O coletor de NEL de
foobar.comfoi notificado - O coletor de NEL de
example.comnão foi notificado.
A a regra prática é que a NEL reproduz registros do lado do servidor, recém-gerados o cliente.
Como example.com não tem visibilidade do servidor de foobar.com
ele também não tem visibilidade dos relatórios de NEL.
Configurações do relatório de depuração
Se você não encontrar relatórios no seu servidor, acesse
chrome://net-export/: Essa página é útil para
verificando se as configurações estão corretas e se os relatórios estão sendo enviados
corretamente.
E o ReportingObserver?
O ReportingObserver é um mecanismo de denúncias relacionado, mas diferente. Ele é baseado em chamadas JavaScript.
Não é adequado para a geração de registros de erros de rede, já que erros de rede
não pode ser interceptado via JavaScript.
Exemplo de servidor
Veja abaixo um exemplo de servidor de nó que usa o Express. Ele mostra como configurar a geração de relatórios para erros de rede e cria um manipulador dedicado para capturar o resultado.
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}`);
});
Leitura adicional
- Monitorar seu aplicativo da Web com a API Reporting (postagem principal sobre a API Reporting)
- Guia de migração da API Reporting v0 para v1
- Especificação: API Reporting legada (v0)
- Especificação: nova API Reporting (v1)