Logging Error Jaringan (NEL)

Eric Bidelman

Maud Nalpas

Pengantar

Logging Error Jaringan (NEL) adalah mekanisme untuk mengumpulkan error jaringan sisi klien dari origin.

Fungsi 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

Header Report-To lama

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

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

Jika URL endpoint Anda berada di origin yang berbeda dengan situs, endpoint harus mendukung permintaan preflight 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, 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. Penting untuk diperhatikan bahwa semua permintaan HTTP berikutnya yang dibuat oleh halaman (untuk gambar, skrip, dll.) akan diabaikan. Konfigurasi disiapkan selama respons halaman utama.

Penjelasan kolom header

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

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 wajib ada dan menentukan durasi browser harus menggunakan endpoint dan melaporkan error ke endpoint.

Kolom endpoints adalah array untuk memberikan fitur failover dan load balancing. Lihat bagian Failover dan load balancing. Penting untuk diperhatikan bahwa browser hanya akan memilih satu endpoint, meskipun grup tersebut mencantumkan beberapa kolektor 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 mengeluarkan permintaan POST dengan Content-Type: application/reports+json dan isi yang berisi array peringatan/error yang ditangkap.

Kapan browser mengirim laporan?

Laporan dikirimkan secara out-of-band dari aplikasi Anda, yang berarti browser mengontrol kapan laporan dikirim ke server Anda.

Browser akan mencoba mengirimkan laporan dalam antrean pada waktu yang paling tepat. Waktu pengiriman harus segera siap (untuk memberikan masukan secara tepat waktu kepada developer), tetapi browser juga dapat menunda pengiriman jika sedang sibuk memproses pekerjaan dengan prioritas yang lebih tinggi, atau jika pengguna berada di jaringan yang lambat dan/atau padat pada saat itu. Browser juga dapat memprioritaskan pengiriman laporan tentang origin tertentu terlebih dahulu, jika pengguna adalah pengunjung rutin.

Anda tidak perlu terlalu memperhatikan performa (misalnya, pertentangan jaringan dengan aplikasi Anda) saat menggunakan Reporting API. Selain itu, tidak ada cara untuk mengontrol kapan browser mengirim laporan dalam antrean.

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 mengirimkan semua peringatan/error konsol yang buruk tersebut ke URL Anda.

Failover dan load balancing

Biasanya, Anda akan mengonfigurasi satu pengumpul URL per grup. Namun, karena pelaporan dapat menghasilkan banyak traffic, spesifikasinya mencakup fitur failover dan load balancing yang terinspirasi oleh data SRV DNS.

Browser akan berupaya sebaik mungkin untuk mengirimkan laporan ke maksimum satu endpoint dalam satu grup. Endpoint dapat diberi weight untuk mendistribusikan beban, dengan setiap endpoint menerima bagian tertentu dari traffic pelaporan. Endpoint juga dapat diberi priority untuk menyiapkan kolektor penggantian.

Pengumpul penggantian hanya dicoba saat upload ke kolektor utama gagal.

Contoh: Buat kolektor 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 Pencatatan Log Error Jaringan

Penyiapan

Untuk menggunakan NEL, siapkan header Report-To dengan kolektor 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 ikut serta untuk origin, Anda hanya perlu mengirim header satu kali. NEL dan Report-To akan berlaku untuk permintaan mendatang ke asal yang sama dan akan terus mengumpulkan error sesuai dengan nilai max_age yang digunakan untuk menyiapkan kolektor.

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

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

Sub-resource

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

• Kolektor NEL foobar.com diberi tahu
• Kolektor NEL example.com tidak diberi tahu

Aturan praktisnya adalah NEL mereproduksi log sisi server, yang baru saja dihasilkan pada klien.

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

Men-debug konfigurasi laporan

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

Bagaimana dengan ReportingObserver?

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

Server contoh

Di bawah ini adalah contoh server Node yang menggunakan Express. Tutorial ini menunjukkan cara mengonfigurasi pelaporan error jaringan, dan membuat pengendali khusus untuk menangkap 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

• Memantau aplikasi web dengan Reporting API (postingan utama di Reporting API)
• Panduan migrasi dari Reporting API v0 ke v1
• Spesifikasi: Reporting API lama (v0)
• Spesifikasi: Reporting API baru (v1)