เกริ่นนำ
การบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย (NEL) เป็นกลไกในการรวบรวมข้อผิดพลาดเกี่ยวกับเครือข่ายฝั่งไคลเอ็นต์จากต้นทาง
โดยจะใช้ส่วนหัวการตอบกลับ HTTP NEL
เพื่อบอกเบราว์เซอร์ให้รวบรวมข้อผิดพลาดของเครือข่าย แล้วผสานรวมกับ Reporting API เพื่อรายงานข้อผิดพลาดไปยังเซิร์ฟเวอร์
ภาพรวมของ Reporting API เดิม
��่วนหัว Report-To
เ��ิม
หากต้องการใช้ Reporting API เดิม คุณจะต้องตั้งค่าส่วนหัวการตอบกลับ HTTP ของ Report-To
ค่าเป็นออบเจ็กต์ที่อธิบายกลุ่มปลายทางของเบราว์เซอร์เพื่อรายงานข้อผิดพลาด ดังนี้
Report-To:
{
"max_age": 10886400,
"endpoints": [{
"url": "https://analytics.provider.com/browser-errors"
}]
}
หาก URL ปลายทางอยู่ในต้นทางอื่นนอกเหนือจากเว็บไซต์ อุปกรณ์ปลายทางควรรองรับคำขอการตรวจสอบล่วงหน้าของ CORS (เช่น 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
)
ในตัวอย่าง การส่งส่วนหัวการตอบกลับนี้พร้อมด้วยหน้าหลักจะเป็นการกำหนดค่าเบราว์เซอร์ให้รายงานคำเตือนที่เบราว์เซอร์สร้างขึ้นไปยังปลายทาง https://analytics.provider.com/browser-errors
เป็นเวลา max_age
วินาที
โปรดทราบว่าระบบจะไม่สนใจคำขอ HTTP ที่ตามมาทั้งหมดที่หน้าเว็บนั้นสร้างขึ้น (สำหรับรูปภาพ สคริปต์ ฯลฯ) การกำหนดค่าจะเป็นการตั้งค่าระหว่างการตอบสนองของหน้าหลัก
คำอธิบายช่องส่วนหัว
การกำหนดค่าปลายทางแต่ละรายการจะมีชื่อ group
, max_age
และอาร์เรย์ endpoints
คุณยังเลือกได้ว่าจะพิจารณาโดเมนย่อยเมื่อรายงานข้อผิดพลาดโดยใช้ช่อง include_subdomains
หรือไม่
ฟิลด์ | ประเภท | คำอธิบาย |
---|---|---|
group |
string | ไม่บังคับ หากไม่ได้ระบุชื่อ group ปลายทางจะใช้ชื่อ "ค่าเริ่มต้น" |
max_age |
ตัวเลข | ต้องระบุ จำนวนเต็มที่ไม่เป็นลบที่กำหนดอายุการใช้งานของปลายทางในหน่วยวินาที ค่า "0" จะทำให้กลุ่มปลายทางถูกนำออกจากแคชการรายงานของ User Agent |
endpoints |
อาร์เรย์<ออบเจ็กต์> | ต้องระบุ อาร์เรย์ของออบเจ็กต์ JSON ที่ระบุ URL จริงของเครื่องมือรวบรวมรายงาน |
include_subdomains |
boolean | ไม่บังคับ บูลีนที่เปิดใช้กลุ่มปลายทางสำหรับโดเมนย่อยทั้งหมดของโฮสต์ต้นทางปัจจุบัน หากละเว้นหรือไม่ใช่ "จริง" ระบบจะไม่รายงานโดเมนย่อยไปยังปลายทาง |
ชื่อ group
เป็นชื่อที่ไม่ซ้ำกันซึ่งใช้เพื่อเชื่อมโยงสตริงกับปลายทาง ให้ใช้ชื่อนี้ในที่อื่นๆ ที่ผสานรวมกับ Reporting API เพื่ออ้างอิงถึงกลุ่มปลายทางที่เจาะจง
นอกจากนี้ ช่อง max-age
ยังต้องระบุและระบุระยะเวลาที่เบราว์เซอร์ควรใช้ปลายทางและรายงานข้อผิดพลาด
ช่อง endpoints
เป็นอาร์เรย์สำหรับฟีเจอร์เฟลโอเวอร์และการจัดสรรภาระงาน โปรดดูส่วนเกี่ยวกับเฟลโอเวอร์และการจัดสรรภาระงาน โปรดทราบว่าเบราว์เซอร์จะเลือกปลายทางเพียง 1 รายการ แม้ว่ากลุ่มจะแสดงผู้รวบรวมหลายรายการใน endpoints
ก็ตาม หากคุณต้องการส่งรายงานไปยังเซิร์ฟเวอร์หลายแห่งพร้อมกัน แบ็กเอนด์จะต้องส่งต่อรายงานเหล่านั้น
เบราว์เซอร์ส่งรายงานอย่างไร
เบราว์เซอร์จะจัดกลุ่มรายงานเป็นระยะๆ แล้วส่งไปยังปลายทางการรายงานที่คุณกำหนดค่าไว้
ในการส่งรายงาน เบราว์เซอร์จะออกคำขอ POST
ที่มี Content-Type: application/reports+json
และเนื้อความที่มีอาร์เรย์ของคำเตือน/ข้อผิดพลาดที่บันทึกไว้
เบราว์เซอร์จะส่งรายงานเมื่อใด
ส่งรายงานนอกขอบเขตจากแอปของคุณ ซึ่งหมายความว่าเบราว์เซอร์จะควบคุมเมื่อมีการส่งรายงานไปยังเซิร์ฟเวอร์ของคุณ
เบราว์เซอร์จะพยายามส่งรายงานในคิวในช่วงเวลาที่เหมาะสมที่สุด ซึ่งอาจทำได้ในทันทีเมื่อพร้อม (เพื่อใ��้ความคิดเห็นแก่นักพัฒนาซอฟต์แวร์ได้ทันท่วงที) แต่เบราว์เซอร์ยังอาจชะลอการนำส่งได้หากเบราว์เซอร์ไม่ว่างเนื่องจากกำลังประมวลผลงานที่มีลำดับความสำคัญสูงกว่า หรือหากผู้ใช้อยู่ในเครือข่ายที่ช้าและ/หรือหนาแน่นในขณะนั้น เบราว์เซอร์อาจให้ความสำคัญกับการส่งรายงานเกี่ยวกับต้นทางหนึ่งๆ ก่อน หากผู้ใช้เข้าชมบ่อย
ไม่มีข้อกังวลด้านประสิทธิภาพมากนัก (เช่น การช่วงชิงเครือข่ายกับแอปของคุณ) เมื่อใช้ Reporting API นอกจากนี้ ยังไม่มีวิธีใดในการควบคุมเวลาที่เบราว์เซอร์ส่งรายงานในคิว
การกำหนดค่าปลายทางหลายจุด
การตอบสนองแบบเดียวกำหนดค่าปลายทางหลายปลายทางพร้อมกันได้โดยการส่งส่วนหัว 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"
}]
}
หรือรวมเข้าด้วยกันเป็นส่วนหัว 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"
}]
}
เมื่อส่งส่วนหัว Report-To
แล้ว เบราว์เซอร์จะแคชปลายทางตามค่า max_age
และส่งคำเตือน/ข้อผิดพลาดที่เป็นอันตรายในคอนโซลไปยัง URL ของคุณ
เฟลโอเวอร์และการจัดสรรภาระงาน
ส่วนใหญ่แล้วคุณจะกำหนดค่าเครื่องมือรวบรวม URL 1 รายการต่อกลุ่ม อย่างไรก็ตาม เนื่องจากการรายงานสร้างการเข้าชมได้เป็นจำนวนมาก ข้อมูลจำเพาะจึงมีฟีเจอร์เฟลโอเวอร์และฟีเจอร์การจัดสรรภาระงานที่ได้รับแรงบันดาลใจมาจากระเบียน SRV ของ DNS
เบราว์เซอร์จะพยายามอย่างเต็มที่เพื่อส่งรายงานไปยังปลายทางมากที่สุด 1 รายการในกลุ่ม ปลายทางจะกำหนด weight
เพื่อกระจายภาระงาน โดยที่ปลายทางแต่ละรายการจะได้รับเศษส่วนของการรับส่งข้อมูลการรายงานที่ระบุ นอกจากนี้ คุณยังกำหนด priority
ให้กับปลายทางเพื่อตั้งค่าผู้รวบรวมวิดีโอสำรองได้ด้วย
ระบบจะลองใช้ตัวรวบรวมสำรองเมื่ออัปโหลดไปยังตัวรวบรวมหลักไม่สำเร็จเท่า��ั้น
ตัวอย่าง: สร้างเครื่องมือรวบรวมสำรองที่ 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}
]
}
การตั้งค่าการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย
ตั้งค่า
หากต้องการใช้ NEL ให้ตั้งค่าส่วนหัว Report-To
กับเครื่องมือรวบรวมที่ใช้กลุ่มที่มีชื่อ ดังนี้
Report-To: {
...
}, {
"group": "network-errors",
"max_age": 2592000,
"endpoints": [{
"url": "https://analytics.provider.com/networkerrors"
}]
}
ขั้นตอนถัดไป ให้ส่งส่วนหัวการตอบกลับ NEL
เพื่อเริ่มรวบรวมข้อผิดพลาด เนื่องจาก NEL เป็นการเลือกใช้สำหรับต้นทาง คุณจึงต้องส่งส่วนหัวเพียงครั้งเดียว ทั้ง NEL
และ Report-To
จะมีผลกับคำขอในอนาคตที่ส่งไปยังต้นทางเดียวกัน และจะรวบรวมข้อมูลข้อผิดพลาดต่อไปตามค่า max_age
ที่ใช้ตั้งค่าเครื่องมือรวบรวม
ค่าของส่วนหัวควรเป็นออบเจ็กต์ JSON ที่มีช่อง max_age
และ report_to
โปรดใช้ชื่อหลังในการอ้างอิงชื่อกลุ่มของเครื่องมือรวบรวมข้อผิดพลาดเกี่ยวกับเครือข่าย
GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}
ทรัพยากรย่อย
ตัวอย่าง: หาก example.com
โหลด foobar.com/cat.gif
และทรัพยากรนั้นโหลดไม่สำเร็จ ให้ทำดังนี้
- ผู้เรียกเก็บเงิน NEL ของ
foobar.com
ได้รับการแจ้งเตือน - ผู้รวบรวม NEL ของ
example.com
ไม่ได้รับการแจ้งเตือน
หลักการทั่วไปคือ NEL จะสร้างบันทึกฝั่งเซิร์ฟเวอร์ขึ้นใหม่ ซึ่งเพิ่งสร้างขึ้นในไคลเอ็นต์
เนื่องจาก example.com
ไม่สามารถเข้าถึงบันทึกเซิร์ฟเวอร์ของ foobar.com
ได้ จึงไม่ม��ระดับการเข้าถึงรายงาน NEL ของตนเองเช่นกัน
การแก้ไขข้อบกพร่องของการกำหนดค่ารายงาน
หากไม่เห็นรายงานปรากฏในเซิร์ฟเวอร์ ให้ไปที่ chrome://net-export/
หน้าดังกล่าวมีประโยชน์ในการยืนยันว่าสิ่งต่างๆ ได้รับการกำหนดค่าอย่างถูกต้องและมีการส่งรายงานอย่างเหมาะสม
แล้ว ReportingObserver ล่ะ
ReportingObserver
เป็นกลไกการรายงานที่เกี่ยวข้องแต่แตกต่างกัน โดยอิงตามการเรียก JavaScript
ไม่เหมาะกับการบันทึกข้อผิดพลาดเกี่ยวกับเครือข่าย เนื่องจากข้อผิดพลาดของเครือข่ายจะสกัดกั้นผ่าน JavaScript ไม่ได้
เซิร์ฟเวอร์ตัวอย่าง
ด้านล่างคือตัวอย่างเซิร์ฟเวอร์โหนดที่ใช้ Express ซึ่งจะแสดงวิธีกำหนดค่าการรายงานข้อผิดพลาดเกี่ยวกับเครือข่าย และสร้างตัวจัดการเฉพาะเพื่อเก็บผลลัพธ์
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}`);
});