Logging Error Jaringan (NEL)

Maud Nalpas

Pengantar

Pencatatan Error Jaringan (NEL) adalah mekanisme untuk mengumpulkan error jaringan sisi klien dari asal.

Library ini menggunakan header respons HTTP NEL untuk memberi tahu browser agar mengumpulkan error jaringan, lalu berintegrasi dengan Reporting API untuk melaporkan error ke server.

Ringkasan Reporting API lama

Untuk menggunakan Reporting API lama, Anda harus menyetel header respons HTTP Report-To. Nilainya adalah objek yang menjelaskan grup endpoint untuk browser yang akan melaporkan error:

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

Jika URL endpoint Anda berada di origin yang berbeda dengan situs Anda, endpoint harus mendukung permintaan pra-penerbangan CORS. (misalnya, 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).

Dalam contoh ini, mengirim header respons ini dengan halaman utama Anda akan mengonfigurasi browser untuk melaporkan peringatan yang dihasilkan browser ke endpoint https://analytics.provider.com/browser-errors selama max_age detik. Perlu diperhatikan bahwa semua permintaan HTTP berikutnya yang dilakukan oleh halaman (untuk gambar, skrip, dll.) akan diabaikan. Konfigurasi disiapkan selama respons halaman utama.

Penjelasan kolom header

Setiap konfigurasi endpoint berisi nama group, max_age, dan array endpoints. Anda juga dapat memilih apakah akan mempertimbangkan subdomain saat melaporkan error dengan menggunakan kolom include_subdomains.

Kolom Jenis Deskripsi
group string Opsional. Jika nama group tidak ditentukan, endpoint akan diberi nama "default".
max_age angka Wajib diisi. Bilangan bulat non-negatif yang menentukan masa aktif endpoint dalam detik. Nilai "0" akan menyebabkan grup endpoint dihapus dari cache pelaporan agen pengguna.
endpoints Array<Object> Wajib diisi. Array objek JSON yang menentukan URL sebenarnya dari pengumpul laporan Anda.
include_subdomains boolean Opsional. Boolean yang mengaktifkan grup endpoint untuk semua subdomain host asal saat ini. Jika dihilangkan atau nilai selain "true", subdomain tidak akan dilaporkan ke endpoint.

Nama group adalah nama unik yang digunakan untuk mengaitkan string dengan endpoint. Gunakan nama ini di tempat lain yang terintegrasi dengan Reporting API untuk merujuk ke grup endpoint tertentu.

Kolom max-age juga diperlukan dan menentukan berapa lama browser harus menggunakan endpoint dan melaporkan error ke endpoint tersebut.

Kolom endpoints adalah array untuk menyediakan fitur failover dan load balancing. Lihat bagian Failover dan load balancing. Penting untuk diperhatikan bahwa browser hanya akan memilih satu endpoint, meskipun grup mencantumkan beberapa pengumpul di endpoints. Jika Anda ingin mengirim laporan ke beberapa server sekaligus, backend Anda harus meneruskan laporan.

Bagaimana cara browser mengirim laporan?

Browser secara berkala mengelompokkan laporan dan mengirimkannya ke endpoint pelaporan yang Anda konfigurasi.

Untuk mengirim laporan, browser akan menerbitkan permintaan POST dengan Content-Type: application/reports+json dan isi yang berisi array peringatan/error yang terekam.

Kapan browser mengirim laporan?

Laporan dikirimkan di luar jalur dari aplikasi Anda, yang berarti browser mengontrol kapan laporan dikirim ke server Anda.

Browser akan mencoba mengirimkan laporan yang diantrekan pada waktu yang paling tepat. Hal ini dapat dilakukan segera setelah pengguna siap (untuk memberikan masukan tepat waktu kepada developer), tetapi browser juga dapat menunda pengiriman jika sedang memproses pekerjaan dengan prioritas lebih tinggi, atau jika pengguna sedang menggunakan jaringan yang lambat dan/atau padat pada saat itu. Browser juga dapat memprioritaskan pengiriman laporan tentang asal tertentu terlebih dahulu, jika pengguna sering berkunjung.

Hampir tidak ada masalah performa (misalnya, persaingan jaringan dengan aplikasi Anda) saat menggunakan Reporting API. Tidak ada cara untuk mengontrol kapan browser mengirim laporan yang diantrekan.

Mengonfigurasi beberapa endpoint

Satu respons dapat mengonfigurasi beberapa endpoint sekaligus dengan mengirim beberapa header 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"
             }]
           }

atau dengan menggabungkannya ke dalam satu header 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"
             }]
           }

Setelah Anda mengirim header Report-To, browser akan meng-cache endpoint sesuai dengan nilai max_age-nya, dan mengirim semua peringatan/error konsol yang tidak menyenangkan tersebut ke URL Anda.

Failover dan load balancing

Biasanya, Anda akan mengonfigurasi satu pengumpul URL per grup. Namun, karena pelaporan dapat menghasilkan banyak traffic, spesifikasi ini mencakup fitur failover dan penyeimbangan beban yang terinspirasi oleh SRV record DNS.

Browser akan berupaya sebaik mungkin untuk mengirimkan laporan ke paling banyak satu endpoint dalam grup. Endpoint dapat diberi weight untuk mendistribusikan beban, dengan setiap endpoint menerima sebagian kecil traffic pelaporan yang ditentukan. Endpoint juga dapat diberi priority untuk menyiapkan pengumpul penggantian.

Kolektor pengganti hanya dicoba saat upload ke kolektor utama gagal.

Contoh: Buat pengumpul penggantian di 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}
             ]
           }

Menyiapkan Network Error Logging

Penyiapan

Untuk menggunakan NEL, siapkan header Report-To dengan pengumpul yang menggunakan grup bernama:

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

Selanjutnya, kirim header respons NEL untuk mulai mengumpulkan error. Karena NEL adalah keikutsertaan untuk origin, Anda hanya perlu mengirim header satu kali. NEL dan Report-To akan berlaku untuk permintaan mendatang ke origin yang sama dan akan terus mengumpulkan error sesuai dengan nilai max_age yang digunakan untuk menyiapkan pengumpul.

Nilai header harus berupa objek JSON yang berisi kolom max_age dan report_to. Gunakan yang terakhir untuk mereferensikan nama grup pengumpul error jaringan Anda:

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

Subresource

Contoh: Jika example.com memuat foobar.com/cat.gif dan resource tersebut gagal dimuat:

  • Pengumpul NEL foobar.com akan diberi tahu
  • Pengumpul NEL example.com tidak diberi tahu

Aturan umumnya adalah NEL mereproduksi log sisi server, yang dihasilkan di sisi klien.

Karena example.com tidak memiliki visibilitas ke log server foobar.com, example.com juga tidak memiliki visibilitas ke laporan NEL-nya.

Melakukan debug konfigurasi laporan

Jika Anda tidak melihat laporan muncul di server, buka chrome://net-export/. Halaman tersebut berguna untuk memverifikasi bahwa semuanya dikonfigurasi dengan benar dan laporan dikirim dengan benar.

Bagaimana dengan ReportingObserver?

ReportingObserver adalah mekanisme pelaporan yang terkait, tetapi berbeda. Hal ini didasarkan pada panggilan JavaScript. Tidak cocok untuk mencatat error jaringan, karena error jaringan tidak dapat dicegat melalui JavaScript.

Contoh server

Di bawah ini adalah contoh server Node yang menggunakan Express. Contoh ini menunjukkan cara mengonfigurasi pelaporan untuk error jaringan, dan membuat handler khusus untuk merekam hasilnya.

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

Bacaan lebih lanjut