רישום שגיאות ברשת (NEL)

Eric Bidelman

Maud Nalpas

מבוא

רישום שגיאות ברשת (NEL) הוא מנגנון לאיסוף שגיאות ברשת בצד הלקוח ממקור.

הוא משתמש בכותרת תגובת NEL HTTP כדי להנחות את הדפדפן לאסוף שגיאות בחיבור לרשת, ואז הוא משתלב עם 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 הוא שם ייחודי שמשמש לשיוך מחרוזת לנקודת קצה. כדי להתייחס לקבוצת נקודות קצה ספציפית, צריך להשתמש בשם הזה במקומות אחרים שמשולבים עם Reporting API.

גם השדה max-age הוא שדה חובה, ובו מציינים כמה זמן הדפדפן צריך להשתמש בנקודת הקצה ולדווח עליה שגיאות.

השדה endpoints הוא מערך שנועד לספק תכונות של יתירות כשל ואיזון עומסים. מידע נוסף מופיע בסעיף בנושא מעבר לגיבוי (Failover) ואיזון עומסים. חשוב לציין שהדפדפן יבחר רק נקודת קצה אחת, גם אם הקבוצה מפרטת כמה אוספים ב-endpoints. אם רוצים לשלוח דוח לכמה שרתים בבת אחת, צריך להגדיר את ה-Backend להעברת הדוחות.

איך הדפדפן שולח דוחות?

הדפדפן מאגד דוחות מעת לעת ושולח אותם לנקודות הקצה של הדיווח שהגדרתם.

כדי לשלוח דוחות, הדפדפן שולח בקשת 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 אחד לכל קבוצה. עם זאת, מכיוון שהדיווח יכול ליצור נפח תנועה גדול, המפרט כולל תכונות של מעבר לגיבוי אוטומטי ואיזון עומסים בהשראת רשומת ה-SRV של DNS.

הדפדפן ישתדל להעביר דוח לנקודת קצה אחת לכל היותר בקבוצה. אפשר להקצות לנקודות קצה 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
• example.com לא מקבל הודעה על איסוף נתוני NEL

הכלל הוא ש-NEL משחזרת יומנים בצד השרת, רק שהם נוצרים בצד הלקוח.

מכיוון של-example.com אין גישה ליומני השרת של foobar.com, אין לה גם גישה לדוחות NEL שלו.

ניפוי באגים בהגדרות של דוחות

אם אתם לא רואים דוחות בשרת, אפשר לעבור אל chrome://net-export/. הדף הזה שימושי כדי לוודא שההגדרות בוצעו בצורה נכונה ושהדוחות נשלחים כמו שצריך.

מה לגבי ReportingObserver?

‫ReportingObserver הוא מנגנון דיווח קשור, אבל שונה. היא מבוססת על קריאות JavaScript. הוא לא מתאים לרישום ביומן של שגיאות ברשת, כי אי אפשר ליירט שגיאות ברשת באמצעות JavaScript.

שרת לדוגמה

בהמשך מוצגת דוגמה לשרת Node שמשתמש ב-Express. במאמר מוסבר איך להגדיר דיווח על שגיאות ברשת ואיך ליצור handler ייעודי לתיעוד התוצאה.

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 (המאמר הראשי בנושא Reporting API)
• מדריך להעברה מ-Reporting API v0 ל-v1
• מפרט: גרסה קודמת של Reporting API‏ (v0)
• מפרט: Reporting API חדש (גרסה 1)