跳至主要内容

指标

Prisma Client 指标让您能够详细了解 Prisma Client 如何与您的数据库交互。您可以使用此洞察来帮助诊断应用程序的性能问题。

metrics 预览功能已移除

metrics 预览功能已在 Prisma ORM v7.0.0 时被移除。

如果您需要查询或连接池行为的可视性，我们建议使用数据库驱动程序提供的原生指标（例如，池统计数据）或设置OpenTelemetry以获得更完整的可观测性解决方案。

关于指标​

您可以以 JSON 或 Prometheus 格式导出指标并在控制台日志中查看，或将它们集成到外部指标系统，例如 StatsD 或 Prometheus。如果将它们集成到外部指标系统，则可以随时间查看指标数据。例如，您可以使用指标来帮助诊断应用程序的空闲和活动连接数如何变化。

Prisma Client 提供以下指标

  • 计数器（总是增加）

    • prisma_client_queries_total：执行的 Prisma Client 查询总数。
    • prisma_datasource_queries_total：执行的数据源查询总数（关系数据库中的 SQL 查询，以及 MongoDB 中的命令）。
      • prisma_datasource_queries_total 返回的值可能大于 prisma_client_queries_total，因为某些 Prisma Client 操作会创建多个查询。
    • prisma_pool_connections_closed_total：关闭的连接池连接总数。
    • prisma_pool_connections_opened_total：当前打开的连接池连接数。

  • 仪表（可增可减）

    • prisma_client_queries_active：当前活动的 Prisma Client 查询数。
    • prisma_client_queries_wait：由于所有连接都在使用中而当前等待连接的 Prisma Client 查询数。
    • prisma_pool_connections_busy：当前忙碌的连接池连接数。这些连接池连接当前正在执行数据源查询。/* 省略 53-55 行 */

  • 直方图（指标数据分为一系列值；我们称集合中的每个容器为“桶”）：/* 省略 57-61 行 */

您可以为指标数据添加全局标签，以帮助您对指标进行分组和分离，例如按基础设施区域或服务器。

先决条件​

要使用 Prisma Client 指标，您必须执行以下操作

  1. 安装兼容的 Prisma ORM 依赖项.
  2. 在 Prisma schema 文件中启用 metrics 功能标志.

1. 安装最新的 Prisma ORM 依赖项​

您必须使用版本介于 3.15.0 和 6.13.x 之间的 prisma 和 @prisma/client npm 包。

安装兼容版本

npm install prisma@6.13.0 --save-dev
npm install @prisma/client@6.13.0

或使用保持在兼容范围内的版本范围

npm install prisma@">=3.15.0 <6.14.0" --save-dev
npm install @prisma/client@">=3.15.0 <6.14.0"

2. 在 Prisma schema 文件中启用功能标志​

在 schema.prisma 文件的 generator 块中，启用 metrics 功能标志

generator client {
  provider        = "prisma-client"
  output          = "./generated"
  previewFeatures = ["metrics"]
}

以 JSON 格式检索指标​

当您以 JSON 格式检索指标时，您可以直接使用返回的格式，或者将它们发送到 StatSD 以可视化它们随时间的变化。

要以 JSON 格式检索指标，请将以下行添加到您的应用程序代码中

const metrics = await prisma.$metrics.json()
console.log(metrics)

这将返回如下指标

{/* Lines 121-154 omitted */}
展开查看完整输出
{/* Lines 163-280 omitted */}

JSON 数据中的直方图​

每个直方图“桶”有两个值。第一个是桶的上限，第二个是计数（落入该桶的数据值数量）。在以下示例中，有 11 到 20 之间的两个值实例，以及 21 到 30 之间的五个值实例

...
[20, 2],
[30, 5],
...

将 Prisma Client 指标与 StatsD 结合使用​

您可以将 JSON 格式的指标发送到 StatsD，以随时间可视化您的指标数据。

信息

注意：您必须将计数器指标作为一系列值提供给 StatsD，这些值从上次检索指标时递增或递减。然而，Prisma Client 的计数器指标返回绝对值。因此，您必须将计数器指标转换为一系列递增和递减的值，并将其作为仪表数据发送到 StatsD。在下面的代码示例中，我们在 diffHistograms 中将计数器指标转换为递增和递减的仪表数据。

在以下示例中，我们每 10 秒向 StatsD 发送一次指标。此时间与 StatsD 的默认 10 秒刷新率一致。

import StatsD from 'hot-shots'
let statsd = new StatsD({
  port: 8125,
})

const diffMetrics = (metrics: Metric<MetricHistogram>[]) => {/* Lines 316-331 omitted */}

let previousHistograms: Metric<MetricHistogram>[] = []


const statsdSender = async () => {/* Lines 337-369 omitted */}

setInterval(async () => await statsdSender(), 10000)

以 Prometheus 格式检索指标​

当您以 Prometheus 格式检索 Prisma Client 指标时，您可以直接使用返回的格式，或者将它们发送到 Prometheus 指标系统，以可视化它们随时间的变化。

要以 Prometheus 格式检索指标，请将以下行添加到您的应用程序代码中

const metrics = await prisma.$metrics.prometheus()
console.log(metrics)

这将返回如下指标

# HELP prisma_client_queries_total Total number of Prisma Client queries executed
# TYPE prisma_client_queries_total counter
prisma_client_queries_total 14

...
# HELP prisma_pool_connections_busy The number of active connections in use.
# TYPE prisma_pool_connections_busy gauge
prisma_pool_connections_busy 0

...
# HELP prisma_client_queries_wait_histogram_ms The wait time for a worker to get a connection.
# TYPE prisma_client_queries_wait_histogram_ms histogram
prisma_client_queries_wait_histogram_ms_bucket{le="0"} 0
prisma_client_queries_wait_histogram_ms_bucket{le="1"} 3
展开查看完整输出
# HELP query_total_operations
# TYPE query_total_operations counter
query_total_operations 2

# HELP prisma_datasource_queries_total
# TYPE prisma_datasource_queries_total counter
prisma_datasource_queries_total 28

# HELP prisma_pool_connections_closed_total Total number of Pool Connections closed
# TYPE prisma_pool_connections_closed_total counter
prisma_pool_connections_closed_total 0

# HELP prisma_pool_connections_opened_total Total number of Pool Connections opened
# TYPE prisma_pool_connections_opened_total counter
prisma_pool_connections_opened_total 0

# HELP prisma_client_queries_active Number of currently active Prisma Client queries
# TYPE prisma_client_queries_active gauge
prisma_client_queries_active 0

# HELP prisma_client_queries_wait Number of queries currently waiting for a connection
# TYPE prisma_client_queries_wait gauge
prisma_client_queries_wait 0

# HELP prisma_pool_connections_busy Number of currently busy Pool Connections (executing a datasource query)
# TYPE prisma_pool_connections_busy gauge
prisma_pool_connections_busy 0

# HELP prisma_pool_connections_idle Number of currently unused Pool Connections (waiting for the next pool query to run)
# TYPE prisma_pool_connections_idle gauge
prisma_pool_connections_idle 21

# HELP prisma_pool_connections_open Number of currently open Pool Connections
# TYPE prisma_pool_connections_open gauge
prisma_pool_connections_open 1

# HELP prisma_pool_connections_open Number of currently open Pool Connections (able to execute a datasource query)
# TYPE prisma_pool_connections_open gauge
prisma_pool_connections_open 0

# HELP prisma_client_queries_wait_histogram_ms The wait time for a worker to get a connection.
# TYPE prisma_client_queries_wait_histogram_ms histogram
prisma_client_queries_wait_histogram_ms_bucket{le="0"} 0
prisma_client_queries_wait_histogram_ms_bucket{le="1"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="5"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="10"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="50"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="100"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="500"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="1000"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="5000"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="50000"} 3
prisma_client_queries_wait_histogram_ms_bucket{le="+Inf"} 3
prisma_client_queries_wait_histogram_ms_sum 0.023208
prisma_client_queries_wait_histogram_ms_count 3

# HELP prisma_client_queries_duration_histogram_ms Histogram of the duration of all executed Prisma Client queries in ms
# TYPE prisma_client_queries_duration_histogram_ms histogram
prisma_client_queries_duration_histogram_ms_bucket{le="0"} 0
prisma_client_queries_duration_histogram_ms_bucket{le="1"} 1
prisma_client_queries_duration_histogram_ms_bucket{le="5"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="10"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="50"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="100"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="500"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="1000"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="5000"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="50000"} 2
prisma_client_queries_duration_histogram_ms_bucket{le="+Inf"} 2
prisma_client_queries_duration_histogram_ms_sum 3.197624
prisma_client_queries_duration_histogram_ms_count 2

# HELP prisma_datasource_queries_duration_histogram_ms Histogram of the duration of all executed Datasource Queries in ms
# TYPE prisma_datasource_queries_duration_histogram_ms histogram
prisma_datasource_queries_duration_histogram_ms_bucket{le="0"} 0
prisma_datasource_queries_duration_histogram_ms_bucket{le="1"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="5"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="10"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="50"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="100"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="500"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="1000"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="5000"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="50000"} 5
prisma_datasource_queries_duration_histogram_ms_bucket{le="+Inf"} 5
prisma_datasource_queries_duration_histogram_ms_sum 1.8407059999999997
prisma_datasource_queries_duration_histogram_ms_count 5

histogram 类型的指标以 Prometheus 格式公开三种不同类别的值

  1. 用于观察桶的多个累积计数器。这些计数器以 _bucket{le="<upper inclusive bound>"} 为后缀。例如，prisma_datasource_queries_duration_histogram_ms 有一个计数器公开为 prisma_datasource_queries_duration_histogram_ms_bucket{le="1"} /* 省略 502-504 行 */

  2. 所有观察到的值的单个总和。此计数器以 _sum 为后缀。例如，prisma_datasource_queries_duration_histogram_ms 的总和公开为 prisma_datasource_queries_duration_histogram_ms_sum。

  3. 已观察到的事件的计数。此计数器以 _count 为后缀。例如，prisma_datasource_queries_duration_histogram_ms 事件的总计数公开为 prisma_datasource_queries_duration_histogram_ms_count。

有关更多信息，请阅读 Prometheus 文档中关于指标类型。

将 Prisma Client 指标与 Prometheus 指标系统结合使用​

在大多数情况下，Prometheus 必须抓取一个端点才能检索指标。以下示例展示了如何使用 Express.js 发送数据

import { PrismaClient } from '../prisma/generated/client'
import express, { Request, Response } from 'express'

const app = express()
const port = 4000
const prisma = new PrismaClient()

app.get('/metrics', async (_req, res: Response) => {
  /* Lines 523-524 omitted */
  res.end(metrics)
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

以下示例展示了如何将 Prisma Client 指标与其他 Prometheus 客户端库结合使用，这些库也与 Express.js 结合使用 REST API 端点提供服务

import { PrismaClient } from '../prisma/generated/client'
import express, { Request, Response } from 'express'
import prom from 'prom-client'

const app = express()
const port = 4000
const prisma = new PrismaClient()

const register = new prom.Registry()
prom.collectDefaultMetrics({ register })

app.get('/metrics', async (_req, res: Response) => {
  /* Lines 547-549 omitted */
  res.end(prismaMetrics + appMetrics)
})

app.listen(port, () => {
  console.log(`Example app listening on port ${port}`)
})

全局标签​

您可以为指标添加全局标签，以帮助您对指标进行分组和分离。Prisma Client 的每个实例都会将这些标签添加到其生成的指标中。例如，您可以使用 { server: us_server1', 'app_version': 'one' } 这样的标签按基础设施区域或按服务器对指标进行分组。

全局标签适用于 JSON 和 Prometheus 格式的指标。

例如，要为 JSON 格式的指标添加全局标签，请将以下代码添加到您的应用程序中

const metrics = prisma.$metrics.json({
  globalLabels: { server: 'us_server1', app_version: 'one' },
})
console.log(metrics)

这将返回以下格式的信息

{/* Lines 576-599 omitted */}
打开方式
复制为 Markdown
在 Claude 中打开
在 ChatGPT 中打开
在 T3.chat 中打开
在 GitHub 中编辑
© . This site is unofficial and not affiliated with Prisma Data, Inc.