使用 Prisma、Prometheus 和 Grafana 的数据库指标

目录

• 简介
  • 什么是指标？
  • 您将使用的技术
• 先决条件
  • 假定知识
  • 开发环境
• 克隆存储库
  • 项目结构和文件
• 将指标集成到您的应用程序中
  • 在 Prisma Client 中启用指标
  • 从您的 Web 服务器公开指标
• 集成 Prometheus
  • 创建 Prometheus 配置文件
  • 启动一个 Prometheus 实例
  • 在 Prometheus UI 中探索指标
• 使用 Grafana 可视化指标
  • 启动一个 Grafana 实例
  • 将 Prometheus 数据源添加到 Grafana
  • 创建您的第一个 Grafana 仪表盘
  • （可选）导入现有 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 应用程序。

要开始，请执行以下操作

1. 克隆存储库

2. 导航到克隆的目录

3. 安装依赖

4. 使用 Docker 在端口 5432 上启动 PostgreSQL 数据库

注意：如果您关闭运行 Docker 容器的终端窗口，它也会停止容器。您可以通过在命令末尾添加 -d 选项来避免这种情况，例如：docker-compose up -d。

5. 从 prisma/migrations 目录应用数据库迁移

注意：此命令还将生成 Prisma Client 并为数据库填充数据。

6. 启动服务器

注意：在开发应用程序时，您应该保持服务器运行。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

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

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

注意：您还可以使用 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 中探索指标

在Expression（表达式）输入字段中，您可以输入一个PromQL（Prometheus 查询语言）查询来检索指标数据。例如，您可以输入 prisma_client_queries_total 来查看 Prisma Client 执行的查询数量。输入查询后，点击Execute（执行）按钮查看结果。

注意：您可能会看到响应Empty query result（空查询结果）而不是实际值。这也没关系——继续下一步。

您正在看到的界面被称为表达式浏览器。它允许您以表格或图形格式查看任何 PromQL 表达式的结果。

目前，查询数量为 0 或为空，因为您尚未发出任何 API 请求。为了避免手动发出大量请求来生成指标数据，您将使用负载测试工具 k6。项目中已提供一个名为 loadtest.js 的负载测试脚本。您可以通过执行以下命令来运行此脚本

此命令将首先拉取 k6 Docker 镜像，然后开始向您的 Express API 发出大量请求。在 k6 开始发出请求后，您可以返回 Prometheus UI 并再次执行之前的查询。您现在应该会看到查询数量迅速增加。

Prometheus UI 还提供了一种以时间序列图形式查看指标的方式。您可以通过点击Graph（图形）选项卡来完成此操作。在Expression（表达式）输入字段中，输入与之前相同的查询，然后点击Execute（执行）按钮。您应该会看到一个图表，显示 Prisma Client 随时间执行的查询数量。

注意：请随意在 Prometheus UI 中尝试其他查询。您可以在Prisma 文档中找到所有可用指标的列表。您还可以通过阅读Prometheus 文档了解如何执行更复杂的 PromQL 查询。

Prometheus 表达式浏览器是一个用于快速可视化临时查询的有用工具。但它不是一个功能齐全的可视化工具。Prometheus 通常与Grafana搭配使用，Grafana 是一个功能丰富且强大的可视化和分析工具。

使用 Grafana 可视化指标

在本节中，您将学习如何设置 Grafana 并使用它创建可视化指标数据的仪表盘。Grafana 是一款流行的开源可视化工具，广泛用于监控和可视化。

您将首先集成 Grafana，使其能够从 Prometheus 收集应用程序的监控数据。然后，您将创建一个仪表盘，有意义地表示系统暴露的各种指标。

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

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

启动一个 Grafana 实例

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

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

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

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

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

将 Prometheus 数据源添加到 Grafana

您需要向 Grafana 添加一个数据源。数据源是 Grafana 可以查询以检索指标数据的外部系统。在这种情况下，您的数据源将是 Prometheus。

要通过 UI 添加数据源，请执行以下操作

1. 点击侧边菜单左下角的齿轮图标。
2. 在Data sources（数据源）配置窗口中，点击Add data source（添加数据源）。
3. 点击Prometheus作为数据源类型。
4. 在 Prometheus 数据源配置页面中，将URL设置为 http://prometheus:9090，将Scrape Interval（抓取间隔）设置为 1s。http://prometheus:9090 将解析到 prometheus 容器上的端口 9090。这得益于 Docker Compose 自动配置的Docker 网络。
5. 点击Save & test（保存并测试）以保存配置。

如果一切配置正确，您应该会看到Data source is working（数据源工作正常）消息。

创建您的第一个 Grafana 仪表盘

一个仪表盘是表示指标数据的可视化集合。仪表盘由一个或多个面板组成，面板是 Grafana 中基本的 Visualization Building Block（可视化构建块）。

注意：在开始之前，您应该通过运行 npm run loadtest 来生成一些流量，以便有数据可供可视化。

要创建您的第一个仪表盘，请执行以下操作

1. 点击侧边菜单中Dashboards（仪表盘）图标下的+ New dashboard（新建仪表盘）选项。
2. 在仪表盘上，点击Add a new panel（添加新面板）以进入面板编辑器。Query（查询）选项卡中的Data source（数据源）应该已经设置为Prometheus。
3. 在Query（查询）选项卡内，在Metric（指标）输入框中填写 prisma_client_queries_total。
4. 按下+ Query（查询）按钮，并在新的Metric（指标）中添加 prisma_datasource_queries_total。
5. 在右侧边栏中，将Title（标题）字段从Panel Title（面板标题）更改为“Prisma Client Queries vs. Datasource Queries”。
6. 点击顶部的Save（保存），系统会要求您为仪表盘命名。
7. 将Dashboard name（仪表盘名称）更改为“Prisma Metrics Dashboard”并点击Save（保存）。

prisma_client_queries_total 表示执行的 Prisma Client 查询总数。prisma_datasource_queries_total 表示在数据源级别执行的数据库查询总数。这两个指标在同一张图表中可视化，方便您进行比较。

恭喜！您刚刚创建了一个仪表盘，用于可视化 Prisma Client 和 Prisma Datasource 发出的查询数量。您的仪表盘现在应该可以在 Grafana 内部访问了。

注意：您应该探索 Grafana 提供的不同功能。例如，您可以向仪表盘添加更多面板、更改可视化类型、添加注释等。您还可以使用 Grafana 设置自动化警报来监控您的系统。更多信息可在Grafana 文档中找到。

（可选）导入现有 Grafana 仪表盘

在上一节中，您创建了一个只有一个面板的仪表盘。在本节中，您将导入一个包含多个面板的现有仪表盘。要导入仪表盘，请执行以下操作

1. 点击侧边菜单中Dashboards（仪表盘）图标下的+ Import（导入）选项。
2. 将此 JSON 文件复制粘贴到Import via panel json（通过面板 JSON 导入）输入字段中。
3. 点击Load（加载）按钮，然后点击Import（导入）。

您现在应该会看到一个包含多个面板的仪表盘。您可以探索不同的面板，并查看它们可视化的指标。

总结

在本教程中，您学习了

• 什么是指标，以及为什么应该使用它。
• 如何将数据库指标与 Prisma 集成到现有 Web 应用程序中。
• 如何使用 Prometheus 收集和查询指标数据。
• 如何使用 Grafana 可视化指标数据。

如需进一步阅读，您可以查阅以下资源

• Prisma 指标文档
• Prisma 追踪教程
• Prometheus 文档
• Grafana 文档

我们非常乐意听到您对指标功能的看法！请在此Github issue上提供关于指标的反馈。

您可以在 GitHub 上找到该项目的源代码。如果您发现问题，请随时在存储库中提出 issue 或提交 PR。您也可以直接在 Twitter 上联系我。