Logging Error Jaringan (NEL)

Eric Bidelman

Maud Nalpas

Pengantar

{i>Network Error Logging<i} (NEL) adalah mekanisme untuk mengumpulkan error jaringan sisi klien dari origin.

Alat 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 yang lama, Anda harus menetapkan header respons HTTP Report-To. Ini nilai adalah objek yang mendeskripsikan grup endpoint untuk browser untuk melaporkan error ke:

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

Jika URL endpoint berada di origin yang berbeda dengan situs Anda, endpoint akan 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).

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

Penjelasan kolom header

Setiap konfigurasi endpoint berisi nama group, max_age, dan endpoints . Anda juga dapat memilih apakah akan mempertimbangkan subdomain saat melaporkan error dengan 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 cara lama browser harus menggunakan endpoint dan melaporkan error padanya.

Kolom endpoints adalah array untuk memberikan failover dan load balancing baru. Lihat bagian Failover dan load balancing. Penting perlu diperhatikan bahwa browser hanya akan memilih satu endpoint, bahkan jika grup mencantumkan beberapa kolektor di endpoints. Jika Anda ingin mengirim melaporkan ke beberapa server sekaligus, bagian {i>backend<i} Anda harus meneruskan laporan.

Bagaimana cara browser mengirim laporan?

Browser secara berkala mengelompokkan laporan dan mengirimkannya ke pelaporan yang dikonfigurasi oleh Anda.

Untuk mengirim laporan, browser mengeluarkan POST minta dengan Content-Type: application/reports+json dan isi yang berisi array peringatan/error yang terdeteksi.

Kapan browser mengirim laporan?

Laporan dikirim secara out-of-band dari aplikasi Anda, artinya browser mengontrol waktu laporan dikirim ke server Anda.

Browser mencoba untuk mengirimkan laporan dalam antrean pada waktu yang paling tepat. Ini mungkin segera setelah mereka siap (untuk memberikan masukan aktual kepada developer), tetapi browser juga dapat menunda penayangan jika sibuk memroses pekerjaan prioritas yang lebih tinggi, atau jika pengguna lambat dan/atau jaringan yang pada saat itu. Browser juga dapat memprioritaskan pengiriman melaporkan tentang asal tertentu terlebih dahulu, jika pengguna sering berkunjung.

Hanya ada sedikit atau tidak ada masalah kinerja (misalnya pertentangan jaringan dengan aplikasi Anda) saat menggunakan Reporting API. Ada juga 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 menjadi satu {i>header<i} 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 menurut nilai max_age-nya, dan mengirim semua konsol peringatan/error pada URL Anda.

Failover dan load balancing

Sering kali Anda akan mengonfigurasi satu kolektor URL per grup. Namun, karena pelaporan dapat menghasilkan traffic yang baik, spesifikasi menyertakan failover dan load balancing yang terinspirasi dari DNS Data SRV.

Browser akan berupaya mengirimkan laporan ke maksimal satu endpoint dalam grup. Endpoint dapat diberi weight untuk mendistribusikan beban, dengan masing-masing endpoint yang menerima bagian traffic pelaporan yang ditentukan. Endpoint dapat juga akan diberi priority untuk menyiapkan kolektor penggantian.

Kolektor 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 Logging 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. Sejak NEL adalah keikutsertaan untuk origin, Anda hanya perlu mengirim header satu kali. NEL dan Report-To akan diterapkan ke permintaan mendatang ke asal yang sama dan akan dilanjutkan untuk mengumpulkan error sesuai dengan nilai max_age yang digunakan untuk menyiapkan kolektor.

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

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 untuk memuat:

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

Tujuan praktisnya adalah NEL mereproduksi log sisi server, yang baru saja klien.

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

Melakukan proses debug pada konfigurasi laporan

Jika Anda tidak melihat laporan muncul di server, buka chrome://net-export/. Halaman tersebut berguna untuk memverifikasi bahwa segala sesuatunya 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 logging error jaringan, karena error jaringan tidak dapat disadap melalui JavaScript.

Server contoh

Di bawah ini adalah contoh server Node yang menggunakan Express. Panduan ini menunjukkan cara mengonfigurasi pelaporan error jaringan, dan membuat pengendali khusus untuk mencatat 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 Anda dengan Reporting API (postingan utama di Reporting API)
• Panduan migrasi dari Reporting API v0 ke v1
• Spesifikasi: Reporting API (v0) lama
• Spesifikasi: Reporting API (v1) baru