Registro de errores de red (NEL)

Eric Bidelman

Maud Nalpas

Introducción

El registro de errores de red (NEL) es un mecanismo para recopilar errores de red del cliente desde un origen.

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

Precaución: Para configurar el registro de errores de red en 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 admite 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, cambia de la API de Reporting heredada a ese nuevo mecanismo.

Descripción general de la API de informes heredada

El encabezado Report-To heredado

Para usar la API de informes heredada, deberás establecer un encabezado de respuesta HTTP Report-To. Su valor es un objeto que describe un grupo de extremos al que el navegador debe informar los errores:

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

Si la URL del extremo se encuentra en un origen diferente al de tu sitio, el extremo debe admitir solicitudes de comprobación previa 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, enviar este encabezado de respuesta con la página principal configura el navegador para que informe las advertencias generadas por el navegador al extremo https://analytics.provider.com/browser-errors durante max_age segundos. Es importante tener en cuenta que se ignoran todas las solicitudes HTTP posteriores que realiza la página (para imágenes, secuencias de comandos, etcétera). 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 group, max_age y un array endpoints. También puedes elegir si deseas tener en cuenta los subdominios cuando informes errores con el campo include_subdomains.

Campo	Tipo	Descripción
group	string	Opcional. Si no se especifica un nombre de 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 endpoints se quite de la caché de informes del agente de usuario.
endpoints	Arreglo<Object>	Obligatorio. Es un array de objetos JSON que especifican la URL real de tu recopilador de informes.
include_subdomains	booleano	Opcional. Es un valor booleano que habilita el grupo de extremos para todos los subdominios del host del origen actual. Si se omite o se establece en cualquier valor que no sea "true", los subdominios no se informan al endpoint.

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 Informes para hacer referencia a un grupo de extremos específico.

El campo max-age también es obligatorio y especifica cuánto tiempo debe usar el navegador el extremo y notificarle los errores.

El campo endpoints es un array que proporciona funciones de conmutación por error y balanceo de cargas. Consulta la sección sobre Conmutación por error y balanceo de cargas. 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 informe a varios servidores a la vez, tu backend deberá reenviar los informes.

¿Cómo envía informes el navegador?

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

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

¿Cuándo envía informes el navegador?

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

El navegador intenta entregar los informes en cola en el momento más oportuno. Esto puede ocurrir tan pronto como estén listos (para proporcionar comentarios oportunos al desarrollador), pero el navegador también puede retrasar la entrega si está ocupado procesando trabajo de mayor prioridad o si el usuario se encuentra en una red lenta o congestionada en ese momento. El navegador también puede priorizar el envío de informes sobre un origen en particular primero, si el usuario es un visitante frecuente.

Cuando se usa la API de Reporting, no hay problemas de rendimiento (por ejemplo, contención de red con tu app). Tampoco hay forma de controlar cuándo el navegador envía los informes en cola.

Configura varios extremos

Una sola respuesta puede configurar varios extremos 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ías el encabezado Report-To, el navegador almacena en caché los extremos según sus valores de max_age y envía todas esas advertencias o errores desagradables de la consola a tus URLs.

Conmutación por error y balanceo de cargas

La mayoría de las veces, configurarás un recopilador de URLs por grupo. Sin embargo, dado que los informes pueden generar una gran cantidad de tráfico, la especificación incluye funciones de conmutación por error y balanceo de cargas inspiradas en el registro SRV de DNS.

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 un weight para distribuir la carga, y cada extremo recibe una fracción especificada del tráfico de informes. También se les puede asignar un priority para configurar recopiladores de resguardo.

Los recopiladores de respaldo solo se intentan 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 un recopilador que use 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. Dado que NEL se habilita para un origen, solo debes enviar el encabezado una vez. Tanto NEL como Report-To se aplicarán a las solicitudes futuras al mismo origen y seguirán recopilando errores según el valor de max_age que se usó para configurar el recopilador.

El valor del encabezado debe ser un objeto JSON que contenga los campos max_age y report_to. Usa la ú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 todas las navegaciones y recuperaciones de subrecursos. Sin embargo, en el caso de los recursos secundarios, 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 no se carga, sucede lo siguiente:

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

La regla general es que NEL reproduce los registros del servidor, solo que se generan en el cliente.

Como example.com no tiene visibilidad de los registros del servidor de foobar.com, tampoco tiene visibilidad de sus informes de NEL.

Depuración de la configuración de informes

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

¿Qué sucede con ReportingObserver?

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

Servidor de ejemplo

A continuación, se muestra un ejemplo de un servidor de Node que usa Express. Muestra cómo configurar los informes de errores de red y 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 versión 0 a la versión 1 de la API de Reporting
• Especificación: API de Reporting heredada (v0)
• Especificación: Nueva API de Reporting (v1)