指標

Prisma Client 指標讓您深入了解 Prisma Client 如何與您的資料庫互動。您可以使用此洞察來協助診斷應用程式的效能問題。

資訊

如果您想要更深入了解 Prisma Client 的效能，達到個別操作的層級，請參閱追蹤。

關於指標

您可以匯出 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：目前忙碌中的連線池連線數。這些連線池連線目前正在執行資料來源查詢。
  • prisma_pool_connections_idle：目前未使用的連線池連線數。這些連線池連線正在等待下一個要執行的資料來源查詢。
  • prisma_pool_connections_open：連線池連線的開啟數量。

• 直方圖 (指標資料分為值的集合；我們將集合中的每個容器稱為「bucket」)

  • prisma_client_queries_wait_histogram_ms：所有 Prisma Client 查詢等待連線池連線的時間 (毫秒)。
  • prisma_client_queries_duration_histogram_ms：所有已執行 Prisma Client 查詢的執行時間 (毫秒)。這包括執行所有資料庫查詢以及執行所有資料庫引擎活動 (例如聯結資料和將資料轉換為正確格式) 所花費的時間。
  • prisma_datasource_queries_duration_histogram_ms：所有已執行資料來源查詢的執行時間 (毫秒)。

您可以將全域標籤新增至您的指標資料，以協助您分組和分隔指標，例如依基礎架構區域或伺服器。

先決條件

若要使用 Prisma Client 指標，您必須執行以下操作

1. 安裝適當的相依性.
2. 在您的 Prisma schema 檔案中啟用 metrics 功能旗標.

1. 安裝最新的 Prisma ORM 相依性

使用 prisma 和 @prisma/client npm 套件的 3.15.0 或更高版本。

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

2. 在 Prisma schema 檔案中啟用功能旗標

在您的 schema.prisma 檔案的 generator 區塊中，啟用 metrics 功能旗標

generator client {
  provider        = "prisma-client-js"
  previewFeatures = ["metrics"]
}

以 JSON 格式擷取指標

當您以 JSON 格式擷取指標時，您可以直接使用傳回的格式，或將它們傳送到 StatSD，以視覺化它們隨時間的變化。

若要以 JSON 格式擷取指標，請將以下程式碼行新增至您的應用程式碼

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

這會傳回如下的指標

{
  "counters": [
    {
      "key": "prisma_client_queries_total",
      "labels": {},
      "value": 0,
      "description": "Total number of Prisma Client queries executed"
    },
    {
      "key": "prisma_datasource_queries_total",
      "labels": {},
      "value": 0,
      "description": "Total number of Datasource Queries executed"
    },
    {
      "key": "prisma_pool_connections_closed_total",
      "labels": {},
      "value": 0,
      "description": "Total number of Pool Connections closed"
    },
    {
      "key": "prisma_pool_connections_opened_total",
      "labels": {},
      "value": 1,
      "description": "Total number of Pool Connections opened"
    }
    ...
  ],
  "gauges": [
    ...
  ],
  "histograms": [
    ...
  ]
}

展開以檢視完整輸出

{
  "counters": [
    {
      "key": "prisma_client_queries_total",
      "labels": {},
      "value": 2,
      "description": "Total number of Prisma Client queries executed"
    },
    {
      "key": "prisma_datasource_queries_total",
      "labels": {},
      "value": 5,
      "description": "Total number of Datasource Queries executed"
    },
    {
      "key": "prisma_pool_connections_open",
      "labels": {},
      "value": 1,
      "description": "Number of currently open Pool Connections"
    }
  ],
  "gauges": [
    {
      "key": "prisma_client_queries_active",
      "labels": {},
      "value": 0,
      "description": "Number of currently active Prisma Client queries"
    },
    {
      "key": "prisma_client_queries_wait",
      "labels": {},
      "value": 0,
      "description": "Number of Prisma Client queries currently waiting for a connection"
    },
    {
      "key": "prisma_pool_connections_busy",
      "labels": {},
      "value": 0,
      "description": "Number of currently busy Pool Connections (executing a datasource query)"
    },
    {
      "key": "prisma_pool_connections_idle",
      "labels": {},
      "value": 21,
      "description": "Number of currently unused Pool Connections (waiting for the next datasource query to run)"
    },
    {
      "key": "prisma_pool_connections_open",
      "labels": {},
      "value": 1,
      "description": "Number of currently open Pool Connections"
    }
  ],
  "histograms": [
    {
      "key": "prisma_client_queries_duration_histogram_ms",
      "labels": {},
      "value": {
        "buckets": [
          [0, 0],
          [1, 0],
          [5, 0],
          [10, 1],
          [50, 1],
          [100, 0],
          [500, 0],
          [1000, 0],
          [5000, 0],
          [50000, 0]
        ],
        "sum": 47.430541000000005,
        "count": 2
      },
      "description": "Histogram of the duration of all executed Prisma Client queries in ms"
    },
    {
      "key": "prisma_client_queries_wait_histogram_ms",
      "labels": {},
      "value": {
        "buckets": [
          [0, 0],
          [1, 3],
          [5, 0],
          [10, 0],
          [50, 0],
          [100, 0],
          [500, 0],
          [1000, 0],
          [5000, 0],
          [50000, 0]
        ],
        "sum": 0.0015830000000000002,
        "count": 3
      },
      "description": "Histogram of the wait time of all Prisma Client Queries in ms"
    },
    {
      "key": "prisma_datasource_queries_duration_histogram_ms",
      "labels": {},
      "value": {
        "buckets": [
          [0, 0],
          [1, 0],
          [5, 2],
          [10, 2],
          [50, 1],
          [100, 0],
          [500, 0],
          [1000, 0],
          [5000, 0],
          [50000, 0]
        ],
        "sum": 47.134498,
        "count": 5
      },
      "description": "Histogram of the duration of all executed Datasource Queries in ms"
    }
  ]
}

JSON 資料中的直方圖

每個直方圖「bucket」都有兩個值。第一個是 bucket 的上限，第二個是計數 (落在該 bucket 中的資料值數量)。在以下範例中，有兩個值介於 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>[]) => {
  return metrics.map((metric) => {
    let prev = 0;

    const diffBuckets = metric.value.buckets.map<MetricHistogramBucket>(
      (values) => {
        const [bucket, value] = values
        const diff = value - prev
        prev = value
        return [bucket, diff]
      }
    )

    metric.value.buckets = diffBuckets
    return metric
  })
}

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


const statsdSender = async () => {
  const metrics = await prisma.$metrics.json()
  
  metrics.counters.forEach((counter: any) => {
    statsd.gauge('prisma.' + counter.key, counter.value, (...res) => {})
  });

  metrics.gauges.forEach((counter: any) => {
    statsd.gauge('prisma.' + counter.key, counter.value, (...res) => {})
  })

  if (!previousHistograms.length) {
    previousHistograms = diffMetrics(metrics.histograms)

    return
  }

  const diffHistograms = diffMetrics(metrics.histograms);

  diffHistograms.forEach((diffHistogram, histogramIndex) => {
    diffHistogram.value.buckets.forEach((values, bucketIndex) => {
      const [bucket, count] = values
      const [_, prev] =
        previousHistograms[histogramIndex].value.buckets[bucketIndex]
      const change = count - prev

      for (let sendTimes = 0; sendTimes < change; sendTimes++) {
        statsd.timing('prisma.' + diffHistograms.key, bucket)
      }
    })
  })

  previousHistograms = diffHistograms
}

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 的累計計數器。這些計數器的後綴為 _bucket{le="<上限內含邊界>"}。例如，prisma_datasource_queries_duration_histogram_ms 有一個計數器公開為 prisma_datasource_queries_duration_histogram_ms_bucket{le="1"}

   當觀察到的值小於或等於 bucket 的上限內含邊界時，Prisma Client 指標會將該 bucket 遞增 1。假設您的 bucket 的上限內含邊界分別為 0、1、5、10 和 50。如果觀察到的值為 5，則 Prisma Client 指標會從第三個 bucket 開始遞增，因為該值大於 0 且大於 1，但小於或等於 5、10 和 50。

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/client'
import express, { Request, Response } from 'express'

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

app.get('/metrics', async (_req, res: Response) => {
  const metrics = await prisma.$metrics.prometheus()
  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/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) => {
  const prismaMetrics = await prisma.$metrics.prometheus()
  const appMetrics = await register.metrics()
  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)

這會傳回以下格式的資訊

{
  "counters": [
    {
      "key": "query_total_operations",
      "labels": { "server": "us_server1", "app_version": "one" },
      "value": 0,
      "description": "The total number of operations executed"
    },
    {
      "key": "prisma_datasource_queries_total",
      "labels": { "server": "us_server1", "app_version": "one" },
      "value": 0,
      "description": "The total number of queries executed"
    },
    ...
  ],
  "gauges": [
    ...
  ],
  "histograms": [
    ...
  ]
}