简介
网络错误日志记录 (NEL) 是一种从源收集客户端网络错误的机制。
它使用 NEL
HTTP 响应标头告知浏览器收集网络连接错误,然后与 Reporting API 集成以向服务器报告错误。
旧版 Reporting API 概览
旧版 Report-To
标头
要使用旧版 Reporting API,您需要设置 Report-To
HTTP 响应标头。其值是一个对象,用于描述浏览器要向以下报告错误的端点组:
Report-To:
{
"max_age": 10886400,
"endpoints": [{
"url": "https://analytics.provider.com/browser-errors"
}]
}
如果您的端点网址与您的网站位于不同的来源,端点应支持 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
)。
在该示例中,将此响应标头与主页面一起发送会将浏览器配置为在 max_age
秒内向端点 https://analytics.provider.com/browser-errors
报告浏览器生成的警告。请务必注意,网页发出的所有后续 HTTP 请求(针对图片、脚本等)都会被忽略。配置将在主页面响应期间设置。
标头字段说明
每个端点配置都包含一个 group
名称、max_age
和 endpoints
数组。您还可以使用 include_subdomains
字段选择在报告错误时是否考虑子网域。
字段 | 类型 | 说明 |
---|---|---|
group |
字符串 | 可选。如果未指定 group 名称,则端点的名称为“default”。 |
max_age |
number | 强制要求。一个非负整数,用于定义端点的生命周期(以秒为单位)。值为“0”会导致端点组从用户代理的报告缓存中移除。 |
endpoints |
数组<对象> | 强制要求。用于指定报告收集器的实际网址的 JSON 对象数组。 |
include_subdomains |
boolean | 可选。一个布尔值,用于为当前源主机的所有子网域启用端点组。如果省略或“true”以外的任何其他内容,则不会向端点报告子网域。 |
group
名称是用于将字符串与端点关联的唯一名称。在与 Reporting API 集成的其他地方使用此名称来指代特定端点组。
max-age
字段也是必填字段,用于指定浏览器应在多长时间内使用端点并向端点报告错误。
endpoints
字段是一个数组,用于提供故障切换和负载均衡功能。请参阅故障切换和负载均衡部分。请务必注意,即使该组在 endpoints
中列出了多个收集器,浏览器也只会选择一个端点。如果您想要同时向多个服务器发送报告,您的后端需要转发报告。
浏览器如何发送报告?
浏览器会定期批量处理报告,并将其发送到您配置的报告端点。
为了发送报告,浏览器会发出包含 Content-Type: application/reports+json
的 POST
请求,以及一个包含捕获到的警告/错误数组的正文。
浏览器何时发送报告?
报告在带外从您的应用传送,这意味着浏览器控制何时将报告发送到您的服务器。
浏览器会在最合适的时机尝试传送已加入队列的报告。请求可在一切就绪后立即执行(以便及时向开发者提供反馈),但如果浏览器正忙于处理优先级较高的工作,或者用户当时网络速度较慢和/或网络拥塞,也可能会延迟执行。如果用户是常客,浏览器也可能会优先发送关于特定来源的报告。
使用 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
值缓存端点,并将所有这些糟糕的控制台警告/错误发送到您的网址。
故障切换和负载均衡
大多数情况下,您需要为每个群组配置一个网址收集器。但是,由于报告可以生成大量流量,因此该规范包含受 DNS SRV 记录启发的故障切换和负载均衡功能。
浏览器将尽可能将报告发送到组中最多的一个端点。可以为端点分配 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
值收集错误。
标头值应该是包含 max_age
和 report_to
字段的 JSON 对象。后者可用于引用网络错误收集器的组名称:
GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}
子资源
示例:如果 example.com
加载了 foobar.com/cat.gif
,但该资源无法加载:
foobar.com
的 NEL 收集器会收到通知example.com
的 NEL 收集器不收到通知
一般来说,NEL 会重现刚刚在客户端上生成的服务器端日志。
由于 example.com
无法查看 foobar.com
的服务器日志,因此也无法查看其 NEL 报告。
调试报告配置
如果您在服务器上没有看到报告,请前往 chrome://net-export/
。该页面可用于验证内容配置是否正确,以及报告是否正常发送。
ReportingObserver 怎么样?
ReportingObserver
是一种相关但不同的报告机制。以 JavaScript 调用为基础。
它不适用于网络错误日志记录,因为网络错误无法通过 JavaScript 拦截。
示例服务器
以下是使用 Express 的 Node 服务器示例。该部分介绍了如何配置网络连接错误报告功能,以及如何创建专用处理程序来捕获结果。
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}`);
});
补充阅读材料
- 使用 Reporting API 监控 Web 应用(关于 Reporting API 的主要博文)
- 从 Reporting API v0 迁移到 v1 的迁移指南
- 规范:旧版 Reporting API (v0)
- 规范:新的 Reporting API (v1)