Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Ghi nhật ký lỗi mạng (NEL)

Eric Bidelman

Maud Nalpas

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 Reporting API để báo cáo lỗi cho máy chủ.

Thận trọng: Để thiết lập tính năng Ghi nhật ký lỗi mạng cho trang web, bạn cần sử dụng Reporting API cũ dựa vào tiêu đề Report-To. Điều này là do Reporting API mới (dựa vào tiêu đề Reporting-Endpoints) không hỗ trợ tính năng Ghi nhật ký lỗi mạng. Tìm hiểu thêm trong phần Hỗ trợ trình duyệt. Thay vào đó, một cơ chế mới cho tính năng Ghi nhật ký lỗi mạng sẽ được phát triển trong tương lai. Khi cơ chế mới đó ra mắt, hãy chuyển từ API Báo cáo cũ sang cơ chế mới đó.

Tổng quan về API Báo cáo cũ

Tiêu đề `Report-To` cũ

Để sử dụng Reporting API cũ, bạn cần đặt tiêu đề phản hồi HTTP Report-To. Giá trị của trường này là một đối tượng mô tả nhóm điểm cuối để trình duyệt báo cáo lỗi:

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 kiểm tra trước 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 cùng 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 cho điểm cuối https://analytics.provider.com/browser-errors trong max_age giây. Xin lưu ý rằng 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.) đều 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, max_age và mảng 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à "default".
`max_age`	số	Bắt buộc. Một số nguyên không âm xác định thời gian hoạt động 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`	Array<Object>	Bắt buộc. Một mảng các đố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ữ của nguồn gốc hiện tại. Nếu bạn bỏ qua hoặc đặt giá trị khác với "true", thì các miền con sẽ không được báo cáo cho điểm cuối.

Tên group là tên riêng biệ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 Reporting API để 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 gian trình duyệt nên 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 đổi 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 danh sách nhóm liệt kê một số trình thu thập trong endpoints. Nếu muốn gửi 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 báo cáo.

Trình duyệt gửi báo cáo như thế nào?

Trình duyệt định kỳ gộp các báo cáo và gửi đến đ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 có 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 gửi ngoài băng tần từ ứng dụng của bạn, 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 trong hàng đợi vào thời điểm thích hợp nhất. Quá trình này có thể diễn ra ngay khi báo cáo sẵn sàng (để cung cấp ý kiến 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 gử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 vào 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, nếu người dùng là khách truy cập thường xuyên.

Khi sử dụng Reporting API, bạn hầu như không cần lo ngại về hiệu suất (ví dụ: tranh chấp mạng với ứng dụng của bạn). Ngoài ra, bạn cũng không thể 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 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 chúng 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 và gửi tất cả cảnh báo/lỗi khó chịu đó trong 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ì báo cáo có thể tạo ra nhiều 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 chuyển đổi 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 để gử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 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.

Trình thu thập dự phòng chỉ được thử khi không tải được lên trình thu thập chính.

Ví dụ: Tạo một 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à tính năng chọn sử dụng 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 đối với cùng một nguồn gốc và sẽ tiếp tục thu thập lỗi theo giá trị max_age được 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. Hãy 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}

Thận trọng: Tiêu đề Report-To sử dụng dấu gạch nối. Ở đây, report_to sử dụng dấu gạch dưới.

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 đã nhận được thông báo
Trình thu thập NEL của example.com không được thông báo

Nguyên tắc chung là NEL tái tạo nhật ký phía máy chủ, vừa đượ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 cũng không có quyền xem báo cáo NEL của.

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ủ của mình, hãy truy cập vào chrome://net-export/. Trang đó rất hữu ích cho việc xác minh rằng mọi thứ được định cấu hình chính xác và báo cáo đang được gửi đ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 biệt. Chỉ số này dựa trên các lệnh gọi JavaScript. Phương thức này không phù hợp để ghi nhật ký lỗi mạng vì không thể chặn lỗi mạng thông qua JavaScript.

Máy chủ mẫu

Dưới đây là ví dụ về máy chủ Node sử dụng Express. Ví dụ này cho thấy cách định cấu hình báo cáo lỗi mạng và tạo một trình xử lý chuyên biệt để 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}`);
});

Tài liệu đọc thêm

Giám sát ứng dụng web bằng API Báo cáo (bài đăng chính về API Báo cáo)
Hướng dẫn di chuyển từ Reporting API phiên bản 0 sang phiên bản 1
Thông số kỹ thuật: Reporting API cũ (phiên bản 0)
Thông số kỹ thuật: Reporting API mới (phiên bản 1)

Ghi nhật ký lỗi mạng (NEL) Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Giới thiệu

Tổng quan về API Báo cáo cũ

Tiêu đề Report-To cũ

Giải thích về các trường tiêu đề

Trình duyệt gửi báo cáo như thế nào?

Khi nào trình duyệt gửi báo cáo?

Định cấu hình nhiều điểm cuối

Chuyển đổi dự phòng và cân bằng tải

Thiết lập tính năng Ghi nhật ký lỗi mạng

Thiết lập

Tài nguyên phụ

Cấu hình báo cáo gỡ lỗi

Còn ReportingObserver thì sao?

Máy chủ mẫu

Tài liệu đọc thêm

Ghi nhật ký lỗi mạng (NEL)

Tiêu đề `Report-To` cũ