跳至主要內容
整合指南

Prisma ORM 資料庫 Telemetry

測量 Prisma 操作指紋、模型和方法延遲、故障、結果計數、版本和依賴於資料庫的工作流程,而無需收集原始查詢參數。

審閱者 Telemetry產品團隊 上 . 我們檢查了要傳送的事件、要排除的資料和程式碼新增方式. 誰負責審查此頁面

有用於
  • Prisma 操作延遲
  • 發布迴歸分析
  • 依賴於資料庫的工作流程除錯
實施證據

使用 Prisma ORM database telemetry 傳送並驗證事件

在受控應用程式邊界使用 Prisma ORM database telemetry,保持事件契約較小,並在建置聚合檢視之前驗證已知結果。

  1. 1

    選擇結果

    Prisma 操作延遲

  2. 2

    定義合約

    query_fingerprint、prisma_model、prisma_operation 和工作流程

  3. 3

    在結果處發出

    使用顯式指紋(例如 User.findMany.active)包裝產品級 Prisma 呼叫,而不是轉發發出的 SQL。

  4. 4

    核實證據

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

開始之前

開始之前

  • Prisma 客戶端在伺服器上初始化
  • 在應用程式呼叫站點選擇的穩定操作名稱
  • A server-side TELEMETRY_API_KEY and a runtime supporting fetch and AbortSignal.timeout

交貨設定

安裝並初始化伺服器端

此伺服器端範例透過 Log API 傳送事件,使用伺服器端金鑰與有時限的 fetch 請求;不需初始化 Telemetry SDK。 將攝取憑據保留在瀏覽器包、客戶端可見的環境變數、原始碼控制、日誌和異常訊息之外。

  1. 1準備一個具有有限網路行為的可重用伺服器端交付客戶端。
  2. 2在成功、失敗、重試或超時邊界處新增結果事件。
  3. 3在啟用警示之前傳送受控裝置並檢查儲存的行。

片段

從一個結構化事件開始

在工作流程完成、失敗或重試的位置新增此形狀。然後從真實的欄位建置儀表板。

prisma

Prisma ORM database telemetry事件

javascript
async function recordDatabaseOutcome(data) {
  try {
    const response = await fetch("https://api.telemetry.sh/log", {
      method: "POST",
      headers: {
        Authorization: process.env.TELEMETRY_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ table: "database_query_completed", data }),
      signal: AbortSignal.timeout(2_000),
    });
    if (!response.ok) console.warn("Telemetry delivery failed", response.status);
  } catch {
    // Preserve the database result or original error when logging is unavailable.
    try { console.warn("Telemetry delivery failed"); } catch {}
  }
}

const SAFE_DATABASE_ERROR_CODES = new Set(["P2024", "P2034"]);

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 observePrismaOperation({
  queryFingerprint,
  model,
  operation,
  workflow,
  run,
}) {
  const startedAt = performance.now();
  try {
    const result = await run();
    await recordDatabaseOutcome({
      query_fingerprint: queryFingerprint,
      prisma_model: model,
      prisma_operation: operation,
      workflow,
      database_name: "app_production",
      status: "success",
      duration_ms: Math.round(performance.now() - startedAt),
      rows_returned: result == null ? 0 : Array.isArray(result) ? result.length : 1,
      release: process.env.APP_RELEASE,
      environment: process.env.NODE_ENV,
    });
    return result;
  } catch (error) {
    await recordDatabaseOutcome({
      query_fingerprint: queryFingerprint,
      prisma_model: model,
      prisma_operation: operation,
      workflow,
      database_name: "app_production",
      status: "failed",
      duration_ms: Math.round(performance.now() - startedAt),
      error_type: classifyDatabaseError(error),
      release: process.env.APP_RELEASE,
      environment: process.env.NODE_ENV,
    });
    throw error;
  }
}

const users = await observePrismaOperation({
  queryFingerprint: "User.findMany.active",
  model: "User",
  operation: "findMany",
  workflow: "account_directory",
  run: () => prisma.user.findMany({ where: { active: true } }),
});

事件結構

query_fingerprint、prisma_model、prisma_operation 和工作流程

狀態、duration_ms、rows_returned、受控 error_type 和 account_id

database_name,版本、環境和安全相關識別符號

檢查設定

檢查站 1

使用顯式指紋(例如 User.findMany.active)包裝產品級 Prisma 呼叫,而不是轉發發出的 SQL。

檢查站 2

將模型、操作和工作流程分開,以便資料庫迴歸可以連線到客戶可見的行為。

檢查站 3

Prisma 查詢事件公開 SQL 和參數;不要將任何一個欄位傳送到 Telemetry。

檢查站 4

The bounded best-effort Log API wrapper keeps delivery failures separate from database outcomes; query the captured event 中 the intended workspace to verify ingestion.

檢查站 5

Use a durable outbox if event loss is unacceptable.

驗證

證明事件已到達

在演練已知的成功和失敗案例後執行此命令。如果您的最終事件契約與程式碼片段不同,請替換後備資料表名稱。

prisma-verification

Prisma ORM database telemetry 驗證查詢

sql
SELECT *
FROM database_query_completed
ORDER BY timestamp_utc DESC
LIMIT 20;
確認每個邏輯結果的一個終端行,以及預期狀態、識別符號、單位和 UTC 時間。
檢查推斷的架構並驗證重試不會更改欄位型別或生成新的邏輯事件 ID。
在儲存的欄位中搜尋憑據、原始有效負載、提示、私有內容和無限制的錯誤訊息。
在將儀表板視為完整之前,請執行提供程式超時、攝取拒絕和處理程序關閉。

實施參考

在啟用新的生產路徑之前,請檢查事件合約、資料安全指南和上游主要文件。

在哪裡記錄事件

保持結果事件小且可恢復

該模式提供了

  • 除了上游工作流程之外,還有一個有界的、SQL 就緒的結果。
  • 用於儀表板、警示和跨事件關聯的穩定欄位。
  • 用於驗證成功、失敗、重試和超時行為的夾具驅動路徑。

該模式不提供

  • OTLP 匯出器、自動收集管道或詳細追蹤和診斷日誌的替代品。
  • 僅因為有效負載包含事件 ID,所以僅傳送一次。
  • 收集原始提供商有效負載、使用者內容、憑證或受監管資料的權限。

事件結構描述範例

在將查詢或程式碼片段適應生產之前,請檢查行粒度、發出邊界、所需型別、隱私類、範例有效負載和驗證清單。

相關產品功能

繼續此工作流程 SQL 查詢 API

對結構化事件資料表執行只讀 DataFusion SQL 並重用結果。

相關 SQL 查詢範例

更多 SQL 範例

針對此工作流程中的結構化欄位執行查詢,檢查範例結果,並將有用的答案轉換為儀表板或警示。

瀏覽所有查詢範例
查詢範例集資料庫可靠性 SQL

按實施系列瀏覽

比較相關整合模式

與此整合配對的範本

更多整合