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 如何与数据库交互。指标暴露了一组计数器 (counters)、仪表盘 (gauges) 和直方图 (histograms)，它们提供了关于 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 可视化指标。

注意：指标通常与跟踪 (tracing)结合使用，以获得系统的精细概览。要了解更多关于跟踪的信息，请参阅我们的跟踪教程。

将使用的技术

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

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 功能标志

注意：您可能已经注意到，此 schema 中已启用了另一个名为 interactiveTransactions 的预览功能。这在应用程序内部用于执行数据库事务。

现在，重新生成 Prisma Client

启用指标功能后，Prisma 将允许您使用 prisma.$metrics API 检索有关数据库操作的指标。您可以以JSON 格式或Prometheus 格式暴露指标。

从 Web 服务器暴露指标

在本节中，您将从您的 Express Web 服务器暴露数据库指标。为此，您将创建一个新的端点 GET /metrics，它将以 Prometheus 格式返回指标。

要实现 GET /metrics 端点，将以下路由添加到 server.ts

确保服务器正在运行，然后访问 http://localhost:4000/metrics 查看生成的指标。

注意：您可以通过运行 npm run dev 启动服务器。

Metrics in Prometheus format

注意：您也可以使用 prisma.$metrics.json() 以 JSON 格式检索指标。您可以在文档中阅读更多关于 JSON 格式的信息。

集成 Prometheus

在本节中，您将学习如何配置 Prometheus 并将其集成到您的应用程序中。Prometheus 通过定期从特定端点请求数据来收集指标。您将配置 Prometheus 从 http://localhost:4000/metrics 端点抓取指标数据。

创建 Prometheus 配置文件

首先，在项目根目录创建一个名为 prometheus 的新文件夹。然后，在该文件夹中创建一个名为 prometheus.yml 的新文件。

使用 Prometheus 的配置更新文件

需要记住的一些重要选项是

job_name 是用于标识来自特定配置的指标的元数据。
scrape_interval 是 Prometheus 抓取指标端点的间隔。
targets 包含要抓取的端点列表。Prometheus 默认会抓取 /metrics 端点。因此无需明确提及。

注意：host.docker.internal 是一个特殊的 DNS 名称，它解析为运行 Docker 的主机机器的内部 IP 地址。由于 Prometheus 在 Docker 内部运行，使用这个特殊的 DNS 名称可以解析主机机器（您的计算机）的 http://localhost。

启动一个 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 选项来实现。打开一个新的终端窗口并运行以下命令

如果命令成功，您应该可以在 http://localhost: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

您看到的界面称为表达式浏览器 (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，以便它可以从 Prometheus 收集您应用程序的监控数据。然后，您将创建一个能够有意义地表示系统暴露的各种指标的看板。

完全配置后，您的应用程序将如下所示

Application architecture with Prometheus and Grafana

注意：Web 应用程序通常有一个使用 Web 服务器 API 的前端（客户端）。但是，本教程不包含前端以避免不必要的复杂性。

启动一个 Grafana 实例

要启动 Grafana 实例，您需要将新的 grafana 镜像添加到您的 docker-compose.yml 文件。将 docker-compose.yml 的当前内容替换为以下配置

grafana 镜像配置为使用名为 grafana-storage 的卷来存储数据。该卷将用于在重启后持久化 Grafana 的数据。grafana 镜像还配置为将端口 3000 暴露给主机机器，您可以使用该端口访问 Grafana UI。

通过运行以下命令再次重启容器

如果您访问 http://localhost:3000，您将看到 Grafana 登录屏幕。默认用户名和密码都是 admin，您可以使用它们登录。您可以跳过创建新密码。

您现在应该会看到 Grafana 登陆页面。

Grafana landing page

向 Grafana 添加 Prometheus 数据源

您需要向 Grafana 添加一个数据源 (data source)。数据源是 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 看板

一个看板 (dashboard) 是可视化集合，用于表示指标数据。看板由一个或多个面板 (panels) 组成，面板是 Grafana 中基本的可视化构建块。

注意：在开始之前，您应该运行 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 查询 vs. Datasource 查询”。
点击顶部的保存 (Save)，系统将要求您命名看板。
将看板名称 (Dashboard name) 更改为“Prisma 指标看板”，然后点击保存 (Save)。