Giới thiệu
Ghi nhật ký lỗi mạng (NEL) là một cơ chế thu thập lỗi mạng phía máy khách từ một nguồn gốc.
API này sử dụng tiêu đề phản hồi HTTP NEL
để yêu cầu trình duyệt thu thập lỗi mạng, sau đó tích hợp với API Báo cáo để báo cáo lỗi cho máy chủ.
Tổng quan về API Báo cáo cũ
Tiêu đề Report-To
cũ
Để sử dụng API Báo cáo cũ, bạn cần đặt tiêu đề phản hồi HTTP Report-To
. Giá trị của thuộc tính này là một đối tượng mô tả một nhóm điểm cuối để trình duyệt báo cáo lỗi đến:
Report-To:
{
"max_age": 10886400,
"endpoints": [{
"url": "https://analytics.provider.com/browser-errors"
}]
}
Nếu URL điểm cuối của bạn nằm trên một nguồn gốc khác với trang web của bạn, thì điểm cuối đó phải hỗ trợ các yêu cầu trước khi bay CORS. (ví dụ: 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
).
Trong ví dụ này, việc gửi tiêu đề phản hồi này với trang chính sẽ định cấu hình trình duyệt để báo cáo các cảnh báo do trình duyệt tạo đến điểm cuối https://analytics.provider.com/browser-errors
trong max_age
giây.
Điều quan trọng cần lưu ý là tất cả các yêu cầu HTTP tiếp theo do trang thực hiện (đối với hình ảnh, tập lệnh, v.v.) sẽ bị bỏ qua. Cấu hình được thiết lập trong quá trình phản hồi của trang chính.
Giải thích về các trường tiêu đề
Mỗi cấu hình điểm cuối chứa một tên group
, mảng max_age
và endpoints
. Bạn cũng có thể chọn xem có xem xét miền con khi báo cáo lỗi hay không bằng cách sử dụng trường include_subdomains
.
Trường | Loại | Mô tả |
---|---|---|
group |
chuỗi | Không bắt buộc. Nếu bạn không chỉ định tên group , thì điểm cuối sẽ được đặt tên là "mặc định". |
max_age |
số | Bắt buộc. Một số nguyên không âm xác định thời gian tồn tại của điểm cuối tính bằng giây. Giá trị "0" sẽ khiến nhóm điểm cuối bị xoá khỏi bộ nhớ đệm báo cáo của tác nhân người dùng. |
endpoints |
Mảng<Đối tượng> | Bắt buộc. Một mảng đối tượng JSON chỉ định URL thực tế của trình thu thập báo cáo. |
include_subdomains |
boolean | Không bắt buộc. Một boolean bật nhóm điểm cuối cho tất cả miền con của máy chủ lưu trữ gốc hiện tại. Nếu bạn bỏ qua hoặc nhập giá trị khác "true", thì các miền con sẽ không được báo cáo cho điểm cuối. |
Tên group
là một tên duy nhất dùng để liên kết một chuỗi với một điểm cuối. Sử dụng tên này ở những nơi khác tích hợp với API Báo cáo để tham chiếu đến một nhóm điểm cuối cụ thể.
Trường max-age
cũng là trường bắt buộc và chỉ định thời lượng trình duyệt sẽ sử dụng điểm cuối và báo cáo lỗi cho điểm cuối đó.
Trường endpoints
là một mảng cung cấp các tính năng dự phòng và cân bằng tải. Xem phần Chuyển sang dự phòng và cân bằng tải. Điều quan trọng cần lưu ý là trình duyệt sẽ chỉ chọn một điểm cuối, ngay cả khi nhóm liệt kê một số trình thu thập trong endpoints
. Nếu bạn muốn gửi một báo cáo đến nhiều máy chủ cùng một lúc, thì phần phụ trợ của bạn sẽ cần chuyển tiếp các báo cáo đó.
Trình duyệt gửi báo cáo như thế nào?
Trình duyệt định kỳ tạo các báo cáo theo lô và gửi các báo cáo đó đến các điểm cuối báo cáo mà bạn định cấu hình.
Để gửi báo cáo, trình duyệt sẽ đưa ra yêu cầu POST
với Content-Type: application/reports+json
và nội dung chứa mảng cảnh báo/lỗi đã được ghi lại.
Khi nào trình duyệt gửi báo cáo?
Báo cáo được phân phối ngoài phạm vi ứng dụng, nghĩa là trình duyệt kiểm soát thời điểm gửi báo cáo đến(các) máy chủ của bạn.
Trình duyệt sẽ cố gắng phân phối các báo cáo đã xếp hàng vào thời điểm thích hợp nhất. Điều này có thể xảy ra ngay khi dữ liệu sẵn sàng (để cung cấp phản hồi kịp thời cho nhà phát triển), nhưng trình duyệt cũng có thể trì hoãn việc phân phối nếu đang bận xử lý công việc có mức độ ưu tiên cao hơn hoặc nếu người dùng đang sử dụng mạng chậm và/hoặc bị tắc nghẽn tại thời điểm đó. Trình duyệt cũng có thể ưu tiên gửi báo cáo về một nguồn gốc cụ thể trước tiên, nếu người dùng là khách truy cập thường xuyên.
Hầu như không có vấn đề gì về hiệu suất (ví dụ: tranh chấp mạng với ứng dụng của bạn) khi sử dụng API Báo cáo. Ngoài ra, bạn cũng không có cách nào để kiểm soát thời điểm trình duyệt gửi báo cáo trong hàng đợi.
Định cấu hình nhiều điểm cuối
Một phản hồi duy nhất có thể định cấu hình nhiều điểm cuối cùng một lúc bằng cách gửi nhiều tiêu đề 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"
}]
}
hoặc bằng cách kết hợp các tiêu đề đó thành một tiêu đề HTTP duy nhất:
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"
}]
}
Sau khi bạn gửi tiêu đề Report-To
, trình duyệt sẽ lưu các điểm cuối vào bộ nhớ đệm theo giá trị max_age
của các điểm cuối đó và gửi tất cả các cảnh báo/lỗi khó chịu đó trên bảng điều khiển đến URL của bạn.
Chuyển đổi dự phòng và cân bằng tải
Trong hầu hết các trường hợp, bạn sẽ định cấu hình một trình thu thập URL cho mỗi nhóm. Tuy nhiên, vì tính năng báo cáo có thể tạo ra một lượng lớn lưu lượng truy cập, nên thông số kỹ thuật này bao gồm các tính năng dự phòng và cân bằng tải lấy cảm hứng từ bản ghi SRV của DNS.
Trình duyệt sẽ cố gắng hết sức để phân phối báo cáo đến tối đa một điểm cuối trong một nhóm. Bạn có thể chỉ định weight
cho các điểm cuối để phân phối tải, trong đó mỗi điểm cuối sẽ nhận được một phần lưu lượng truy cập báo cáo được chỉ định. Bạn cũng có thể chỉ định priority
cho các điểm cuối để thiết lập trình thu thập dự phòng.
Bộ thu dự phòng chỉ được thử khi quá trình tải lên bộ thu chính không thành công.
Ví dụ: Tạo trình thu thập dự phòng tại 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}
]
}
Thiết lập tính năng Ghi nhật ký lỗi mạng
Thiết lập
Để sử dụng NEL, hãy thiết lập tiêu đề Report-To
bằng một trình thu thập sử dụng nhóm được đặt tên:
Report-To: {
...
}, {
"group": "network-errors",
"max_age": 2592000,
"endpoints": [{
"url": "https://analytics.provider.com/networkerrors"
}]
}
Tiếp theo, hãy gửi tiêu đề phản hồi NEL
để bắt đầu thu thập lỗi. Vì NEL là tuỳ chọn cho một nguồn gốc, nên bạn chỉ cần gửi tiêu đề một lần. Cả NEL
và Report-To
sẽ áp dụng cho các yêu cầu trong tương lai đến cùng một nguồn gốc và sẽ tiếp tục thu thập lỗi theo giá trị max_age
dùng để thiết lập trình thu thập.
Giá trị tiêu đề phải là một đối tượng JSON chứa trường max_age
và report_to
. Sử dụng tên sau để tham chiếu tên nhóm của trình thu thập lỗi mạng:
GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}
Tài nguyên phụ
Ví dụ: Nếu example.com
tải foobar.com/cat.gif
và tài nguyên đó không tải được:
- Trình thu thập NEL của
foobar.com
được thông báo - Bộ thu thập NEL của
example.com
không được thông báo
Quy tắc chung là NEL tái tạo nhật ký phía máy chủ, chỉ được tạo trên máy khách.
Vì example.com
không có quyền xem nhật ký máy chủ của foobar.com
, nên example.com
cũng không có quyền xem báo cáo NEL.
Cấu hình báo cáo gỡ lỗi
Nếu bạn không thấy báo cáo xuất hiện trên máy chủ, hãy chuyển đến chrome://net-export/
. Trang đó rất hữu ích để xác minh mọi thứ được định cấu hình chính xác và báo cáo được gửi đúng cách.
Còn ReportingObserver thì sao?
ReportingObserver
là một cơ chế báo cáo có liên quan nhưng khác. Lệnh này dựa trên các lệnh gọi JavaScript.
Không phù hợp để ghi lỗi mạng, vì không thể chặn lỗi mạng qua JavaScript.
Máy chủ mẫu
Dưới đây là ví dụ về máy chủ Node sử dụng Express. Bài viết này cho biết cách định cấu hình tính năng báo cáo lỗi mạng và tạo một trình xử lý chuyên dụng để ghi lại kết quả.
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}`);
});