コーディングエージェントでこのドキュメントを使用してください

Claude Code、Codex、Cursor、または別のコーディングエージェント用の集中プロンプトパックを開き、それをここで説明するワークフローに適応させます。

プロンプトパックを開く実際のテレメトリを接続する

このページの内容

Telemetry のセットアップ
Express アプリケーションを作成する
構造化エラーミドルウェアを追加する
エラーをクエリして視覚化する
次のステップ

Webサーバーエラーの分析

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

5xx スパイクとリリースおよび POST チェックアウトルートを相関付ける Web サーバーエラーダッシュボード — 最も便利なエラーイベントは、インシデント発生時に必要なディメンションを保存します。

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

Telemetry のセットアップ

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

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

npm install telemetry-sh

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

import telemetry from "telemetry-sh";

telemetry.init("YOUR_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}`);
});

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

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

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

telemetry.init(process.env.TELEMETRY_API_KEY);

const app = express();

app.get("/api/projects/:id", async (req, res) => {
  throw Object.assign(new Error("Synthetic failure"), {
    code: "PROJECT_LOOKUP_FAILED",
  });
});

app.use(async (err, req, res, next) => {
  const statusCode = Number(err.statusCode) || 500;

  await 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: err.code ?? "UNCLASSIFIED_ERROR",
    request_id: req.get("x-request-id") ?? "missing",
    release: process.env.APP_RELEASE ?? "unknown",
  });

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

app.listen(3000);

次のようなルートテンプレートを使用します。 /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 遅延パーセンタイルしたがって、インシデントビューは正確さと速度の両方をカバーします。

ページの著者と参考資料

Telemetry 編集チームがこの説明を所有しています。製品チームは動作、例、境界をレビューします。

ドキュメントのレビュー方法

コーディング エージェントでこのドキュメントを使用してください