node-postgres Pool and Query Telemetry：從邊界到驗證行
在受控應用程式邊界使用 node-postgres Pool and Query Telemetry，保持事件契約較小，並在建置聚合檢視之前驗證已知結果。
- 1
選擇結果
Postgres 連線池監控
- 2
定義合約
query_fingerprint、服務、database_name、狀態和 duration_ms
- 3
埋點邊界
從呼叫站點傳遞有界指紋，而不是從原始 SQL 派生它。
- 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 對其進行一次初始化。 將攝取憑據保留在瀏覽器包、客戶端可見的環境變數、原始碼控制、日誌和異常訊息之外。
npm安裝
npm install telemetry-sh- 1準備一個具有有限網路行為的可重用伺服器端交付客戶端。
- 2在成功、失敗、重試或超時邊界處新增結果事件。
- 3在啟用警示之前傳送受控裝置並檢查儲存的行。
片段
從一個結構化事件開始
在工作流程完成、失敗或重試的位置新增此形狀。然後從真實的欄位建置儀表板。
node-postgres Pool and Query Telemetry事件
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 Pool and Query Telemetry 驗證查詢
SELECT *
FROM database_query_completed
ORDER BY timestamp_utc DESC
LIMIT 20;實施參考
在啟用新的生產路徑之前，請檢查事件合約、資料安全指南和上游主要文件。
生產邊界
保持結果事件小且可恢復
該模式提供了
- 除了上游工作流程之外，還有一個有界的、SQL 就緒的結果。
- 用於儀表板、警示和跨事件關聯的穩定欄位。
- 用於驗證成功、失敗、重試和超時行為的夾具驅動路徑。
該模式不提供
- OTLP 匯出器、自動收集管道或詳細追蹤和診斷日誌的替代品。
- 僅因為有效負載包含事件 ID，所以僅傳送一次。
- 收集原始提供商有效負載、使用者內容、憑證或受監管資料的權限。
事件架構起點
此工作流程的事件契約
在將查詢或程式碼片段適應生產之前，請檢查行粒度、發出邊界、所需型別、隱私類、範例有效負載和驗證清單。
相關產品功能
繼續此工作流程 SQL 查詢 API
對結構化事件資料表執行只讀 DataFusion SQL 並重用結果。
相關 SQL 查詢範例
用 SQL 回答下一個問題
針對此工作流程中的結構化欄位執行查詢，檢查範例結果，並將有用的答案轉換為儀表板或警示。
透過指紋查詢緩慢的資料庫查詢
哪些資料庫操作始終慢到足以進行調查？
開啟查詢範例按總時間影響對資料庫查詢進行排名
哪個資料庫操作消耗的累積請求時間最多？
開啟查詢範例測量資料庫連線池飽和度
哪些應用程式池使呼叫者等待資料庫連線？
開啟查詢範例測量資料庫連線超時和改動
哪些服務和區域顯示出不健康的資料庫連線流失？
開啟查詢範例計算資料庫事務回滾率
哪些服務回滾了異常份額的資料庫事務？
開啟查詢範例測量長時間執行的資料庫事務
哪些應用程式事務類別保持開放時間最長？
開啟查詢範例查詢資料庫鎖等待和死鎖
哪些資料庫操作會造成最嚴重的鎖爭用？
開啟查詢範例透過 SQLSTATE 和版本分析資料庫錯誤
應用程式發布後哪些資料庫錯誤類別增加了？
開啟查詢範例測量資料庫複製和 CDC 延遲
哪些副本或 CDC 使用者落後於源資料庫？
開啟查詢範例按區域測量資料庫副本的陳舊程度
哪些副本區域正在提供過時或失敗的讀取？
開啟查詢範例按版本追蹤資料庫遷移失敗
哪些版本包含失敗或回滾的資料庫遷移？
開啟查詢範例按實施系列瀏覽
比較相關整合模式
與此整合配對的範本
更多整合