コンテンツにスキップ

このページは英語のページを機械翻訳したものです。内容は英語のページが正です。 英語のページを読む

エラーの報告

サーバーが自身のバグや障害をどのように知らせるか、各プラットフォームでその報告をどこで読むか、そして報告をエラートラッカーに送る方法を説明します。 メトリクスは何かがおかしいことを教えてくれます。エラーの報告は、何が失敗したのかをスタックとともに教えてくれます。すべての設定は設定リファレンスにあります。

何を設定していても、すべての報告に次の 3 つのことが起こります。

  1. スタックを含む error report の行が 1 行、標準エラー出力に出ます(ログの行)。
  2. 報告はデータベースのエラーグループに数えられます。管理画面にグループが表示され、manage_errors の権限を持つ人には、新しいグループと再発したグループが通知されます(エラーグループと通知)。
  3. errors_exporter を設定すると、報告は外部のサービスにも送られます(報告をサービスに送る)。

errors_exporter を設定しない限り、サーバーの外には何も出ていきません。

報告されるもの 報告されないもの(メトリクスとほかのログの行で分かります)
HTTP ハンドラー、ジョブ、バックグラウンドタスクでのパニック 4xx の応答(不正な入力、認可、レート制限)とメンテナンスモード
クライアント API、管理 API、サインインのページ、ActivityPub、OAuth、メディアが 5xx を返した原因のエラー クライアントが接続を切ったリクエスト
最終的に失敗したジョブ(dead) ジョブの再試行。再試行を使い切ったときに報告されます
起動の失敗: 不正な設定、またはセットアップできないデータベースやアダプター 失敗したレディネスチェック
Web クライアントが処理しなかったエラー。ブラウザーからサーバーに送られます ほかのサーバーが原因の失敗: 配送の再試行と断念、拒否された署名、失敗したリモートの取得
ブラウザー自身のノイズ: 切れたネットワーク、ブラウザー拡張機能からのエラー、新しいデプロイで消えたチャンク

外部サービス(メール、ストレージ、決済、音声)の障害は、それによってジョブが最終的に失敗したか、リクエストが 5xx を返したときにだけ報告されます。一時的な障害は、代わりに my.adapter.* のメトリクスに表れます(サーバーの運用)。

バックグラウンドタスクでのパニックは、報告されたあとにプロセスを停止させます。そのため、サーバーが壊れた状態のまま動き続けることはありません。プロセスはプラットフォームが再起動します。

この行は msg が error report、level が ERROR です(障害がプロセスを停止させるときは severity が CRITICAL になります)。 そのフィールドと、スクラブがそれらに何をするかは、サーバーの運用にあります。要点は次のとおりです。

  • my.error.fingerprint は、同じエラーならどの発生でも同じ値です。これで検索したり、まとめたりしてください。
  • my.error.where は発生した場所を示します。たとえば client_api GET /api/v1/statuses/{id} です。
  • request_id、job_id、trace_id、span_id で、同じリクエストやジョブのほかの行を見つけられます。
  • リクエストのエラーの行には context.httpRequest があり、メソッド、URL としてのルート (/api/v1/statuses/{id} で、クライアントが要求したパスではありません)、応答したステータスが入ります。Error Reporting はこれらをグループに表示し、絞り込みにも使えます。
  • message は行の最後にあり、エラーの型とメッセージ、改行、Go のスタックが入ります。
  • スタックは、エラーが報告された場所ではなく、エラーの出どころから始まります。データベースのエラーなら、クエリを実行したサーバーの関数です。そのため、出どころの異なるエラーは、Error Reporting でも管理画面でも別のグループになります。

スタックを含む行はほかにありません。

Cloud Error Reporting は、何も設定しなくてもこの行を読み取り、コンソールの Error Reporting にエラーを一覧表示します。無料で、料金がかかるのは Cloud Logging だけです。

  • エラーは型とスタックの上位のフレームでまとめられます。サーバーのフィンガープリントは使えないため、Error Reporting のグループが管理画面のグループと異なることがあります。
  • グループは 30 日間保持され、新しいエラーと、解決済みのエラーが再発したときに通知されます。通知はプロジェクト全体で 1 時間に最大 20 件です。通知チャネルは Google Cloud コンソールで設定してください。
  • 報告の前後に何が起きたかを調べるには、Cloud Logging で jsonPayload."request_id"="<id>"、または同じ形で trace_id を検索します。

OpenTofu のモジュール mycroblog-gcp では、observability セクションが既定で報告をここに送ります(errors = "error-reporting")。Error Reporting API を有効にし、errors_exporter は none のままにします。

CloudWatch Logs は、この行をただの JSON として読み取ります。

  • ロググループのログ異常検出をオンにしてください。これまでに見たことのない行のパターンを検出し、SNS にアラームを送れます。読み取るのは行の先頭 1,500 文字だけで、message が最後のフィールドになっているのはこのためです。解決済みの状態は保持しません。
  • 報告を数えるには、{ $.msg = "error report" } のようなメトリクスフィルターを作ります。my.error.fingerprint から取ったディメンションは使わないでください。ディメンションの値ごとに、それぞれ別のメトリクスとして課金されます。my.error.source と my.error.kind は問題ありません。
  • 前後の状況は Logs Insights で調べます: filter `request_id` = "<id>"。

OpenTofu のモジュール mycroblog-aws では、observability セクションが既定で報告を CloudWatch Logs に保持し(errors = "cloudwatch")、errors_exporter は none のままにします。ログ異常検出は、あなたが行う手順のままです。

行はコンテナのログから読みます: docker compose logs my | jq -c 'select(.msg == "error report")'。 metrics_exporter = prometheus のときは、報告が急に増えるとアラート MyErrorReportsIncreasing(アラートと対応手順)が警告します。その元になるカウンターは my.errors.reported です。 外部のサービスを必要としない通知には、管理画面と後述の Webhook を使ってください。トラッカーを使うなら errors_exporter を使います。

サーバーは報告をフィンガープリントごとにデータベースで数えます。設定も追加のサービスも不要で、書き込みもわずかです。あるフィンガープリントの最初の報告はすぐに書き込まれ、その後の報告はメモリー上で合計されて 1 分に 1 回書き込まれます。プロセスを強制終了すると直近 1 分間の件数が失われることがありますが、ログの行はそれで失われることはありません。 90 日より古い件数は毎日削除されます。失敗したのがデータベースそのものであれば、報告はログの行にだけ残ります。

ロールに manage_errors がある人(組み込みの admin ロールにはあります)には、管理メニューに「エラー」(/admin/errors)が表示されます。

  • 一覧にはグループが表示され、既定では未解決のものが、最後に見られた順に並びます。状態(未解決、解決済み、ミュート中、すべての状態)と発生元(サーバー、Web クライアント)で絞り込めます。各行には、メッセージの最初の行、発生した場所、直近 24 時間と 7 日間の件数、最後に見られた日時、状態が表示されます。
  • グループのページは、その状態でできる操作から始まります(未解決のグループには「解決にする」と「ミュート」、解決済みのグループには「ミュート」、ミュート中のグループには「ミュートを解除」)。続いて、グループの事実(場所、メッセージ、最初と最後の日時とバージョン、フィンガープリント)、直近 24 時間と 7 日間の件数、最新の発生(日時、バージョン、プロセスのロール、型、リクエスト ID とトレース ID、スタック)、直近 90 日間の 1 時間ごとの発生件数(新しい順)、状態の変更履歴が表示されます。フィンガープリント、リクエスト ID、トレース ID、スタックには「コピー」ボタンがあるので、ID をログの検索に貼り付けてください。
  • 「解決にする」は、修正したエラーに使います。別のバージョンのサーバーで再発すると、グループは再び開いて、もう一度通知します。解決したときのバージョンで同じエラーが起きても数えられるだけなので、古いバージョンに残った最後のリクエストでグループが再び開くことはありません。
  • 「ミュート」は件数を数え続けますが、通知も Webhook のイベントも送りません。「ミュートを解除」でグループは再び開きます。

同じ操作は GET /api/v1/admin/error_groups と POST /api/v1/admin/error_groups/{id}/resolve(/mute、/unmute)でも行えます。

  • manage_errors を持つ人は、新しいエラーグループと再発のときに通知 admin_error_group を受け取ります。通知はサーバー全体で 1 時間に最大 10 件で、その時間の残りは、さらにエラーが報告されたことを伝える 1 件の通知にまとめられます。メールでも受け取れます(モデレーション)。
  • Webhook のイベント error_group.created と error_group.regressed は同じグループを運ぶので、Slack や Discord、自動化ツールに送れます(サーバーの Webhook、Webhook リファレンス)。Webhook には manage_webhooks が、イベントには manage_errors が必要です。
  • ミュートしたグループが通知することはありません。

Web クライアントは、画面が処理しなかったエラーを自分のサーバーの POST /api/v1/client_errors に送ります。そのため第三者に見られることはなく、コンテンツセキュリティの設定も変わりません。サーバーはすべてに 204 を返し、受け付けないものは捨てます。受け付けないのは、16 KiB を超える本文、自分の Web クライアントのファイルを含まないスタック、1 つの IP アドレスから 1 分間に 10 件を超える報告です。同じエラーはページの表示ごとに 1 回だけ送られ、ページの表示ごとに最大 20 件です。 サインインしたセッションなしに送られた報告は、数えられてログに記録されますが、それだけでは誰にも通知しません。そのため、匿名のスクリプトが受信箱を埋め尽くすことはできません。サインインしている人のブラウザーも同じエラーを報告すると、グループが通知します。 スタックはミニファイされたビルドのもので、ソースには戻されません。まずルートとメッセージを読んでください。リリースは、そのページを配信したサーバーのバージョンです。オフラインで開いたページや、3 秒待っても応答がなかったページはブラウザーのコピーから表示され、ブラウザーが Web クライアントを保存したときのバージョンを名乗ります。つまり、Web クライアントが同じ、より古いバージョンです。

Web クライアントは、応答の速さの標本を、エラーと同じように自分のサーバーの POST /api/v1/client_measurements に送ります。送るのは、ルートごとの画面が表示されるまでの時間(LCP)と操作に応答するまでの時間(INP)、長いフレーム、種類ごとの各ナビゲーション、ID(post.reply)ごとの各操作、そして音声通話の往復時間、ジッター、パケット損失です。標本に含まれるのはルート、種類、操作、通話のトランスポートの名前だけで、アカウント、アドレス、URL は含みません。サーバーはすべてに 204 を返し、1 つの IP アドレスからは 1 分に最大 10 件のリクエストを受け付けます。 サーバーは標本を 1 時間ごとにデータベースで数え、1 分に 1 回書き込み、30 日後に削除します。GET /api/v1/admin/ux_measurements(manage_errors)は、直近 24 時間(hours で最大 720 まで)を合計し、名前ごとに 75 パーセンタイルを返します。メトリクス my.ux.duration と my.ux.call.packet_loss は同じ標本を書き出します(メトリクス)。種類ごとに、プロセスの中で最初の 200 件の名前を保持し、それ以降のものは other として数えます。 既定ではオフで、インスタンス設定 ux_measurement でオンにします。オフの間、サーバーは標本を取りません(インスタンス設定)。オンの間に標本を送るのはブラウザーのセッションの一部だけで、ux_measurement_share で別の値を設定しない限り 10 % です。セッションは Web クライアントの起動時に 1 回だけ抽選されます。

ロールに manage_errors がある人には、管理メニューに「UX の計測」(/admin/ux-measurements)が表示されます。直近 24 時間、7 日間、30 日間から選びます。標本のある指標ごとに、名前の表があり、標本数と 75 パーセンタイルが表示されます。LCP と INP では、良好な標本と不良な標本の割合(LCP は 2.5 秒以内と 4 秒超、INP は 200 ミリ秒以内と 500 ミリ秒超)も表示され、75 パーセンタイルが良好のしきい値を超えているものには印が付きます。表の下の「Web クライアントを計測する」は設定 ux_measurement で、ロールに manage_settings もある人だけがここで変更でき、専用の「保存」ボタンがあります。

errors_exporter を設定すると、各報告をエラートラッカーにも送ります。ログの行とデータベースのグループはそのまま残ります。報告は 1 回だけ送られ、再試行されることはなく、サービスを待つ処理もありません。

値 送り先
none(既定) どこにも送らない
sentry errors_sentry_dsn にある Sentry 互換の任意のサービス
otlp OpenTelemetry のコレクターまたはバックエンド。ログレコードとして送ります

errors_environment(既定は production)は、すべての報告にデプロイメントの名前を付けます。たとえば staging です。

どちらのエクスポーターも、ログの行と同じスクラブ済みのフィールドを、フィンガープリントとトレース ID・スパン ID とともに送ります。ホストについての情報は何も送りません。ホスト名、IP アドレス、ユーザー、リクエストの本文、ヘッダー、Cookie は含まれません。

サーバーは、サービスに大量の報告が押し寄せないよう、送る量を制限します。

  • 同じフィンガープリントはプロセスごとに 1 分に最大 1 回、すべての報告を合わせて 1 分に最大 60 件まで送ります。残りはログとグループに残ります。
  • 送信を待つ報告は最大 1,000 件です。キューがいっぱいのときに来た報告は捨てられます。サーバーが停止するときは、キューが空になるまで最大 2 秒待ちます。
  • サービスが 429 を返したり、速度を落とすよう求めたりしたとき(Retry-After、X-Sentry-Rate-Limits)は、サーバーはその間送信を止めます。
  • DSN のキーと報告がほかの場所に渡らないよう、サーバーはサービスからのリダイレクトに従いません。リダイレクトは failed として数えられます。サービスが表示する DSN を使ってください。その DSN は受け付け口そのものを指しています。

カウンター my.errors.exported を監視してください。my.outcome は success、dropped(制限を超えた、キューがいっぱいだった、またはサービスが速度を落とすよう求めた)、failed(サービスに到達できなかった、またはサービスが報告を拒否した)のいずれかです(サーバーの運用)。

ターミナルウィンドウ
MY_ERRORS_EXPORTER=sentry
MY_ERRORS_SENTRY_DSN_FILE=/run/secrets/sentry_dsn # or MY_ERRORS_SENTRY_DSN; the DSN is a secret

OpenTofu のモジュールでは、observability セクションのエラーは設定に任せます。モジュールは DSN のシークレットを作るので、あなたが値を入れてください。出力 secrets_to_fill にそれが挙げられます。

observability = { errors = "settings" }
settings = { errors_exporter = "sentry" }
secrets = ["errors_sentry_dsn"]

サーバーは Sentry のプロトコルを自分で話すので、Sentry SDK は使われず、SENTRY_* の環境変数も読みません。サーバーはフィンガープリントを設定するので、サービスはそれでまとめます。また、タグ service(my)、my.role、my.error.where、error.fingerprint を設定します。リリースはサーバーのバージョンで、環境は errors_environment です。

  • Sentry(ホスト型またはセルフホスト): プロジェクトのクライアントキーから DSN をコピーします。
  • GlitchTip: プロジェクトの DSN をコピーします。オープンソースで、小さなサーバーで動きます。新しい issue と再発した issue に対して、お使いのバージョンがどのアラートルールを提供しているか確認してください。
  • Datadog Error Tracking: お使いの Datadog サイトの Sentry DSN、https://<DD_API_KEY>@sentry-intake.<DD_SITE>/1 を使います。Datadog には service タグが必要ですが、サーバーは常にこれを設定します。Datadog はこれらのイベントをログとして保存し、Error Tracking でまとめます。代わりにエージェントやフォワーダーでログの行を Datadog に送る場合(Error Tracking for Logs)、スタックは message に入っています。ログパイプラインでこれを error.stack に割り当ててください。そうしないと Datadog はこれをスタックとして認識しません。sentry のエクスポーターには、このような割り当ては必要ありません。
ターミナルウィンドウ
MY_ERRORS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector:4318 # or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer%20...

各報告は exception という名前の OpenTelemetry のログレコードで、重大度 ERROR(プロセスを停止させるときは FATAL)、exception.type、exception.message、exception.stacktrace、my.error.fingerprint、my.error.where、my.error.source、my.error.kind、トレース ID とスパン ID を持ちます。メトリクスやトレースと同じリソースで、OTLP/HTTP(protobuf、gzip)で送られます。

これらのレコードがまとめられたエラーになるかどうかはバックエンドによります。トレースのデータだけからエラーの画面を作るバックエンドもあり、Datadog には error.stack が必要です。Sentry、GlitchTip、Datadog には sentry を使ってください。ほかのログと並べてレコードを置きたいときに otlp を使います。

スクラブが保証すること、しないこと

Section titled “スクラブが保証すること、しないこと”

スクラブは報告が作られるときに 1 回だけ行われます。そのため、ログの行、データベース、すべてのエクスポーターが受け取るのはスクラブ済みのテキストだけです。

  • メッセージの中の URL、メールアドレス、@user@host 形式のハンドル、IP アドレス、UUID と ULID、10 桁以上の数字は、それぞれ <url>、<email>、<acct>、<ip>、<id>、<n> に置き換えられ、メッセージは 1 KiB に切り詰められます。
  • スタックの中の関数の引数の値は (...) に置き換えられ、スタックは 16 KiB に切り詰められます。ファイルの位置はソースツリーからの相対パスで残るので、ビルドしたマシンのパスは表れません。
  • どの報告にも、リクエストの本文、ヘッダー、クエリー、Cookie、アカウント ID、ユーザー名、IP アドレス、User-Agent は含まれません。

スクラブはパターンに一致するものを置き換えるだけなので、メッセージに個人データが含まれないことは保証しません。エラーメッセージが引用した名前、自由記述のテキスト、10 桁未満の数字は残ることがあります。通常の http request と job の行の error フィールドは、このようにはスクラブされません。ログとエラートラッカーは、ユーザーのコンテンツの断片を含むかもしれない場所として扱い、ほかのログと同じアクセス制御と保持期間を適用してください。errors_exporter を設定したら、報告にはそのサービスの保存場所、保持期間、アクセスのルールが適用されます。

LLM とコーディングエージェント向け:llms.txt,llms-full.txt, llms-small.txt

このサイトのアクセス解析