本文へ移動
Telemetry
統合ガイド

node-postgres プールとクエリ Telemetry

SQL パラメーターをログに記録することなく、ノード Postgres クエリのフィンガープリント、接続の取得、プールの圧力、タイムアウト、トランザクションの結果、データベース エラーを計測します。

レビュー者 Telemetry 製品チーム . インストルメンテーション契約、プライバシー境界、および実装ガイダンス. 基準と所有権を確認する

役に立つ
  • Postgres 接続プールの監視
  • 遅いデータベース操作の分析
  • トランザクションとタイムアウトのデバッグ
実装の証拠

node-postgres Pool and Query Telemetry: 境界から検証された行まで

制御されたアプリケーション境界で node-postgres Pool and Query Telemetry を使用し、イベント コントラクトを小さく保ち、集約ビューを構築する前に既知の結果を検証します。

  1. 1

    結果を選択してください

    Postgres 接続プールの監視

  2. 2

    契約を定義する

    query_fingerprint、サービス、database_name、ステータス、および duration_ms

  3. 3

    境界を計測する

    生の SQL から取得するのではなく、呼び出しサイトから境界付きフィンガープリントを渡します。

  4. 4

    証拠を検証する

    Exercise a known fixture, then inspect database_query_completed for one correctly typed terminal row.

始める前に

前提条件と境界

  • 共有プールを含む pg パッケージ
  • アプリケーションが所有する操作のフィンガープリント
  • サーバー側 TELEMETRY_API_KEY

配信設定

サーバー側のインストールと初期化

サーバー専用コードで telemetry-sh をインポートし、process.env.TELEMETRY_API_KEY で一度初期化します。 ブラウザ バンドル、クライアントに表示される環境変数、ソース管理、ログ、および例外メッセージに取り込み資格情報が含まれないようにします。

node-postgres-インストール

npmのインストール

bash
npm install telemetry-sh
  1. 1制限されたネットワーク動作を持つ再利用可能なサーバー側配信クライアントを 1 つ準備します。
  2. 2成功、失敗、再試行、またはタイムアウトの境界に結果イベントを追加します。
  3. 3アラートを有効にする前に、制御されたフィクスチャを送信し、保存されている行を検査します。

スニペット

1 つの構造化されたイベントから始める

ワークフローが完了、失敗、または再試行される場所にこの図形を追加します。次に、実際のフィールドからダッシュボードを構築します。

node-postgres

node-postgres Pool and Query Telemetryイベント

javascript
import { Pool } from "pg";
import telemetry from "telemetry-sh";

const pool = new Pool({ max: 10 });
const SAFE_DATABASE_ERROR_CODES = new Set(["40001", "40P01", "55P03", "57014"]);

function classifyDatabaseError(error) {
  return error && typeof error === "object" &&
    "code" in error &&
    SAFE_DATABASE_ERROR_CODES.has(String(error.code))
    ? String(error.code)
    : "database_error";
}

async function runDatabaseOperation({
  queryFingerprint,
  text,
  values,
}) {
  const acquireStartedAt = performance.now();
  let client;

  try {
    client = await pool.connect();
    const acquisitionWaitMs = performance.now() - acquireStartedAt;
    const queryStartedAt = performance.now();
    const result = await client.query(text, values);
    await telemetry.log("database_query_completed", {
      query_fingerprint: queryFingerprint,
      service: "checkout-api",
      database_name: "app_production",
      status: "success",
      duration_ms: Math.round(performance.now() - queryStartedAt),
      acquisition_wait_ms: Math.round(acquisitionWaitMs),
      rows_returned: result.rowCount ?? result.rows.length,
      active_connections: pool.totalCount - pool.idleCount,
      idle_connections: pool.idleCount,
      max_connections: pool.options.max ?? 10,
      waiting_count: pool.waitingCount,
      release: process.env.APP_RELEASE,
      environment: process.env.NODE_ENV,
    });
    return result;
  } catch (error) {
    await telemetry.log("database_query_completed", {
      query_fingerprint: queryFingerprint,
      service: "checkout-api",
      database_name: "app_production",
      status: "failed",
      duration_ms: Math.round(performance.now() - acquireStartedAt),
      error_type: classifyDatabaseError(error),
      active_connections: pool.totalCount - pool.idleCount,
      idle_connections: pool.idleCount,
      max_connections: pool.options.max ?? 10,
      waiting_count: pool.waitingCount,
      release: process.env.APP_RELEASE,
      environment: process.env.NODE_ENV,
    });
    throw error;
  } finally {
    client?.release();
  }
}

イベント契約

query_fingerprint、サービス、database_name、ステータス、および duration_ms

active_connections、idle_connections、max_connections、および waiting_count

acquisition_wait_ms、rows_returned、error_type、リリース、環境

実装のチェックポイント

チェックポイント 1

生の SQL から取得するのではなく、呼び出しサイトから境界付きフィンガープリントを渡します。

チェックポイント 2

接続の取得をクエリの実行とは別に測定して、プールの競合がデータベースの作業と誤解されないようにします。

チェックポイント 3

ホワイトリストを通じてドライバーのエラー コードを記録し、接続文字列、クエリ パラメーター、または生のデータベース メッセージを決して転送しないでください。

検証

イベントが到着したことを証明する

既知の成功例と失敗例を実行した後、これを実行します。最終的なイベント コントラクトがスニペットと異なる場合は、フォールバック テーブル名を置き換えます。

node-postgres-検証

node-postgres Pool and Query Telemetry 検証クエリ

sql
SELECT *
FROM database_query_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
論理結果ごとに 1 つのターミナル行を、予想されるステータス、識別子、単位、および UTC 時刻とともに確認します。
推論されたスキーマを検査し、再試行によってフィールド タイプが変更されたり、新しい論理イベント ID が生成されたりしないことを確認します。
保存されたフィールドで認証情報、生のペイロード、プロンプト、プライベート コンテンツ、および無制限のエラー メッセージを検索します。
ダッシュボードを完了として扱う前に、プロバイダーのタイムアウト、取り込みの拒否、およびプロセスのシャットダウンを実行します。

実装の参考資料

新しい運用パスを有効にする前に、イベント契約、データ安全性に関するガイダンス、上流の主要ドキュメントを確認してください。

生産境界

結果イベントを小さく、回復可能なものに保つ

このパターンが提供するのは、

  • 上流のワークフローの横にある、制限付きの SQL 対応の結果。
  • ダッシュボード、アラート、およびイベント間の相関関係の安定したフィールド。
  • 成功、失敗、再試行、タイムアウトの動作を検証するためのフィクスチャ駆動のパス。

このパターンでは提供されません

  • OTLP エクスポーター、自動収集パイプライン、または詳細なトレースと診断ログの代替。
  • ペイロードにイベント ID が含まれているという理由だけで、1 回だけ配信されます。
  • 生のプロバイダー ペイロード、ユーザー コンテンツ、資格情報、または規制されたデータを収集する許可。

イベントスキーマの開始点

クエリまたはスニペットを運用環境に適用する前に、行粒度、出力境界、必要なタイプ、プライバシー クラス、サンプル ペイロード、および検証チェックリストを確認してください。

関連製品の機能

このワークフローを続行します SQL クエリ API

構造化イベント テーブルに対して読み取り専用 DataFusion SQL を実行し、結果を再利用します。

関連する SQL レシピ

SQL で次の質問に答えてください

このワークフローの構造化フィールドに対してクエリを実行し、結果の例を検査して、有用な回答をダッシュボードまたはアラートに変換します。

すべてのレシピを参照する
データベースの信頼性初心者

遅いデータベース クエリをフィンガープリントで検出する

調査するには十分なほど常に遅いデータベース操作はどれですか?

レシピを開く
データベースの信頼性初心者

データベースクエリを合計時間の影響でランク付けする

どのデータベース操作が最も累積リクエスト時間を消費しますか?

レシピを開く
データベースの信頼性初心者

データベース接続プールの飽和状態を測定する

どのアプリケーション プールが呼び出し元にデータベース接続を待たせていますか?

レシピを開く
データベースの信頼性中級者

データベース接続のタイムアウトとチャーンを測定する

どのサービスとリージョンが異常なデータベース接続のチャーンを示していますか?

レシピを開く
データベースの信頼性中級者

データベーストランザクションのロールバック率の計算

異常な割合のデータベース トランザクションをロールバックするサービスはどれですか?

レシピを開く
データベースの信頼性中級者

長時間実行されるデータベース トランザクションの測定

どのアプリケーション トランザクション クラスが最も長く開いたままになりますか?

レシピを開く
データベースの信頼性中級者

データベースのロック待機とデッドロックの検索

最も深刻なロック競合を引き起こすデータベース操作はどれですか?

レシピを開く
データベースの信頼性初心者

SQLSTATEとリリースによるデータベースエラーの分析

アプリケーションのリリース後に増加したデータベース エラー クラスはどれですか?

レシピを開く
データベースの信頼性初心者

データベースのレプリケーションと CDC ラグを測定する

どのレプリカまたは CDC コンシューマーがソース データベースに遅れをとっていますか?

レシピを開く
データベースの信頼性上級者向け

リージョンごとにデータベース レプリカの古さを測定する

どのレプリカ リージョンが古い読み取りまたは失敗した読み取りを処理していますか?

レシピを開く
データベースの信頼性初心者

データベース移行の失敗をリリースごとに追跡する

失敗したデータベース移行またはロールバックされたデータベース移行はどのリリースに含まれていますか?

レシピを開く
完全なコレクションデータベースの信頼性 SQL

実装ファミリーごとに参照する

関連する統合パターンを比較する

この統合と組み合わせるテンプレート

さらなる統合