OpenTelemetry 追踪

追踪提供了 Prisma Client 执行的操作的详细日志，操作级别包括执行每个查询所花费的时间。它可以帮助您分析应用程序的性能并识别瓶颈。追踪完全符合 OpenTelemetry，因此您可以将其用作端到端应用程序追踪系统的一部分。

信息

追踪为您提供对 Prisma ORM 项目的高度详细的操作级洞察。如果您想要聚合的数值报告，例如查询计数、连接计数和总查询执行时间，请参阅指标。

关于追踪

当您启用追踪时，Prisma Client 输出以下内容

• Prisma Client 执行的每个操作（例如 findMany）的一个追踪。
• 在每个追踪中，一个或多个span。每个 span 代表操作的一个阶段所花费的时间长度，例如序列化或数据库查询。Span 以树状结构表示，其中子 span 表示执行发生在更大的父 span 内。

追踪中的 span 数量和类型取决于追踪涵盖的操作类型，但一个示例如下

您可以将追踪输出发送到控制台，或在任何 OpenTelemetry 兼容的追踪系统中分析它，例如 Jaeger、Honeycomb 和 Datadog。在本页中，我们提供了一个如何将追踪输出发送到 Jaeger 的示例，您可以在本地运行。

追踪输出

对于每个追踪，Prisma Client 输出一系列 span。这些 span 的数量和类型取决于 Prisma Client 操作。典型的 Prisma 追踪具有以下 span

• prisma:client:operation：表示整个 Prisma Client 操作，从 Prisma Client 到数据库再返回。它包含诸如 Prisma Client 调用的模型和方法之类的详细信息。根据 Prisma 操作，它包含以下一个或多个 span
  • prisma:client:connect：表示 Prisma Client 连接到数据库所需的时间。
  • prisma:client:serialize：表示验证和转换 Prisma Client 操作为 查询引擎 的查询所需的时间。
  • prisma:engine:query：表示查询在查询引擎中花费的时间。
    • prisma:engine:connection：表示 Prisma Client 获取数据库连接所需的时间。
    • prisma:engine:db_query：表示针对数据库执行的数据库查询。它在标签中包含查询，以及查询运行所需的时间。
    • prisma:engine:serialize：表示将来自数据库的原始响应转换为类型化结果所需的时间。
    • prisma:engine:response_json_serialization：表示将数据库查询结果序列化为 Prisma Client 的 JSON 响应所需的时间。

例如，给定以下 Prisma Client 代码

prisma.user.findMany({
  where: {
    email: email,
  },
  include: {
    posts: true,
  },
})

追踪结构如下

• prisma:client:operation
  • prisma:client:serialize
  • prisma:engine:query
    • prisma:engine:connection
    • prisma:engine:db_query：第一个 SQL 查询或命令的详细信息...
    • prisma:engine:db_query：...下一个 SQL 查询或命令的详细信息...
    • prisma:engine:serialize
    • prisma:engine:response_json_serialization

注意事项和先决条件

如果您的应用程序向收集器发送大量 span，这可能会对性能产生重大影响。有关如何最大限度地减少这种影响的信息，请参阅减少性能影响。

要使用追踪，您必须执行以下操作

1. 安装适当的依赖项.
2. 安装 OpenTelemetry 包.
3. 在您的应用程序中注册追踪.

开始在 Prisma ORM 中使用追踪

本节介绍如何在您的应用程序中安装和注册追踪。

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

使用版本 6.1.0 或更高版本的 prisma、@prisma/client 和 @prisma/instrumentation npm 包。您还需要安装 @opentelemetry/api 包，因为它是一个对等依赖项。

npm install prisma@latest --save-dev
npm install @prisma/client@latest --save
npm install @prisma/instrumentation@latest --save
npm install @opentelemetry/api@latest --save

先前版本的 Prisma ORM 上的追踪

追踪在 Prisma ORM 的 4.2.0 版本中作为预览功能添加。对于 4.2.0 和 6.1.0 之间的 Prisma ORM 版本，您需要在 Prisma schema 文件中启用 tracing 预览功能。

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

步骤 2：安装 OpenTelemetry 包

现在安装适当的 OpenTelemetry 包，如下所示

npm install @opentelemetry/semantic-conventions @opentelemetry/exporter-trace-otlp-http @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node @opentelemetry/resources

步骤 3：在您的应用程序中注册追踪

以下代码提供了在 Prisma 中配置 OpenTelemetry 追踪的两个示例

1. 使用 @opentelemetry/sdk-trace-node（现有示例），它提供了对追踪设置的细粒度控制。
2. 使用 @opentelemetry/sdk-node，它提供了更简单的配置，并与 OpenTelemetry 的 JavaScript 入门指南保持一致。

---

选项 1：使用 @opentelemetry/sdk-trace-node

此设置使您可以对仪表和追踪进行细粒度控制。您需要为您的特定应用程序自定义此配置。此方法简洁明了，对于需要快速设置以将追踪发送到 OTLP 兼容后端（例如 Honeycomb、Jaeger 或 Datadog）的用户来说更容易。

// Imports
import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } from '@opentelemetry/semantic-conventions'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
import { PrismaInstrumentation, registerInstrumentations } from '@prisma/instrumentation'
import { Resource } from '@opentelemetry/resources'

// Configure the trace provider
const provider = new NodeTracerProvider({
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: 'example application', // Replace with your service name
    [SEMRESATTRS_SERVICE_VERSION]: '0.0.1', // Replace with your service version
  }),
})

// Configure how spans are processed and exported. In this case, we're sending spans
// as we receive them to an OTLP-compatible collector (e.g., Jaeger).
provider.addSpanProcessor(new SimpleSpanProcessor(new OTLPTraceExporter()))

// Register your auto-instrumentors
registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [new PrismaInstrumentation()],
})

// Register the provider globally
provider.register()

此方法提供了最大的灵活性，但可能涉及额外的配置步骤。

选项 2：使用 @opentelemetry/sdk-node

对于许多用户，尤其是初学者，NodeSDK 类通过将常见默认值捆绑到单个统一配置中，简化了 OpenTelemetry 的设置。

// Imports
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { NodeSDK } from '@opentelemetry/sdk-node'
import { PrismaInstrumentation } from '@prisma/instrumentation'

// Configure the OTLP trace exporter
const traceExporter = new OTLPTraceExporter({
  url: 'https://api.honeycomb.io/v1/traces', // Replace with your collector's endpoint
  headers: {
    'x-honeycomb-team': 'HONEYCOMB_API_KEY', // Replace with your Honeycomb API key or collector auth header
  },
})

// Initialize the NodeSDK
const sdk = new NodeSDK({
  serviceName: 'my-service-name', // Replace with your service name
  traceExporter,
  instrumentations: [
    new PrismaInstrumentation({
      middleware: true, // Enable middleware tracing if needed
    }),
  ],
})

// Start the SDK
sdk.start()

// Handle graceful shutdown
process.on('SIGTERM', async () => {
  try {
    await sdk.shutdown()
    console.log('Tracing shut down successfully')
  } catch (err) {
    console.error('Error shutting down tracing', err)
  } finally {
    process.exit(0)
  }
})

如果出现以下情况，请选择 NodeSDK 方法

• 您刚开始使用 OpenTelemetry，并且想要简化的设置。
• 您需要以最少的样板快速集成追踪。
• 您正在使用 OTLP 兼容的追踪后端，如 Honeycomb、Jaeger 或 Datadog。

如果出现以下情况，请选择 NodeTracerProvider 方法

• 您需要详细控制 span 的创建、处理和导出方式。
• 您正在使用自定义 span 处理器或导出器。
• 您的应用程序需要特定的仪表或采样策略。

OpenTelemetry 是高度可配置的。您可以自定义资源属性、要检测的组件、span 的处理方式以及 span 的发送位置。

您可以在此示例应用程序中找到包含指标的完整示例。

追踪操作指南

使用 Jaeger 可视化追踪

Jaeger 是一个免费且开源的 OpenTelemetry 收集器和仪表板，您可以使用它来可视化您的追踪。

以下屏幕截图显示了一个追踪可视化示例

要在本地运行 Jaeger，请使用以下 Docker 命令

docker run --rm --name jaeger -d -e COLLECTOR_OTLP_ENABLED=true -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:latest

您现在可以在 https://127.0.0.1:16686/ 找到可用的追踪仪表板。当您启用追踪使用您的应用程序时，您将开始在此仪表板中看到追踪。

将追踪输出发送到控制台

以下示例使用 @opentelemetry/sdk-trace-base 中的 ConsoleSpanExporter 将输出追踪发送到控制台。

// Imports
import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import {
  BasicTracerProvider,
  ConsoleSpanExporter,
  SimpleSpanProcessor,
} from '@opentelemetry/sdk-trace-base'
import { AsyncHooksContextManager } from '@opentelemetry/context-async-hooks'
import * as api from '@opentelemetry/api'
import { PrismaInstrumentation, registerInstrumentations } from '@prisma/instrumentation'
import { Resource } from '@opentelemetry/resources'

// Export the tracing
export function otelSetup() {
  const contextManager = new AsyncHooksContextManager().enable()

  api.context.setGlobalContextManager(contextManager)

  //Configure the console exporter
  const consoleExporter = new ConsoleSpanExporter()

  // Configure the trace provider
  const provider = new BasicTracerProvider({
    resource: new Resource({
      [SemanticResourceAttributes.SERVICE_NAME]: 'test-tracing-service',
      [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
    }),
  })

  // Configure how spans are processed and exported. In this case we're sending spans
  // as we receive them to the console
  provider.addSpanProcessor(new SimpleSpanProcessor(consoleExporter))

  // Register your auto-instrumentors
  registerInstrumentations({
    tracerProvider: provider,
    instrumentations: [new PrismaInstrumentation()],
  })

  // Register the provider
  provider.register()
}

追踪 Prisma Client 中间件

默认情况下，追踪不输出 Prisma Client 中间件 的 span。要在您的追踪中包含您的中间件，请在您的 registerInstrumentations 语句中将 middleware 设置为 true，如下所示

registerInstrumentations({
  instrumentations: [new PrismaInstrumentation({ middleware: true })],
})

这会将以下 span 类型添加到您的追踪中

• prisma:client:middleware：表示操作在您的中间件中花费的时间。

追踪交互式事务

当您执行交互式事务时，您将看到以下 span，以及标准 span

• prisma:client:transaction：一个根 span，它包装了 prisma span。
  • prisma:engine:itx_runner：表示交互式事务在查询引擎中花费的时间。
  • prisma:engine:itx_query_builder：表示构建交互式事务所需的时间。

作为一个例子，采用以下 Prisma schema

schema.prisma

generator client {
  provider        = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id    Int    @id @default(autoincrement())
  email String @unique
}

model Audit {
  id     Int    @id
  table  String
  action String
}

给定以下交互式事务

await prisma.$transaction(async (tx) => {
  const user = await tx.user.create({
    data: {
      email: email,
    },
  })

  await tx.audit.create({
    data: {
      table: 'user',
      action: 'create',
      id: user.id,
    },
  })

  return user
})

追踪结构如下

• prisma:client:transaction
• prisma:client:connect
• prisma:engine:itx_runner
  • prisma:engine:connection
  • prisma:engine:db_query
  • prisma:engine:itx_query_builder
    • prisma:engine:db_query
    • prisma:engine:db_query
    • prisma:engine:serialize
  • prisma:engine:itx_query_builder
    • prisma:engine:db_query
    • prisma:engine:db_query
    • prisma:engine:serialize
• prisma:client:operation
  • prisma:client:serialize
• prisma:client:operation
  • prisma:client:serialize

添加更多仪表

OpenTelemetry 的一个好处是能够仅需对您的应用程序代码进行最少的更改即可添加更多仪表。

例如，要添加 HTTP 和 ExpressJS 追踪，将以下仪表添加到您的 OpenTelemetry 配置。这些仪表为完整的请求-响应生命周期添加 span。这些 span 向您显示您的 HTTP 请求花费了多长时间。

// Imports
import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express'
import { HttpInstrumentation } from '@opentelemetry/instrumentation-http'

// Register your auto-instrumentors
registerInstrumentations({
  tracerProvider: provider,
  instrumentations: [
    new HttpInstrumentation(),
    new ExpressInstrumentation(),
    new PrismaInstrumentation(),
  ],
})

有关可用仪表的完整列表，请查看 OpenTelemetry 注册表。

自定义资源属性

您可以通过更改资源属性以更具体地针对您的应用程序来调整应用程序追踪的分组方式

const provider = new NodeTracerProvider({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'weblog',
    [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
  }),
})

目前正在努力标准化通用资源属性。尽可能遵循标准属性名称是一个好主意。

减少性能影响

如果您的应用程序向收集器发送大量 span，这可能会对性能产生重大影响。您可以使用以下方法来减少这种影响

• 使用 BatchSpanProcessor
• 向收集器发送更少的 span

使用 BatchSpanProcessor 批量发送追踪

在生产环境中，您可以使用 OpenTelemetry 的 BatchSpanProcessor 将 span 批量发送到收集器，而不是一次发送一个。但是，在开发和测试期间，您可能不想批量发送 span。在这种情况下，您可能更喜欢使用 SimpleSpanProcessor。

您可以配置您的追踪配置以使用适当的 span 处理器，具体取决于环境，如下所示

import {
  SimpleSpanProcessor,
  BatchSpanProcessor,
} from '@opentelemetry/sdk-trace-base'

if (process.env.NODE_ENV === 'production') {
  provider.addSpanProcessor(new BatchSpanProcessor(otlpTraceExporter))
} else {
  provider.addSpanProcessor(new SimpleSpanProcessor(otlpTraceExporter))
}

通过采样向收集器发送更少的 span

减少性能影响的另一种方法是使用概率采样向收集器发送更少的 span。这降低了追踪的收集成本，但仍然很好地表示了您的应用程序中正在发生的事情。

一个示例实现如下所示

import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions'
import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
import { TraceIdRatioBasedSampler } from '@opentelemetry/core'
import { Resource } from '@opentelemetry/resources'

const provider = new NodeTracerProvider({
  sampler: new TraceIdRatioBasedSampler(0.1),
  resource: new Resource({
    // we can define some metadata about the trace resource
    [SemanticResourceAttributes.SERVICE_NAME]: 'test-tracing-service',
    [SemanticResourceAttributes.SERVICE_VERSION]: '1.0.0',
  }),
})

故障排除追踪

我的追踪没有显示出来

您设置追踪的顺序很重要。在您的应用程序中，确保在导入任何仪表化依赖项之前注册追踪和仪表。例如

import { registerTracing } from './tracing'

registerTracing({
  name: 'tracing-example',
  version: '0.0.1',
})

// You must import any dependencies after you register tracing.
import { PrismaClient } from '@prisma/client'
import async from 'express-async-handler'
import express from 'express'