Ağ Hatası Günlük Kaydı (NEL)

Eric Bidelman

Maud Nalpas

Giriş

Ağ Hatası Günlüğe Kaydetme (NEL), bir kaynaktan istemci taraflı ağ hatalarını toplama mekanizmasıdır.

Tarayıcıya ağ hatalarını toplamasını bildirmek için NEL HTTP yanıt üstbilgisini kullanır, ardından hataları bir sunucuya bildirmek için Reporting API ile entegre olur.

Eski Reporting API'ye genel bakış

Eski Report-To üstbilgisi

Eski Reporting API'yi kullanmak için bir Report-To HTTP yanıt başlığı ayarlamanız gerekir. Değeri, tarayıcının hataları bildireceği bir uç nokta grubunu tanımlayan bir nesnedir:

Report-To:
{
    "max_age": 10886400,
    "endpoints": [{
    "url": "https://analytics.provider.com/browser-errors"
    }]
}

Uç nokta URL'niz sitenizden farklı bir kaynakta bulunuyorsa uç nokta, CORS ön kontrol isteklerini desteklemelidir. (ör. 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).

Örnekte, bu yanıt üstbilgisinin ana sayfanızla birlikte gönderilmesi, tarayıcı tarafından oluşturulan uyarıları max_age saniye boyunca https://analytics.provider.com/browser-errors uç noktasına bildirecek şekilde yapılandırır. Sayfa tarafından yapılan sonraki tüm HTTP isteklerinin (resimler, komut dosyaları vb. için) yoksayıldığını unutmayın. Yapılandırma, ana sayfanın yanıtı sırasında ayarlanır.

Başlık alanlarının açıklaması

Her uç nokta yapılandırması bir group adı, max_age ve endpoints dizisi içerir. Ayrıca, include_subdomains alanını kullanarak hataları bildirirken alt alan adlarının dikkate alınıp alınmayacağını da seçebilirsiniz.

group adı, bir dizeyi bir uç noktayla ilişkilendirmek için kullanılan benzersiz bir addır. Belirli bir uç nokta grubuna referans vermek için Reporting API ile entegre olan diğer yerlerde bu adı kullanın.

max-age alanı da gereklidir ve tarayıcının uç noktayı ne kadar süre boyunca kullanacağını ve bu uç noktaya hataları nasıl bildireceğini belirtir.

endpoints alanı, yük devretme ve yük dengeleme özelliklerini sağlayan bir dizidir. Yük devretme ve yük dengeleme ile ilgili bölüme bakın. Grup endpoints içinde birkaç toplayıcı listelemiş olsa bile tarayıcının yalnızca bir uç nokta seçeceğini unutmayın. Bir raporu aynı anda birkaç sunucuya göndermek istiyorsanız arka uç sunucunuzun raporları iletmesi gerekir.

Tarayıcı, raporları nasıl gönderir?

Tarayıcı, raporları düzenli olarak toplu hale getirir ve yapılandırdığınız raporlama uç noktalarına gönderir.

Tarayıcı, rapor göndermek için Content-Type: application/reports+json ile birlikte bir POSTisteği ve yakalanan uyarı/hata dizisini içeren bir gövde gönderir.

Tarayıcı ne zaman rapor gönderir?

Raporlar, uygulamanızdan bant dışı olarak yayınlanır. Yani raporların sunucularınıza ne zaman gönderileceğini tarayıcı kontrol eder.

Tarayıcı, sıraya alınmış raporları en uygun zamanda yayınlamaya çalışır. Bu, hazır oldukları anda olabilir (geliştiriciye zamanında geri bildirim sağlamak için) ancak tarayıcı, daha yüksek öncelikli bir işi işleme konusunda meşgulse veya kullanıcı o sırada yavaş ve/veya yoğun bir ağdaysa yayınlamayı geciktirebilir. Tarayıcı, kullanıcı sık ziyaretçiyse önce belirli bir kaynakla ilgili raporları göndermeye de öncelik verebilir.

Reporting API'yi kullanırken performansla ilgili çok az sorun (ör. uygulamanızla ağ çekişmesi) yaşanır. Ayrıca, tarayıcı tarafından sıraya eklenen raporların ne zaman gönderileceğini kontrol etmenin bir yolu yoktur.

Birden fazla uç nokta yapılandırma

Tek bir yanıt, birden fazla Report-To üstbilgisi göndererek aynı anda birden fazla uç noktayı yapılandırabilir:

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"
             }]
           }

tek bir HTTP başlığında birleştirerek kullanabilirsiniz:

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 başlığını gönderdikten sonra tarayıcı, uç noktaları max_age değerlerine göre önbelleğe alır ve bu can sıkıcı konsol uyarılarının/hatalarının tümünü URL'lerinize gönderir.

Yedekleme ve yük dengeleme

Çoğu zaman, her grup için tek bir URL toplayıcı yapılandırırsınız. Ancak raporlama çok fazla trafik oluşturabileceğinden, spesifikasyonda DNS SRV kaydından ilham alan yedekleme ve yük dengeleme özellikleri yer alır.

Tarayıcı, bir gruptaki en fazla bir uç noktaya rapor göndermek için elinden geleni yapar. Yük dağıtmak için uç noktalara weight atanabilir. Bu durumda her uç nokta, raporlama trafiğinin belirli bir kısmını alır. Uç noktalara yedek toplayıcılar ayarlamak için priority de atanabilir.

Yedek toplayıcılar yalnızca birincil toplayıcılara yüklemeler başarısız olduğunda denenir.

Örnek: https://backup.com/reports adresinde yedek toplayıcı oluşturun:

Report-To: {
             "group": "endpoint-1",
             "max_age": 10886400,
             "endpoints": [
               {"url": "https://example.com/reports", "priority": 1},
               {"url": "https://backup.com/reports", "priority": 2}
             ]
           }

Ağ Hatası Günlük Kaydını Ayarlama

Kurulum

NEL'yi kullanmak için Report-To başlığını, adlandırılmış grup kullanan bir toplayıcıyla ayarlayın:

Report-To: {
    ...
  }, {
    "group": "network-errors",
    "max_age": 2592000,
    "endpoints": [{
      "url": "https://analytics.provider.com/networkerrors"
    }]
  }

Ardından, hataları toplamaya başlamak için NEL yanıt üstbilgisini gönderin. NEL, bir kaynak için etkinleştirildiğinden başlığı yalnızca bir kez göndermeniz gerekir. Hem NEL hem de Report-To, aynı kaynağa yapılan gelecekteki istekler için geçerli olur ve toplayıcıyı ayarlamak için kullanılan max_age değerine göre hataları toplamaya devam eder.

Başlık değeri, max_age ve report_to alanı içeren bir JSON nesnesi olmalıdır. Ağ hataları toplayıcınızın grup adına referans vermek için ikincisini kullanın:

GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}

Alt kaynaklar

Örnek: example.com, foobar.com/cat.gif'ı yükler ve bu kaynak yüklenemezse:

• foobar.com'nin NEL toplayıcısı bilgilendirilir
• example.com'nin NEL toplayıcısı bildirilmez.

NEL'in, istemcide oluşturulan sunucu tarafı günlüklerini yeniden ürettiği genel bir kuraldır.

example.com, foobar.com'un sunucu günlüklerini göremediğinden NEL raporlarını da göremez.

Rapor yapılandırmalarında hata ayıklama

Sunucunuzda raporlar görünmüyorsa chrome://net-export/ adresine gidin. Bu sayfa, her şeyin doğru şekilde yapılandırıldığını ve raporların düzgün şekilde gönderildiğini doğrulamak için yararlıdır.

ReportingObserver ne olacak?

ReportingObserver, ilgili ancak farklı bir raporlama mekanizmasıdır. Bu veri, JavaScript çağrılarına dayanır. Ağ hataları JavaScript aracılığıyla yakalanamadığından ağ hatası günlüğe kaydetme için uygun değildir.

Örnek sunucu

Aşağıda, Express kullanan örnek bir Node sunucusu verilmiştir. Bu örnekte, ağ hataları için raporlamanın nasıl yapılandırılacağı gösterilmekte ve sonucu yakalamak üzere özel bir işleyici oluşturulmaktadır.

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}`);
});

Daha fazla bilgi

• Reporting API ile web uygulamanızı izleme (Reporting API'deki ana yayın)
• Reporting API v0'dan v1'e taşıma kılavuzu
• Özellik: eski Reporting API (v0)
• Özellik: yeni Reporting API (v1)