Vitest

Open Telemetry 支持 experimental ​

反馈

请在 GitHub 讨论区 中留下关于此功能的反馈。

示例项目

GitHub

OpenTelemetry 追踪可以成为调试测试中应用程序性能和行为的有用工具。

如果启用，Vitest 集成会生成限定于你的测试工作器（worker）的跨度（spans）。

WARNING

OpenTelemetry 初始化会增加每个测试的启动时间，除非 Vitest 在没有 隔离 的情况下运行。你可以将其视为 vitest.worker.start 内的 vitest.runtime.traces 跨度。

要在 Vitest 中开始使用 OpenTelemetry，请通过 experimental.openTelemetry.sdkPath 指定 SDK 模块路径，并将 experimental.openTelemetry.enabled 设置为 true。Vitest 将自动对整个进程和每个单独的测试工作器进行插桩。

确保将 SDK 导出为默认导出，以便 Vitest 可以在进程关闭之前刷新网络请求。注意，Vitest 不会自动调用 start。

快速开始 ​

在预览你的应用追踪之前，安装所需的包并在配置中指定你的插桩文件路径。

shell
npm i @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-trace-otlp-proto
js
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { NodeSDK } from '@opentelemetry/sdk-node'

const sdk = new NodeSDK({
  serviceName: 'vitest',
  traceExporter: new OTLPTraceExporter(),
  instrumentations: [getNodeAutoInstrumentations()],
})

sdk.start()
export default sdk
js
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    experimental: {
      openTelemetry: {
        enabled: true,
        sdkPath: './otel.js',
      },
    },
  },
})

假定时器

如果你正在使用假定时器，重要的是在测试结束前重置它们，否则追踪可能无法被正确追踪。

Vitest 不会处理 sdkPath 模块，因此重要的是 SDK 可以在你的 Node.js 环境中被导入。理想情况下，此文件应使用 .js 扩展名。使用其他扩展名会减慢你的测试速度，并可能需要提供额外的 Node.js 参数。

如果你想提供 TypeScript 文件，请确保熟悉 Node.js 文档中的 TypeScript 页面。

自定义追踪 ​

你可以自己使用 OpenTelemetry API 来追踪代码中的某些操作。自定义追踪会自动继承 Vitest OpenTelemetry 上下文：

ts
import { trace } from '@opentelemetry/api'
import { test } from 'vitest'
import { db } from './src/db'

const tracer = trace.getTracer('vitest')

test('db connects properly', async () => {
  // 这将显示在 `vitest.test.runner.test.callback` span 内
  await tracer.startActiveSpan('db.connect', () => db.connect())
})

浏览器模式 ​

当在 浏览器模式 下运行测试时，Vitest 会在 Node.js 和浏览器之间传播追踪上下文。Node.js 端的追踪（测试编排、浏览器驱动通信）无需额外配置即可用。

要从浏览器运行时捕获追踪，请通过 browserSdkPath 提供浏览器兼容的 SDK：

shell
npm i @opentelemetry/sdk-trace-web @opentelemetry/exporter-trace-otlp-proto
js
import {
  BatchSpanProcessor,
  WebTracerProvider,
} from '@opentelemetry/sdk-trace-web'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'

const provider = new WebTracerProvider({
  spanProcessors: [
    new BatchSpanProcessor(new OTLPTraceExporter()),
  ],
})

provider.register()
export default provider
js
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      instances: [{ browser: 'chromium' }],
    },
    experimental: {
      openTelemetry: {
        enabled: true,
        sdkPath: './otel.js',
        browserSdkPath: './otel-browser.js',
      },
    },
  },
})

异步上下文

与 Node.js 不同，浏览器没有自动的异步上下文传播。Vitest 会在内部处理测试执行的此问题，但深层嵌套异步代码中的自定义跨度可能不会自动传播上下文。

查看追踪 ​

要生成追踪，照常运行 Vitest。你可以在监视模式或运行模式下运行 Vitest。Vitest 将在所有完成后手动调用 sdk.shutdown() 以确保追踪被正确处理。

你可以使用任何支持 OpenTelemetry API 的开源或商业产品来查看追踪。如果你之前没有使用过 OpenTelemetry，我们建议从 Jaeger 开始，因为它非常容易设置。

Jaeger 中 Open Telemetry 结果的示例

@opentelemetry/api ​

Vitest 将 @opentelemetry/api 声明为可选的同伴依赖，它在内部使用它来生成跨度。当未启用追踪收集时，Vitest 不会尝试使用此依赖。

当配置 Vitest 使用 OpenTelemetry 时，你通常会安装 @opentelemetry/sdk-node，它包含 @opentelemetry/api 作为传递依赖，从而满足 Vitest 的同伴依赖要求。如果遇到指示找不到 @opentelemetry/api 的错误，这通常意味着尚未启用追踪收集。如果在正确配置后错误仍然存在，你可能需要显式安装 @opentelemetry/api。

进程间上下文传播 ​

Vitest 支持通过 OpenTelemetry 规范 中定义的 TRACEPARENT 和 TRACESTATE 环境变量从父进程自动传播上下文。当作为更大的分布式追踪系统的一部分运行 Vitest 时（例如，具有 OpenTelemetry 插桩的 CI/CD 流水线），这特别有用。

© 2026 VoidZero Inc. and Vitest contributors.