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

Maud Nalpas

Giriş

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

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

Eski Reporting API'ye genel bakış

Eski Reporting API'yi kullanmak için Report-To HTTP yanıt başlığını ayarlamanız gerekir. Değeri, tarayıcının hataları bildireceği bir uç nokta grubunu açıklayan 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 başlığının 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. include_subdomains alanını kullanarak hataları bildirirken alt alan adlarının dikkate alınıp alınmayacağını da seçebilirsiniz.

Alan Tür Açıklama
group dize İsteğe bağlı. group adı belirtilmezse uç noktaya "varsayılan" adı verilir.
max_age sayı Zorunludur. Uç noktanın kullanım ömrünü saniye cinsinden tanımlayan negatif olmayan bir tam sayı. "0" değeri, uç nokta grubunun kullanıcı aracısının raporlama önbelleğinden kaldırılmasına neden olur.
endpoints Array<Object> Zorunludur. Rapor toplayıcınızın gerçek URL'sini belirten bir JSON nesneleri dizisi.
include_subdomains boolean İsteğe bağlı. Mevcut kaynağın ana makinesinin tüm alt alan adları için uç nokta grubunu etkinleştiren bir boole değeri. Atlanırsa veya "true" dışında bir değer girilirse alt alanlar uç noktaya bildirilmez.

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 bu adı, Reporting API ile entegre olan diğer yerlerde kullanın.

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

endpoints alanı, yük devretme ve yük dengeleme özellikleri sağlayan bir dizidir. Yedek devretme ve yük dengeleme bölümüne bakın. Grupta endpoints içinde birden fazla toplayıcı listelense bile tarayıcının yalnızca bir uç nokta seçeceğini unutmayın. Bir raporu aynı anda birden fazla sunucuya göndermek istiyorsanız arka uçunuzun raporları yönlendirmesi gerekir.

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

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

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

Tarayıcı ne zaman rapor gönderir?

Raporlar, uygulamanızın dışında bir bant üzerinden gönderilir. Bu nedenle, raporların sunucularınıza ne zaman gönderileceğini tarayıcı kontrol eder.

Tarayıcı, sıraya alınmış raporları en uygun zamanda teslim etmeye çalışır. Bu, geliştiriciye zamanında geri bildirim sağlamak için kullanıcı hazır olduğunda hemen yapılabilir. Ancak tarayıcı, daha yüksek öncelikli işleri işlemekle meşgulse veya kullanıcı o sırada yavaş ve/veya yoğun bir ağ kullanıyorsa teslimatı geciktirebilir. Tarayıcı, kullanıcı sık ziyaret eden bir kullanıcıysa belirli bir kaynakla ilgili raporların önce gönderilmesine de öncelik verebilir.

Raporlama API'si kullanılırken performansla ilgili çok az endişe vardır veya hiç endişe yoktur (ör. uygulamanızla ağ çekişmesi). Tarayıcının, sıraya alınmış raporları ne zaman göndereceğini kontrol etmenin de bir yolu yoktur.

Birden çok uç noktayı yapılandırma

Tek bir yanıt, birden fazla Report-To üstbilgisi göndererek aynı anda çeşitli uç noktaları 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"
             }]
           }

veya bunları tek bir HTTP üstbilgisinde birleştirerek:

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 tüm bu kötü konsol uyarılarını/hatalarını URL'lerinize gönderir.

Yük devretme ve yük dengeleme

Çoğu zaman grup başına bir URL toplayıcı yapılandırırsınız. Ancak raporlama önemli ölçüde trafik oluşturabileceğinden spesifikasyon, DNS SRV kaydından esinlenerek oluşturulmuş yük devretme ve yük dengeleme özelliklerini içerir.

Tarayıcı, bir grupta en fazla bir uç noktaya rapor göndermek için elinden geleni yapar. Yükü dağıtmak için uç noktalara weight atanabilir. Her uç nokta, raporlama trafiğinin belirli bir bölümünü alır. Uç noktalara, yedek toplayıcılar ayarlamak için priority da atanabilir.

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

Örnek: https://backup.com/reports adresinde yedek bir 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ı kaydını ayarlama

Kurulum

NEL'i kullanmak için Report-To üstbilgisini adlandırılmış bir 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 başlığını gönderin. NEL, kaynak için etkinleştirme gerektirdiğ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 alanlarını 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 öğesini yüklüyorsa ve bu kaynak yüklenemiyorsa:

  • foobar.com kullanıcısının NEL toplayıcısı bilgilendirilir.
  • example.com adlı kullanıcının NEL toplayıcısına bildirim gönderilmez.

Genel olarak NEL, sunucu tarafı günlüklerini istemcide oluşturulmuş şekilde yeniden üretir.

example.com, foobar.com'nin sunucu günlüklerini göremediği için NEL raporlarını da göremez.

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

Sunucunuzda raporların gösterilmediğini görüyorsanız 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 hakkında

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

Örnek sunucu

Aşağıda, Express kullanan bir örnek düğüm sunucusu verilmiştir. Ağ hataları için raporlamanın nasıl yapılandırılacağını gösterir ve sonucu yakalamak için özel bir işleyici oluşturur.

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