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

Eric Bidelman

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ı bildirmek 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 Report-To Başlığı

Eski Reporting API'yi kullanmak için Report-To HTTP yanıt başlığı ayarlamanız gerekir. Bu dizenin değeri, tarayıcının hataları bildirmesi için 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).

Bu örnekte, ana sayfanızla birlikte bu yanıt üst bilgisini gönderdiğinizde, tarayıcı 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ılı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. Bu adı, belirli bir uç nokta grubuna referans vermek için Reporting API ile entegre olan diğer yerlerde kullanın.

max-age alanı da gereklidir ve tarayıcının uç noktasını ne kadar süre kullanacağını ve hataları buna ne kadar süre 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. Grupta endpoints içinde birden fazla toplayıcı listeleniyor olsa bile tarayıcının yalnızca bir uç nokta seçeceğini unutmayın. Aynı anda birkaç sunucuya rapor göndermek istiyorsanız arka ucunuzun raporları yönlendirmesi 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ı, raporları göndermek için Content-Type: application/reports+json ile bir POST isteği ve yakalanan uyarı/hata dizisini içeren bir gövde metni gönderir.

Tarayıcı, raporları ne zaman gönderir?

Raporlar, uygulamanızdan bant dışında dağıtılı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 iletmeye çalışır. Bu, hazır olduğunda (geliştiriciye zamanında geri bildirim sağlamak için) hemen gelebilir ancak tarayıcı daha yüksek öncelikli işleri yapmakla meşgulse veya kullanıcı o sırada yavaş ve/veya sıkışık bir ağdaysa teslimi geciktirebilir. Kullanıcı sık sık ziyaret ediyorsa tarayıcı önce belirli bir kaynakla ilgili raporlar göndermeye de öncelik verebilir.

Reporting API'yi kullanırken performansla ilgili çok az sorun (ör. uygulamanızın ağ çakışması) olur veya hiç yoktur. Ayrıca, tarayıcının sıraya alınmış raporları ne zaman göndereceğini kontrol etmenin bir yolu da yoktur.

Birden fazla uç nokta 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"
             }]
           }

tek bir HTTP başlığında birleştirmeniz yeterlidir:

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öndermenizin ardından tarayıcı, uç noktaları max_age değerlerine göre önbelleğe alır ve tüm bu tehlikeli konsol uyarılarını/hatalarını URL'lerinize gönderir.

Yük devretme ve yük dengeleme

Çoğu zaman, her grup için tek bir URL toplayıcı yapılandırırsınız. Bununla birlikte, raporlama önemli ölçüde trafik oluşturabileceği için bu spesifikasyon, DNS SRV kaydından esinlenen yük devretme ve yük dengeleme özellikleri 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 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 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ü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"
    }]
  }

Sonra, hataları toplamaya başlamak için NEL yanıt başlığını gönderin. Bir kaynak için NEL etkinleştirildiğinden başlığı yalnızca bir kez göndermeniz gerekir. Hem NEL hem de Report-To, aynı kaynağa yapılacak 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ını içeren bir JSON nesnesi olmalıdır. Ağ hataları toplayıcınızın grup adına referans vermek için ikinci adı 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ükler ve bu kaynak yüklenemezse:

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

Genel kural olarak NEL, istemcide kısa süre önce oluşturulan sunucu tarafı günlükleri yeniden oluşturur.

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

Hata ayıklama raporu yapılandırmaları

Sunucunuzda rapor gösterilmiyorsa chrome://net-export/ adresine gidin. Bu sayfa, öğelerin doğru şekilde yapılandırıldığını ve raporların düzgün şekilde gönderildiğini doğrulamak açısından kullanışlıdır.

ReportingObserver ile ilgili durum nedir?

ReportingObserver alakalı ancak farklı bir bildirme mekanizmasıdır. JavaScript çağrılarına dayanır. Ağ hatalarına JavaScript aracılığıyla müdahale edilemediğinden ağ hatalarını günlük kaydı 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

• Web uygulamanızı Reporting API ile izleme (Reporting API'deki ana yayın)
• Reporting API v0'dan v1'e geçiş rehberi
• Spesifikasyon: eski Reporting API (v0)
• Spesifikasyon: yeni Reporting API (v1)