Registro de errores de red (NEL)

Eric Bidelman

Maud Nalpas

Introducción

Network Error Logging (NEL) es un mecanismo para recopilar errores de red del cliente de un origen

Usa el encabezado de respuesta HTTP NEL para indicarle al navegador que recopile errores de red y, luego, se integra en la API de Reporting para informar los errores a un servidor.

Precaución: Si quieres configurar Network Error Logging para tu sitio, deberás usar la API de Reporting heredada que se basa en el encabezado Report-To. Esto se debe a que la nueva API de Reporting, que se basa en el encabezado Reporting-Endpoints, no es compatible con el registro de errores de red. Obtén más información en Compatibilidad con navegadores. En su lugar, se desarrollará un nuevo mecanismo para el registro de errores de red en el futuro. Una vez que esté disponible, cambie de la API de Reporting heredada a ese mecanismo nuevo.

Descripción general de la API de Reporting heredada

El encabezado Report-To heredado

Para usar la API de Reporting heredada, deberás configurar un encabezado de respuesta HTTP Report-To. Es El valor es un objeto que describe un grupo de extremos para el navegador. para informar errores a:

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

Si su URL de extremo se encuentra en un origen diferente al de su sitio, el de servicio debe admitir solicitudes preliminares de CORS. (p.ej., 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).

En el ejemplo, si envías este encabezado de respuesta con tu página principal configura el navegador para que informe advertencias generadas por él al extremo https://analytics.provider.com/browser-errors durante max_age segundos Es importante tener en cuenta que todas las solicitudes HTTP posteriores que realice la página (para imágenes, secuencias de comandos, etc.). La configuración se establece durante la respuesta de la página principal.

Explicación de los campos de encabezado

Cada configuración de extremo contiene un nombre de group, un max_age y un endpoints . También puedes elegir si quieres tener en cuenta los subdominios al informar con el campo include_subdomains.

Campo	Tipo	Descripción
group	string	Opcional. Si no se especifica un nombre group, el extremo recibe el nombre “default”.
max_age	número	Obligatorio. Es un número entero no negativo que define la vida útil del extremo en segundos. Un valor de "0" hará que el grupo de extremos se quite de la caché de informes del usuario-agente.
endpoints	Arreglo<Objeto>	Obligatorio. Un array de objetos JSON que especifica la URL real de tu recopilador de informes.
include_subdomains	boolean	Opcional. Un valor booleano que habilita el grupo de extremos para todos los subdominios del host de origen actual. Si se omite o no se especifica como "true", los subdominios no se informan al extremo.

El nombre group es un nombre único que se usa para asociar una cadena con un extremo. Usa este nombre en otros lugares que se integren con la API de Reporting para hacer referencia a un grupo de extremos específico.

El campo max-age también es obligatorio y especifica por cuánto tiempo el navegador debe usar el extremo e informar sobre él errores.

El campo endpoints es un array para proporcionar conmutación por error y balanceo de cargas. atributos. Consulta la sección sobre Conmutación por error y balanceo de cargas. Es Es importante tener en cuenta que el navegador seleccionará solo un extremo, incluso si el grupo enumera varios recopiladores en endpoints. Si deseas enviar un a varios servidores a la vez, tu backend deberá reenviar el informes.

¿De qué manera el navegador envía informes?

El navegador agrupa los informes periódicamente y los envía al informe. en los extremos que configuras.

Para enviar informes, el navegador emite un POST. solicitud con Content-Type: application/reports+json y un cuerpo que contiene el array de advertencias/errores que se capturaron.

¿Cuándo envía informes el navegador?

Los informes se entregan fuera de banda desde tu app, es decir, que el navegador controla cuándo se envían los informes a sus servidores.

El navegador intenta entregar los informes en cola en el momento más oportuno. Esto puede ocurrir en cuanto estén listos (para proporcionarte comentarios oportunos al desarrollador), pero el navegador también puede retrasar la entrega si es ocupado procesando un trabajo de mayor prioridad o si el usuario está en un estado red congestionada en ese momento. Es posible que el navegador también priorice informa primero acerca de un origen en particular, si el usuario es un visitante frecuente.

El problema de rendimiento es mínimo o nulo. (p.ej., la contención de la red con tu app) cuando uses la API de Reporting. Hay tampoco hay forma de controlar cuándo el navegador envía informes en cola.

Configura varios extremos

Una sola respuesta puede configurar varios endpoints a la vez enviando varios encabezados 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"
             }]
           }

o combinándolos en un solo encabezado 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"
             }]
           }

Una vez que envíes el encabezado Report-To, el navegador almacenará en caché los extremos de acuerdo con sus valores de max_age, y envía todas esas desagradables consolas advertencias/errores a sus URL.

Conmutación por error y balanceo de cargas

La mayoría de las veces, configurarás un recopilador de URL por grupo. Sin embargo, dado que los informes pueden generar mucho tráfico, la especificación incluye de balanceo de cargas y de balanceo de cargas inspiradas en el Registro SRV.

El navegador hará todo lo posible para entregar un informe a como máximo un extremo. en un grupo. A los extremos se les puede asignar una weight para distribuir la carga, con cada que recibe una fracción específica del tráfico de informes. Los extremos pueden también se les asignará un priority para configurar recopiladores de resguardo.

Los recopiladores de resguardo solo se prueban cuando fallan las cargas a los recopiladores principales.

Ejemplo: Crea un recopilador de resguardo en 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}
             ]
           }

Configura el registro de errores de red

Configuración

Para usar NEL, configura el encabezado Report-To con una recopilador que usa un grupo con nombre:

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

A continuación, envía el encabezado de respuesta NEL para comenzar a recopilar errores. Desde NEL es habilitar un origen, solo tienes que enviar el encabezado una vez. Tanto NEL como Report-To se aplicará a las solicitudes futuras del mismo origen y continuará para recopilar errores según el valor max_age que se usó para la configuración el recopilador.

El valor del encabezado debe ser un objeto JSON que contenga un max_age y report_to. Usa esta última para hacer referencia al nombre del grupo de tu Recopilador de errores de red:

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

Precaución: El encabezado Report-To usa un guion. Aquí, report_to usa un guion bajo.

Subrecursos

Punto clave: NEL funciona en navegaciones y recuperaciones de subrecursos. Sin embargo, para los subrecursos, la página contenedora no tiene visibilidad de los informes de NEL sobre las solicitudes de origen cruzado que realiza.

Ejemplo: Si example.com carga foobar.com/cat.gif y ese recurso falla, para cargar:

• Se notifica al recopilador de NEL de foobar.com
• No se notifica al recopilador de NEL de example.com.

El regla general es que NEL reproduce los registros del servidor, recién generados en al cliente.

Como example.com no puede ver el servidor de foobar.com de datos, tampoco tiene visibilidad de sus informes de NEL.

Depura la configuración de los informes

Si no ves informes en tu servidor, ve a chrome://net-export/ Esa página es útil para verificando que todo esté configurado correctamente y que se envíen los informes correctamente.

¿Qué sucede con ReportingObserver?

ReportingObserver es un mecanismo de generación de informes relacionado, pero diferente. Se basa en llamadas de JavaScript. No es adecuado para el registro de errores de red, ya que estos errores y no se pueden interceptar a través de JavaScript.

Servidor de ejemplo

A continuación, se muestra un ejemplo de un servidor de nodos que usa Express. Aquí se muestra cómo configurar los informes de errores de red y se crea un controlador dedicado para capturar el 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}`);
});

Lecturas adicionales

• Supervisa tu aplicación web con la API de Reporting (publicación principal sobre la API de Reporting)
• Guía de migración de la API de Reporting v0 a v1
• Especificación: API de Reporting heredada (v0)
• Especificación: nueva API de Reporting (v1)