تسجيل خطأ في الشبكة (NEL)

Eric Bidelman

Maud Nalpas

مقدمة

تسجيل أخطاء الشبكة (NEL) هو آلية جمع أخطاء الشبكة من جهة العميل من مصدر معيّن.

وهو يستخدم عنوان استجابة HTTP NEL ليطلب من المتصفّح جمع أخطاء الشبكة، ثم يتكامل مع Reporting API من أجل إبلاغ الخادم بالأخطاء.

تنبيه: لإعداد "تسجيل أخطاء الشبكة" لموقعك الإلكتروني، ستحتاج إلى استخدام واجهة Reporting API القديمة التي تعتمد على عنوان Report-To. ويرجع ذلك إلى أنّ واجهة Reporting API الجديدة التي تعتمد على العنوان Reporting-Endpoints لا تتيح تسجيل أخطاء الشبكة. يمكنك الاطّلاع على المزيد من المعلومات في توافق المتصفّح. بدلاً من ذلك، سيتم تطوير آلية جديدة لتسجيل أخطاء الشبكة في المستقبل. وعندما تصبح هذه الواجهة متاحة، يمكنك التبديل من واجهة 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	سلسلة	اختياريّ. إذا لم يتم تحديد اسم group، سيُسمّى "default" لنقطة النهاية.
max_age	الرقم	مَعلمة مطلوبة. عدد صحيح غير سالب يحدد عمر نقطة النهاية بالثواني. القيمة "0" سيؤدي إلى إزالة مجموعة النهاية من ذاكرة التخزين المؤقت لإعداد تقارير وكيل المستخدم.
endpoints	مصفوفة<Object>	مَعلمة مطلوبة. مصفوفة من كائنات JSON التي تحدِّد عنوان URL الفعلي لأداة جمع التقارير.
include_subdomains	منطقي	اختياريّ. قيمة منطقية تفعِّل مجموعة نقاط النهاية لجميع النطاقات الفرعية لمضيف المصدر الحالي. إذا تم حذفها أو استخدام أي شيء آخر بخلاف "صحيح"، لا يتم إبلاغ نقطة النهاية بالنطاقات الفرعية.

اسم group هو اسم فريد يُستخدم لربط سلسلة بـ نقطة نهاية. استخدام هذا الاسم في أماكن أخرى تتكامل مع مع Reporting API من أجل الإشارة إلى مجموعة نقاط نهاية محدّدة.

يجب أيضًا ملء الحقل max-age ويحدد كيفية مدة استخدام المتصفح لنقطة النهاية وإبلاغه بالأخطاء.

الحقل endpoints هو مصفوفة لتوفير موازنة الحمل وتجاوز الأعطال. الجديدة. راجِع القسم الذي يتناول تجاوز الأعطال وموازنة التحميل. من المهم تجدر الإشارة إلى أنّ المتصفح سيختار نقطة نهاية واحدة فقط، حتى إذا كانت المجموعة تضم عدة هواة جمع في endpoints. إذا كنت ترغب في إرسال إلى عدة خوادم دفعة واحدة، فستحتاج الخلفية إلى إعادة توجيه التقارير.

كيف يرسل المتصفّح التقارير؟

يجمّع المتصفّح التقارير بشكل دوري ويرسلها إلى التقارير. نقاط النهاية التي تقوم بتهيئتها.

لإرسال التقارير، يُصدر المتصفّح 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:

سيبذل المتصفّح قصارى جهده لإرسال تقرير إلى نقطة نهاية واحدة على الأكثر. في مجموعة. يمكن تعيين 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}

تنبيه: يستخدم العنوان Report-To واصلة. هنا، تستخدم report_to شرطة سفلية.

المراجع الفرعية

نقطة رئيسية: تعمل NEL على التنقّل وجلب الموارد الفرعية. أمّا بالنسبة إلى الموارد الفرعية، فلا يمكن للصفحة التي تتضمّن الصفحة الاطّلاع على تقارير NEL حول الطلبات الواردة من مصادر متعددة التي تقدّمها.

مثال: في حال تحميل example.com foobar.com/cat.gif وتعذُّر هذا المورد للتحميل:

• تم إشعار جامع NEL الخاص بـ foobar.com
• لا يتم إرسال إشعار إلى جامع NEL الخاص بـ example.com

تشير رسالة الأشكال البيانية أن NEL يعيد إنتاج السجلات من جانب الخادم، التي تم إنشاؤها للتو في للعميل.

بما أنّ example.com ليس لديه إذن الوصول إلى خادم foobar.com السجلات، فإنها لا تتوفر لها أيضًا إمكانية الاطلاع على تقارير NEL الخاصة به.

تصحيح أخطاء تكوينات تقرير

إذا لم تظهر لك التقارير على الخادم، انتقِل إلى chrome://net-export/ هذه الصفحة مفيدة للتحقّق من الإعدادات بشكل صحيح، ويتم إرسال التقارير بشكل صحيح.

ماذا عن ReportingObserver؟

إنّ ReportingObserver هي آلية ذات صلة، ولكنّها مختلفة للإبلاغ عن المحتوى. وهو يعتمد على استدعاءات JavaScript. لا يصلح لتسجيل أخطاء الشبكة، لأن أخطاء الشبكة باستخدام JavaScript.

مثال على الخادم

في ما يلي مثال على خادم عقدة يستخدم Express. يعرض هذا القسم كيفية ضبط التقارير حول أخطاء الشبكة، ويُنشئ معالِجًا مخصّصًا لتسجيل النتيجة.

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)
• دليل نقل البيانات من الإصدار 0 إلى الإصدار 1 من Reporting API
• المواصفات: واجهة Reporting API القديمة (الإصدار 0)
• المواصفات: واجهة Reporting API الجديدة (الإصدار 1)