はじめに
ネットワーク エラー ロギング(NEL)は、オリジンからクライアントサイド ネットワーク エラーを収集するメカニズムです。
NEL
HTTP レスポンス ヘッダーを使用して、ネットワーク エラーを収集するようブラウザに指示し、Reporting API と統合してエラーをサーバーに報告します。
従来の Reporting API の概要
以前の Report-To
ヘッダー
以前の Reporting API を使用するには、Report-To
HTTP レスポンス ヘッダーを設定する必要があります。その値は、ブラウザがエラーを報告するエンドポイント グループを記述するオブジェクトです。
Report-To:
{
"max_age": 10886400,
"endpoints": [{
"url": "https://analytics.provider.com/browser-errors"
}]
}
エンドポイント URL がサイトとは異なるオリジンにある場合は、エンドポイントが CORS プリフライト リクエストをサポートしている必要があります。(例: 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
)。
この例では、メインページとともにこのレスポンス ヘッダーを送信すると、ブラウザが生成した警告をエンドポイント https://analytics.provider.com/browser-errors
に max_age
秒間報告するようにブラウザが構成されます。ページから後続で送信される HTTP リクエスト(画像やスクリプトなど)はすべて無視されます。構成は、メインページのレスポンス時に設定されます。
ヘッダー フィールドの説明
各エンドポイント構成には、group
名、max_age
、endpoints
配列が含まれています。include_subdomains
フィールドを使用して、エラーの報告時にサブドメインを考慮するかどうかを選択することもできます。
フィールド | タイプ | 説明 |
---|---|---|
group |
文字列 | 省略可。group 名が指定されていない場合、エンドポイントには「default」という名前が付けられます。 |
max_age |
数値 | 必須。エンドポイントの存続期間を秒単位で定義する正の整数。値が「0」の場合、エンドポイント グループはユーザー エージェントのレポート キャッシュから削除されます。 |
endpoints |
Array<Object> | 必須。レポート コレクタの実際の URL を指定する JSON オブジェクトの配列。 |
include_subdomains |
ブール値 | 省略可。現在のオリジンのホストのすべてのサブドメインでエンドポイント グループを有効にするブール値。省略されている場合や「true」以外の値が指定されている場合、サブドメインはエンドポイントに報告されません。 |
group
名は、文字列をエンドポイントに関連付けるために使用される一意の名前です。Reporting API と統合されている他の場所で、この名前を使用して特定のエンドポイント グループを参照します。
max-age
フィールドも必須で、ブラウザがエンドポイントを使用してエラーを報告する時間を指定します。
endpoints
フィールドは、フェイルオーバーとロード バランシング機能を提供する配列です。フェイルオーバーとロード バランシングのセクションをご覧ください。グループに endpoints
に複数のコレクタがリストされていても、ブラウザは 1 つのエンドポイントのみを選択することに注意してください。レポートを複数のサーバーに同時に送信する場合は、バックエンドでレポートを転送する必要があります。
ブラウザはどのようにレポートを送信しますか?
ブラウザは定期的にレポートをバッチ処理し、構成したレポート エンドポイントに送信します。
レポートを送信するために、ブラウザは Content-Type: application/reports+json
と、キャプチャされた警告/エラーの配列を含む本文を含む POST
リクエストを発行します。
ブラウザはいつレポートを送信しますか?
レポートはアプリからアウトオブバンドで配信されます。つまり、レポートがサーバーに送信されるタイミングはブラウザが制御します。
ブラウザは、キューに登録されたレポートを最も適切なタイミングで配信しようとします。これは、準備ができ次第(デベロッパーにタイムリーなフィードバックを提供する目的で)行うことができますが、優先度の高い処理でブラウザがビジー状態になっている場合や、ユーザーが遅いネットワークや輻輳しているネットワークを使用している場合は、ブラウザが配信を遅らせることもあります。また、ユーザーが頻繁にアクセスしている場合は、特定のオリジンに関するレポートを優先して送信することもあります。
Reporting API を使用する場合、パフォーマンスに関する懸念事項(アプリとのネットワーク競合など)はほとんどありません。また、ブラウザがキューに登録されたレポートを送信するタイミングを制御する方法もありません。
複数のエンドポイントの構成
1 つのレスポンスで、複数の Report-To
ヘッダーを送信して複数のエンドポイントを同時に構成できます。
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"
}]
}
または、複数のヘッダーを 1 つの HTTP ヘッダーにまとめることもできます。
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
ヘッダーを送信すると、ブラウザは max_age
値に従ってエンドポイントをキャッシュに保存し、厄介なコンソール アラートやエラーをすべて URL に送信します。
フェイルオーバーとロード バランシング
ほとんどの場合、グループごとに 1 つの URL コレクタを構成します。ただし、レポートにより大量のトラフィックが生成される可能性があるため、この仕様には DNS SRV レコードを参考にしたフェイルオーバー機能とロード バランシング機能が含まれています。
ブラウザは、グループ内の最大 1 つのエンドポイントにレポートを配信するよう最善を尽くします。エンドポイントに weight
を割り当てて負荷を分散し、各エンドポイントがレポート トラフィックの特定の割合を受信できます。エンドポイントに priority
を割り当てて、フォールバック コレクタを設定することもできます。
フォールバック コレクタは、プライマリ コレクタへのアップロードが失敗した場合にのみ試行されます。
例: https://backup.com/reports
に代替コレクタを作成します。
Report-To: {
"group": "endpoint-1",
"max_age": 10886400,
"endpoints": [
{"url": "https://example.com/reports", "priority": 1},
{"url": "https://backup.com/reports", "priority": 2}
]
}
ネットワーク エラー ロギングの設定
セットアップ
NEL を使用するには、名前付きグループを使用するコレクタで Report-To
ヘッダーを設定します。
Report-To: {
...
}, {
"group": "network-errors",
"max_age": 2592000,
"endpoints": [{
"url": "https://analytics.provider.com/networkerrors"
}]
}
次に、NEL
レスポンス ヘッダーを送信してエラーの収集を開始します。NEL はオリジンでオプトインするため、ヘッダーを送信する必要があるのは 1 回だけです。NEL
と Report-To
は、同じ送信元への今後のリクエストに適用され、コレクタの設定に使用された max_age
値に従ってエラーの収集が継続されます。
ヘッダー値は、max_age
フィールドと report_to
フィールドを含む JSON オブジェクトである必要があります。後者は、ネットワーク エラー コレクタのグループ名を参照するために使用します。
GET /index.html HTTP/1.1
NEL: {"report_to": "network-errors", "max_age": 2592000}
サブリソース
例: example.com
が foobar.com/cat.gif
を読み込み、そのリソースの読み込みに失敗した場合:
foobar.com
の NEL コレクタに通知が届くexample.com
の NEL コレクタに通知されません
NEL は、クライアントで生成されたサーバーサイド ログを再現します。
example.com
には foobar.com
のサーバーログは表示されないため、NEL レポートも表示されません。
レポート構成のデバッグ
サーバーにレポートが表示されない場合は、chrome://net-export/
に移動してください。このページは、設定が正しく行われ、レポートが適切に送信されていることを確認するのに役立ちます。
ReportingObserver はどうですか?
ReportingObserver
は関連するが異なる報告メカニズムです。JavaScript 呼び出しに基づいています。ネットワーク エラーは JavaScript でインターセプトできないため、ネットワーク エラーのロギングには適していません。
サーバー例
以下に、Express を使用する Node サーバーの例を示します。ネットワーク エラーのレポートを構成する方法を示し、結果をキャプチャする専用のハンドラを作成します。
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}`);
});