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

Maud Nalpas
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 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 uçuş 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.

Üstbilgi 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.

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 süresini saniye cinsinden tanımlayan negatif olmayan bir tamsayı. "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 nesnesi dizisi.
include_subdomains boolean İsteğe bağlı. Geçerli 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 olursa alt alan adları uç noktaya bildirilmez.

group adı, bir dizeyi 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ı, yedekleme ve yük dengeleme özelliklerini sağlayan bir dizidir. Acil durum planlaması ve yük dengeleme bölümünü inceleyin. 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 aralıklarla gruplandırır 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 çok uç noktayı 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"
             }]
           }

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 bu can sıkıcı konsol uyarılarının/hatalarının tümü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, 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ün dağıtılması için uç noktalara bir weight atanabilir. Her uç nokta, raporlama trafiğinin belirli bir kısmını alır. Yedek toplayıcılar ayarlamak için uç noktalara priority da atanabilir.

Yedek toplayıcılar yalnızca birincil toplayıcılara yapılan 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'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, 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