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

Eric Bidelman

Maud Nalpas

Giriş

Ağ Hatası Günlük Kaydı (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 üzere Reporting API ile entegre olur.

Eski Reporting API'ye genel bakış

Eski Report-To Başlığı

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 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 üstbilgisini ana sayfanızla göndermek, 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.

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

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

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 zorunludur ve tarayıcının uç noktayı ne kadar süreyle kullanması ve hataları ona bildirmesi gerektiğini belirtir.

endpoints alanı, yük devretme ve yük dengeleme özellikleri sağlamak için kullanılan bir dizidir. Yük devretme ve yük dengeleme bölümüne 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 birkaç sunucuya göndermek istiyorsanız arka ucunuzun, raporları yönlendirmesi gerekir.

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

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

Rapor göndermek için tarayıcı, 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 teslim edilir. 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 teslim etmeye çalışır. Bu, geliştiriciye zamanında geri bildirim sağlamak için, hazır oldukları anda gerçekleştirilebilir, ancak tarayıcı daha yüksek öncelikli bir işi yapmakla meşgulse ya da kullanıcı o sırada yavaş ve/veya kalabalık bir ağda bulunuyorsa yayını geciktirebilir. Kullanıcı sık ziyaret eden bir kullanıcıysa tarayıcı, ilk olarak belirli bir kaynakla ilgili raporları göndermeye öncelik verebilir.

Reporting API'yi kullanırken performansla ilgili neredeyse hiç endişe yoktur (ör. uygulamanızla ağ uyuşmazlığı). 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 üst bilgisi 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 başlığında birleştirebilirsiniz:

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 üst bilgisini göndermenizden sonra, tarayıcı max_age değerlerine göre uç noktaları önbelleğe alır ve tüm bu rahatsız edici konsol uyarılarını/hatalarını URL'lerinize gönderir.

Yük devretme ve yük dengeleme

Çoğunlukla grup başına bir URL toplayıcı yapılandırırsınız. Ancak raporlama yüksek miktarda trafik oluşturabileceğinden bu spesifikasyon, DNS SRV kaydından esinlenen yük devretme ve yük dengeleme özelliklerini içerir.

Tarayıcı, gruptaki en fazla bir uç noktaya rapor göndermek için elinden geleni yapar. Uç noktalara, yükü dağıtmak için bir weight atanabilir. Her uç nokta, raporlama trafiğinin belirli bir bölümünü alır. Uç noktalara da yedek toplayıcı ayarlamak için bir priority 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 üstbilgisini, 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 başlığını gönderin. NEL, bir kaynak için kaydolduğundan başlığı yalnızca bir kez göndermeniz gerekir. Hem NEL hem de Report-To, aynı kaynağa gelecekte yapılacak istekler için geçerli olur ve toplayıcıyı ayarlamak için kullanılan max_age değerine göre hata 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 ikinci kodu 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 hizmetini yüklerse ve bu kaynak yüklenemezse:

• 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önderilmedi

Genel kural, NEL'in istemcide oluşturulan sunucu tarafı günlükleri yeniden üretmesidir.

example.com, foobar.com sunucu günlüklerinde görünür olmadığından NEL raporlarını da göremez.

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

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

ReportingObserver'da durum nedir?

ReportingObserver, konuyla 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ğ hatası günlük kaydı için uygun değildir.

Örnek sunucu

Aşağıda, Express kullanan bir düğüm sunucusu örneği verilmiştir. Bu uzantı, 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

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