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

Maud Nalpas

Giriş

Ağ Hatası Günlüğü (NEL), bir kaynaktan istemci tarafı ağ hatalarını toplamak için kullanılan bir mekanizmadır.

Tarayıcıya ağ hatalarını toplamasını söylemek 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ığı 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ıyı, 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) yok sayıldığını unutmayın. Yapılandırma, ana sayfanın yanıtı sırasında ayarlanır.

Üstbilgi alanlarının açıklaması

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

Alan Tür Açıklama
group dize İsteğe bağlıdır. group adı belirtilmezse uç noktaya "default" 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 Dizi<Nesne> Zorunludur. Rapor toplayıcınızın gerçek URL'sini belirten bir JSON nesneleri dizisi.
include_subdomains boole İsteğe bağlıdır. 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 alan adları uç noktaya bildirilmez.

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

max-age alanı da zorunludur ve tarayıcının uç noktayı ne kadar süre kullanması ve hataları bu uç noktaya bildirmesi gerektiğini belirtir.

endpoints alanı, yük devretme ve yük dengeleme özellikleri 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ı listelese 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 ucunuzun 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.

Rapor göndermek için tarayıcı, POST ile bir Content-Type: application/reports+json isteği ve yakalanan uyarı/hata dizisini içeren bir gövde yayınlar.

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ınan raporları en uygun zamanda göndermeye çalışır. Bu işlem, hazır oldukları anda (geliştiriciye zamanında geri bildirim sağlamak için) 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ğdaysa teslimatı geciktirebilir. Tarayıcı, kullanıcı sık ziyaret ediyorsa belirli bir kaynakla ilgili raporları öncelikli olarak gönderebilir.

Reporting API kullanılırken performansla ilgili endişeler (ör. uygulamanızla ağ çekişmesi) çok azdır veya hiç yoktur. Ayrıca, tarayıcının sıraya alınmış raporları ne zaman göndereceğini kontrol etmenin bir yolu yoktur.

Birden fazla uç noktayı yapılandırma

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

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 can sıkıcı 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 çok fazla trafik oluşturabileceğinden spesifikasyon, DNS SRV kaydından esinlenen yük devretme ve yük dengeleme özelliklerini içerir.

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 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 bir 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üğe Kaydetme'yi ayarlama

Kurulum

NEL'i kullanmak için Report-To başlığını, 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, hata toplamaya başlamak için NEL yanıt başlığını gönderin. NEL, bir kaynak için etkinleştirildiğinden başlığı yalnızca bir kez göndermeniz yeterlidir. Hem NEL hem de Report-To, aynı kaynağa yönelik gelecekteki isteklere uygulanır ve toplayıcıyı ayarlamak için kullanılan max_age değerine göre hata toplamaya devam eder.

Üstbilgi 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 kaynağını yüklüyorsa ve bu kaynak yüklenemiyorsa:

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

Genel kural, NEL'in sunucu tarafı günlüklerini yeniden oluşturmasıdır. Bu günlükler, istemci tarafında oluşturulur.

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

Hata ayıklama raporu yapılandırmaları

Sunucunuzda rapor görmüyorsanız chrome://net-export/ adresine gidin. Bu sayfa, yapılandırmanın doğru yapıldığını ve raporların düzgün şekilde gönderildiğini doğrulamak için kullanışlıdır.

ReportingObserver hakkında ne düşünüyorsunuz?

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

Örnek sunucu

Aşağıda, Express kullanan örnek bir Node 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