2022年10月17日

使用 Prisma、Prometheus 和 Grafana 的資料庫指標

Prisma 的指標功能為您提供了關於 Prisma 如何與資料庫互動的詳細洞察。在本教程中，您將學習如何使用指標來監控您的資料庫，結合 Prisma、Prometheus 和 Grafana。

簡介

本教程將教您如何使用指標來提升應用程式的監控能力。您將親手實踐如何將指標整合到使用 Prisma、PostgreSQL 和 Express 構建的 Web 應用程式中。

您將使用一個預構建的 Express API 伺服器，該伺服器使用 Prisma 與 PostgreSQL 資料庫互動。在本教程中，您將學習如何使用 Prisma 的指標功能向 API 伺服器新增指標。您還將學習如何設定和配置 Prometheus 和 Grafana 來收集和視覺化生成的指標。

什麼是指標？

指標是資料的數值表示，用於隨時間監控和觀察系統行為。您可以使用它來確保系統按預期執行、識別潛在問題、衡量業務目標等。

在 Prisma 中，指標是一個新功能，允許您監控 Prisma 如何與資料庫互動。指標暴露了一組計數器、量規和直方圖，提供有關 Prisma 和資料庫連線狀態的資訊。Prisma 暴露的指標包括

執行的 Prisma Client 查詢總數 (prisma_client_queries_total)
執行的 SQL 或 MongoDB 查詢總數 (prisma_datasource_queries_total)
活躍資料庫連線數 (prisma_pool_connections_open)
包含所有執行的 Prisma Client 查詢持續時間的直方圖 (prisma_client_queries_duration_histogram_ms)
... 還有更多！

注意：可用指標的完整列表可在指標文件中找到。

指標可以直接由您的應用程式分析，也可以傳送到外部監控系統和時間序列資料庫，如 Prometheus 或 StatsD。與這些外部系統整合可以顯著提高您的監控能力，開箱即用地提供以下功能

透過視覺化和儀表盤進行即時效能監控
查詢和分析歷史資料
針對故障和效能下降的精確自動化警報

在本教程中，您將使用 Prometheus 收集指標，並使用 Grafana 視覺化指標。

注意：指標通常與追蹤結合使用，以獲得系統更精細的概覽。要了解更多關於追蹤的資訊，請檢視我們的追蹤教程。

您將使用的技術

在本教程中，您將使用以下工具

Prisma 作為物件關係對映器 (ORM)
PostgreSQL 作為資料庫
Prometheus 作為指標收集器
Grafana 作為指標視覺化工具
Express 作為 Web 框架
TypeScript 作為程式語言

先決條件

假定知識

本教程對初學者友好。但是，它假定您具備以下知識

JavaScript 或 TypeScript（首選）的基礎知識
後端 Web 開發的基礎知識

注意：本教程假定您沒有指標方面的先驗知識。

開發環境

要跟隨本教程，您需要

... 已安裝 Node.js。
... 已安裝 Docker 和 Docker Compose。

注意：如果您使用 Linux，請確保您的 Docker 版本為 20.10.0 或更高。您可以透過在終端中執行 docker version 來檢查您的 Docker 版本。
... 可選地安裝 Prisma VS Code 擴充套件。Prisma VS Code 擴充套件為 Prisma 添加了非常棒的智慧感知和語法高亮功能。
... 可選地擁有 Unix shell 的訪問許可權（如 Linux 和 macOS 中的終端/shell），以便執行本系列中提供的命令。

如果您沒有 Unix shell（例如，您使用的是 Windows 機器），您仍然可以跟隨操作，但 shell 命令可能需要根據您的機器進行修改。

克隆儲存庫

您將使用我們為本教程構建的現有 Express Web 應用程式。

要開始，請執行以下操作

克隆儲存庫

安裝依賴

使用 Docker 在埠 5432 上啟動 PostgreSQL 資料庫

注意：如果您關閉執行 Docker 容器的終端視窗，它也會停止容器。您可以透過在命令末尾新增 -d 選項來避免這種情況，例如：docker-compose up -d。

從 prisma/migrations 目錄應用資料庫遷移

注意：此命令還將生成 Prisma Client 併為資料庫填充資料。

啟動伺服器

注意：在開發應用程式時，您應該保持伺服器執行。dev 指令碼應在程式碼發生任何更改時重新啟動伺服器。

專案結構和檔案

您克隆的儲存庫具有以下結構

該儲存庫包含 REST API 的程式碼。它包含一個 /articles 端點，您可以在其中執行各種 CRUD（建立、讀取、更新和刪除）操作。還有一個 /articles/audit 端點，可以查詢該端點以獲取對各種文章所做更改的日誌。

此儲存庫中值得注意的檔案和目錄是

prisma
- schema.prisma：定義資料庫 schema。
- migrations：包含資料庫遷移歷史。
- seed.ts：包含一個用於為您的開發資料庫填充模擬資料的指令碼。
server.ts：帶有各種端點的 Express REST API 實現。
loadtest.js：一個使用 k6 向 REST API 生成大量流量的指令碼。

注意：請隨意探索儲存庫中的檔案，以更好地瞭解應用程式。

將指標整合到您的應用程式中

您的 Express 應用程式已經實現了所有核心“業務邏輯”。為了衡量應用程式的效能，您將整合指標。

本節將教您如何初始化指標並從您的 Web 伺服器公開它們。

在 Prisma Client 中啟用指標

指標目前在 Prisma 中作為預覽功能提供。要使用它，您需要在 schema.prisma 檔案的 generator 塊中啟用 metrics 功能標誌

現在，重新生成 Prisma Client

啟用指標功能後，Prisma 將允許您使用 prisma.$metrics API 檢索有關資料庫操作的指標。您可以以JSON 格式或Prometheus 格式公開指標。

從您的 Web 伺服器公開指標

在本節中，您將從 Express Web 伺服器公開資料庫指標。為此，您將建立一個名為 GET /metrics 的新端點，該端點將以 Prometheus 格式返回指標。

要實現 GET /metrics 端點，請將以下路由新增到 server.ts

確保伺服器正在執行，然後訪問 https://:4000/metrics 以檢視生成的指標。

注意：您可以透過執行 npm run dev 來啟動伺服器。

Metrics in Prometheus format

注意：您還可以使用 prisma.$metrics.json() 以 JSON 格式檢索指標。您可以在文件中瞭解更多關於 JSON 格式的資訊。

整合 Prometheus

在本節中，您將學習如何配置 Prometheus 並將其整合到您的應用程式中。Prometheus 透過定期從特定端點請求資料來收集指標。您將配置 Prometheus 從 https://:4000/metrics 端點抓取指標資料。

建立 Prometheus 配置檔案

首先，在專案根目錄下建立一個名為 prometheus 的新資料夾。然後，在該資料夾中建立一個名為 prometheus.yml 的新檔案。

使用 Prometheus 配置更新檔案

需要記住的一些重要選項是

job_name 是用於識別特定配置中指標的元資料。
scrape_interval 是 Prometheus 抓取指標端點的間隔。
targets 包含要抓取的端點列表。Prometheus 預設會抓取 /metrics 端點。因此無需明確提及。

注意：host.docker.internal 是一個特殊的 DNS 名稱，它解析到執行 Docker 的主機機器的內部 IP 地址。由於 Prometheus 在 Docker 內部執行，因此使用此特殊 DNS 名稱以便它可以解析主機機器（您的計算機）的 https://。

啟動一個 Prometheus 例項

配置檔案準備好後，您需要執行 Prometheus。您將透過擴充套件 docker-compose.yml 檔案，在 Docker 容器內設定 Prometheus。透過將當前檔案內容替換為以下內容，將 prometheus 映象新增到 docker-compose.yml 檔案中

新的 prometheus 映象已配置為使用您之前建立的 prometheus/prometheus.yml 配置檔案。它還將暴露埠 9090 到主機機器，您可以使用該埠訪問 Prometheus 使用者介面 (UI)。該映象將使用一個名為 prometheus-storage 的卷來儲存 Prometheus 的資料。

注意：在 Linux 機器上，需要 extra_hosts 選項才能解析 host.docker.internal。如果您使用的是 Linux，請確保您的 Docker 版本為 20.10.0 或更高。您可以檢視此Github 評論以獲取更多資訊。

現在您需要重啟在 Docker Compose 中執行的容器。您可以透過再次執行 docker-compose up 命令並新增 --force-recreate 選項來完成此操作。開啟一個新的終端視窗並執行以下命令

如果命令成功，您應該能夠在 https://:9090 中看到 Prometheus UI。

Prometheus UI

在 Prometheus UI 中探索指標

在Expression（表示式）輸入欄位中，您可以輸入一個PromQL（Prometheus 查詢語言）查詢來檢索指標資料。例如，您可以輸入 prisma_client_queries_total 來檢視 Prisma Client 執行的查詢數量。輸入查詢後，點選Execute（執行）按鈕檢視結果。

注意：您可能會看到響應Empty query result（空查詢結果）而不是實際值。這也沒關係——繼續下一步。

Query execution result in Prometheus UI expression browser

您正在看到的介面被稱為表示式瀏覽器。它允許您以表格或圖形格式檢視任何 PromQL 表示式的結果。

目前，查詢數量為 0 或為空，因為您尚未發出任何 API 請求。為了避免手動發出大量請求來生成指標資料，您將使用負載測試工具 k6。專案中已提供一個名為 loadtest.js 的負載測試指令碼。您可以透過執行以下命令來執行此指令碼

此命令將首先拉取 k6 Docker 映象，然後開始向您的 Express API 發出大量請求。在 k6 開始發出請求後，您可以返回 Prometheus UI 並再次執行之前的查詢。您現在應該會看到查詢數量迅速增加。

Prometheus UI 還提供了一種以時間序列圖形式檢視指標的方式。您可以透過點選Graph（圖形）選項卡來完成此操作。在Expression（表示式）輸入欄位中，輸入與之前相同的查詢，然後點選Execute（執行）按鈕。您應該會看到一個圖表，顯示 Prisma Client 隨時間執行的查詢數量。

Query execution result in graph format

注意：請隨意在 Prometheus UI 中嘗試其他查詢。您可以在Prisma 文件中找到所有可用指標的列表。您還可以透過閱讀Prometheus 文件瞭解如何執行更復雜的 PromQL 查詢。

Prometheus 表示式瀏覽器是一個用於快速視覺化臨時查詢的有用工具。但它不是一個功能齊全的視覺化工具。Prometheus 通常與Grafana搭配使用，Grafana 是一個功能豐富且強大的視覺化和分析工具。

使用 Grafana 視覺化指標

在本節中，您將學習如何設定 Grafana 並使用它建立視覺化指標資料的儀表盤。Grafana 是一款流行的開源視覺化工具，廣泛用於監控和視覺化。

您將首先整合 Grafana，使其能夠從 Prometheus 收集應用程式的監控資料。然後，您將建立一個儀表盤，有意義地表示系統暴露的各種指標。

完全配置後，您的應用程式將如下所示

Application architecture with Prometheus and Grafana

注意：Web 應用程式通常有一個前端（客戶端）來消費 Web 伺服器的 API。但是，本教程不包含前端，以避免不必要的複雜性。

啟動一個 Grafana 例項

要啟動一個 Grafana 例項，您需要將一個新的 grafana 映象新增到您的 Docker Compose 檔案中。用以下配置替換 docker-compose.yml 的當前內容

grafana 映象配置為使用名為 grafana-storage 的捲來儲存資料。此卷將用於在重啟後保留 Grafana 的資料。grafana 映象還配置為將埠 3000 暴露給主機機器，您可以使用該埠訪問 Grafana UI。

透過執行以下命令再次重啟容器

如果您訪問 https://:3000，您將看到 Grafana 登入螢幕。預設使用者名稱和密碼都是 admin，您可以使用它們登入。您可以跳過建立新密碼。

您現在應該會看到 Grafana 登入頁面。

Grafana landing page

將 Prometheus 資料來源新增到 Grafana

您需要向 Grafana 新增一個資料來源。資料來源是 Grafana 可以查詢以檢索指標資料的外部系統。在這種情況下，您的資料來源將是 Prometheus。

要透過 UI 新增資料來源，請執行以下操作

點選側邊選單左下角的齒輪圖示。
在Data sources（資料來源）配置視窗中，點選Add data source（新增資料來源）。
點選Prometheus作為資料來源型別。
在 Prometheus 資料來源配置頁面中，將URL設定為 http://prometheus:9090，將Scrape Interval（抓取間隔）設定為 1s。http://prometheus:9090 將解析到 prometheus 容器上的埠 9090。這得益於 Docker Compose 自動配置的Docker 網路。
點選Save & test（儲存並測試）以儲存配置。

如果一切配置正確，您應該會看到Data source is working（資料來源工作正常）訊息。

Grafana data source configuration

建立您的第一個 Grafana 儀表盤

一個儀表盤是表示指標資料的視覺化集合。儀表盤由一個或多個面板組成，面板是 Grafana 中基本的 Visualization Building Block（視覺化構建塊）。

注意：在開始之前，您應該透過執行 npm run loadtest 來生成一些流量，以便有資料可供視覺化。

要建立您的第一個儀表盤，請執行以下操作

點選側邊選單中Dashboards（儀表盤）圖示下的+ New dashboard（新建儀表盤）選項。
在儀表盤上，點選Add a new panel（新增新面板）以進入面板編輯器。Query（查詢）選項卡中的Data source（資料來源）應該已經設定為Prometheus。
在Query（查詢）選項卡內，在Metric（指標）輸入框中填寫 prisma_client_queries_total。
按下+ Query（查詢）按鈕，並在新的Metric（指標）中新增 prisma_datasource_queries_total。
在右側邊欄中，將Title（標題）欄位從Panel Title（面板標題）更改為“Prisma Client Queries vs. Datasource Queries”。
點選頂部的Save（儲存），系統會要求您為儀表盤命名。
將Dashboard name（儀表盤名稱）更改為“Prisma Metrics Dashboard”並點選Save（儲存）。