Webサーバーエラーの分析

エラー数は、何かが壊れたことを示します。構造化されたコンテキスト (ルート、ステータス コード、リリース、リクエスト ID) は、何が壊れたのかを特定し、それをデプロイメントに関連付けるのに役立ちます。

最新の Web 開発では、監視とロギングは、堅牢で信頼性の高いアプリケーションを維持するための重要な側面です。 Telemetry を使用すると、開発者は、デバッグやユーザー エクスペリエンスの向上に重要なさまざまなイベントやシステム メトリクスを追跡できます。この投稿では、Telemetry API を使用して、Express.js Web サーバー内のすべてのエラーを捕捉してログに記録する方法を説明します。このガイドでは Express のみを取り上げていますが、このアイデアは Rails から Elixir などのすべての Web サーバーに適用できます。

Telemetry のセットアップ

データをログに記録する前に、Telemetry を設定する必要があります。この例では、Telemetry JavaScript SDK を使用します。

まず、Telemetry SDK をプロジェクトにインストールします。

npm install telemetry-sh

次に、API キーを使用してアプリケーション内の Telemetry クライアントを初期化します。

const telemetry = require("telemetry-sh");

telemetry.init(process.env.TELEMETRY_API_KEY);

サーバー環境に TELEMETRY_API_KEY を設定してください。キーをブラウザー側のコードに入れたり、コミットしたりしないでください。

Express アプリケーションを作成する

次に、基本的な Express アプリケーションをセットアップしましょう。 Express をまだインストールしていない場合は、次のコマンドを使用してプロジェクトに追加できます。

npm install express

次に、単純な Express サーバーを作成します。

const express = require('express');
const app = express();
const port = 3000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(port, () => {
  console.log(`Example app listening at http://localhost:${port}`);
});

構造化エラーミドルウェアを追加する

エラー ハンドラーはすべてのルートの後に属します。プライベートな値を含む可能性のある生の本体、資格情報、スタック トレース、または例外メッセージではなく、安全なカテゴリと操作コンテキストをキャプチャします。

// Add this after the real routes in your existing Express app.
app.use((err, req, res, next) => {
  if (res.headersSent) return next(err);
  const statusCode = Number(err.statusCode) || 500;
  const rawCode = typeof err.code === "string" ? err.code : "";
  const errorCode = /^[A-Z0-9_]{1,40}$/.test(rawCode)
    ? rawCode
    : "UNCLASSIFIED_ERROR";

  res.status(statusCode).json({ error: "Request failed" });

  void Promise.resolve()
    .then(() => telemetry.log("api_request_failed", {
      route_template: req.route?.path ?? "unmatched_route",
      method: req.method,
      status_code: statusCode,
      status: "error",
      error_type: err.constructor?.name ?? "Error",
      error_code: errorCode,
      request_id: res.locals.requestId ?? "missing",
      release: process.env.APP_RELEASE ?? "unknown",
    }))
    .catch(() => console.warn("Telemetry error event was not sent"));
});

このハンドラーは、実際のルートを処理する既存の Express アプリに追加してください。上の Hello World の例だけではエラーイベントは発生しません。実際に失敗するリクエストを1回実行し、その行が api_request_failed に保存されたことをクエリで確認します。アプリが信頼できるリクエスト ID を生成する場合は、このハンドラーの前に res.locals.requestId に設定してください。この例では応答を返してから Telemetry に送信します。サーバーレス環境では、待機しない Promise に頼らず、プラットフォームがサポートするバックグラウンドタスクまたはフラッシュ機構を使ってください。

次のようなルート テンプレートを使用します。 /api/projects/:id、顧客識別子を含む生のパスではありません。ワークフローにとって障害が重要な場合は、処理された 4xx および 5xx 応答のイベント スキーマを同じに保ちます。

エラーをクエリして視覚化する

まずルートとリリースごとの失敗件数を確認し、調査用に最近のイベントの表を残します。

SELECT
  route_template,
  release,
  status_code,
  error_code,
  COUNT(*) AS failures,
  MAX(timestamp_utc) AS last_seen_at
FROM api_request_failed
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template, release, status_code, error_code
ORDER BY failures DESC, last_seen_at DESC;

真のエラー率を得るには、成功したリクエストと失敗したリクエストを共有テーブルを使用して同じテーブルに記録します。 status または status_code フィールド。失敗のみのテーブルではエラーをランク付けできますが、分母を提供することはできません。

次のステップ

を使用します。 ルート レシピ別の API エラー率 分母安全なクエリ、視覚化の例、ダッシュボード レイアウト、アラート ガイダンスを提供します。と組み合わせてください API 遅延パーセンタイル したがって、インシデントビューは正確さと速度の両方をカバーします。