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 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ị là đối tượng mô tả nhóm điểm cuối của 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, điểm cuối sẽ hỗ trợ các yêu cầu kiểm tra 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ụ: gửi tiêu đề phản hồi này cùng với trang chính của bạn đị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. Cần lưu ý rằng tất cả các yêu cầu HTTP sau đó do trang (đố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 nội dung phản hồi của trang chính.

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

Mỗi cấu hình điểm cuối chứa một tên group, max_age và endpoints . Bạn cũng có thể chọn xem có xem xét các miền con khi báo cáo hay không lỗi bằng cách sử dụng trường include_subdomains.

Tên group là 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 ở các vị trí khác có tích hợp bằng API Báo cáo để tham chiếu đến một nhóm thiết bị đầu cuối cụ thể.

Trường max-age cũng là trường bắt buộc và quy định cách thức 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 tính năng chuyển đổi dự phòng và cân bằng tải các tính năng AI mới. Hãy xem phần Chuyển đổi cơ chế và cân bằng tải. Bây giờ cần lưu ý rằng trình duyệt sẽ chỉ chọn một điểm cuối, thậm chí nếu nhóm liệt kê nhiều trình thu thập trong endpoints. Nếu bạn muốn gửi một báo cáo cho nhiều máy chủ cùng một lúc, chương trình phụ trợ của bạn sẽ cần chuyển tiếp .

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

Trình duyệt định kỳ báo cáo theo lô và gửi đến báo cáo điểm cuối mà bạn định cấu hình.

Để gửi báo cáo, trình duyệt sẽ đưa ra một POST gửi yêu cầu bằng Content-Type: application/reports+json và một phần 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 báo cáo được gửi đế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ể ngay khi chúng sẵn sàng (để cung cấp 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 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 tải chậm và/hoặc mạng bị nghẽn tại thời điểm đó. Trình duyệt cũng có thể ưu tiên gửi trước tiên sẽ báo cáo về nguồn gốc cụ thể nếu người dùng là khách truy cập thường xuyên.

Hầu như không phải lo lắng 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. Có cũng không có cách nào để kiểm soát thời điểm trình duyệt gửi các báo cáo được xếp 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 vào 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 các giá trị max_age của chúng và gửi tất cả những bảng điều khiển khó chịu đó các cảnh báo/lỗi đối với URL của mình.

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

Trong hầu hết 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 rất nhiều lưu lượng truy cập, nên thông số kỹ thuật bao gồm tính năng chuyển đổi dự phòng và cân bằng tải lấy cảm hứng từ DNS Bản ghi SRV.

Trình duyệt sẽ cố gắng hết sức để gửi báo cáo cho tối đa một điểm cuối trong một nhóm. Các điểm cuối có thể được chỉ định một weight để phân phối tải, trong đó mỗi điểm cuối nhận được một phần được chỉ định của lưu lượng truy cập báo cáo. Điểm cuối có thể cũng được chỉ định priority để 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 trình thu thập chính lên.

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 trình thu thập sử dụng một 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 thông tin về lỗi. Từ NEL là chọn tham gia một nguồn gốc, 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 cho 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 có chứa max_age và Trường 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 thành công để tải:

• Trình thu thập NEL của foobar.com đã được thông báo
• Trình thu thập NEL của example.com không được thông báo

Chiến lược phát hành đĩa đơn quy tắc chung là NEL tái tạo nhật ký phía máy chủ, vừa được tạo trên khách hàng.

Vì example.com không có khả năng hiển thị trong máy chủ của foobar.com nhật ký của mình, nhưng bạn cũng không nhìn thấy báo cáo NEL của mình.

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

Nếu bạn không thấy báo cáo hiển thị trên máy chủ của mình, hãy truy cập chrome://net-export/. Trang đó hữu ích cho xác minh mọi thứ được định cấu hình chính xác và các báo cáo đang được gửi đúng cách.

Còn ReportingNgười quan sát báo cáo thì sao?

ReportingObserver là một cơ chế báo cáo có liên quan nhưng khác. API này dựa trên các lệnh gọi JavaScript. Công cụ này không phù hợp để ghi nhật ký lỗi mạng, vì lỗi mạng mà không thể chặn thông qua JavaScript.

Máy chủ mẫu

Dưới đây là ví dụ về máy chủ Nút sử dụng Express. Tài liệu này trình bày cách định cấu hình tính năng báo cáo cho các lỗi mạng và tạo một trình xử lý chuyên dụng để nắm bắt 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 trên API Báo cáo)
• Hướng dẫn di chuyển từ API Báo cáo phiên bản 0 sang phiên bản 1
• Thông số kỹ thuật: API Báo cáo cũ (v0)
• Quy cách: API Báo cáo mới (phiên bản 1)