Pengantar
Logging Error Jaringan (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
. Nilainya
adalah objek yang menjelaskan grup endpoint agar browser
dapat melaporkan error ke:
Report-To:
{
"max_age": 10886400,
"endpoints": [{
"url": "https://analytics.provider.com/browser-errors"
}]
}
Jika URL endpoint berada di asal yang berbeda dengan situs Anda, endpoint tersebut 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 ini, mengirim header respons ini dengan halaman utama Anda akan mengonfigurasi browser untuk melaporkan peringatan yang dibuat 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
.
Kolom | Jenis | Deskripsi |
---|---|---|
group |
string | Opsional. Jika nama group tidak ditentukan, endpoint akan diberi nama "default". |
max_age |
number | 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<Objek> | 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 dari host asal saat ini. Jika dihilangkan atau apa pun 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 wajib ada dan menentukan durasi penggunaan endpoint dan melaporkan error pada browser.
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 tersebut mencantumkan beberapa kolektor di endpoints
. Jika Anda ingin mengirim laporan ke beberapa server sekaligus, backend Anda harus meneruskan laporan tersebut.
Bagaimana cara browser mengirim laporan?
Browser secara berkala mengelompokkan laporan dan mengirimkannya ke endpoint pelaporan yang Anda konfigurasikan.
Untuk mengirim laporan, browser mengeluarkan permintaan POST
dengan
Content-Type: application/reports+json
dan isi yang berisi array
peringatan/error yang direkam.
Kapan browser mengirim laporan?
Laporan dikirim secara out-of-band dari aplikasi Anda, artinya browser mengontrol kapan laporan dikirim ke server Anda.
Browser akan mencoba mengirimkan laporan dalam antrean pada waktu yang paling tepat. Hal ini dapat segera dilakukan setelah pengguna siap (untuk memberikan masukan yang tepat waktu kepada developer), tetapi browser juga dapat menunda penayangan jika sedang sibuk saat 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 untuk mengirim laporan tentang asal tertentu terlebih dahulu, jika pengguna sering berkunjung.
Tidak ada masalah 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 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
sesuai dengan nilai max_age
-nya, dan akan mengirim semua peringatan/error
konsol yang menjengkelkan tersebut ke URL Anda.
Failover dan load balancing
Sering kali Anda akan mengonfigurasi satu kolektor URL per grup. Namun, karena pelaporan dapat menghasilkan banyak traffic yang baik, spesifikasinya mencakup fitur failover dan load balancing yang terinspirasi oleh data SRV DNS.
Browser akan melakukan upaya terbaik untuk mengirimkan laporan ke maksimal satu endpoint dalam grup. Endpoint dapat ditetapkan weight
untuk mendistribusikan beban, dengan setiap
endpoint menerima bagian traffic pelaporan yang ditentukan. Endpoint juga dapat
ditetapkan 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. 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 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 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 dibuat di klien.
Karena example.com
tidak memiliki visibilitas ke log server foobar.com
, pengguna 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 telah 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 dicegat 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}`);
});