feat: support openTelemetry for browser mode (#9180)

Author: hi-ogawa

docs/config/experimental.md

@@ -117,9 +117,13 @@ Please, leave feedback regarding this feature in a [GitHub Discussion](https://g
 interface OpenTelemetryOptions {
   enabled: boolean
   /**
-   * A path to a file that exposes an OpenTelemetry SDK.
+   * A path to a file that exposes an OpenTelemetry SDK for Node.js.
    */
   sdkPath?: string
+  /**
+   * A path to a file that exposes an OpenTelemetry SDK for the browser.
+   */
+  browserSdkPath?: string
 }
 ```
 
@@ -133,9 +137,7 @@ OpenTelemetry may significantly impact Vitest performance; enable it only for lo
 
 You can use a [custom service](/guide/open-telemetry) together with Vitest to pinpoint which tests or files are slowing down your test suite.
 
-::: warning BROWSER SUPPORT
-At the moment, Vitest does not start any spans when running in [the browser](/guide/browser/).
-:::
+For browser mode, see the [Browser Mode](/guide/open-telemetry#browser-mode) section of the OpenTelemetry guide.
 
 An `sdkPath` is resolved relative to the [`root`](/config/root) of the project and should point to a module that exposes a started SDK instance as a default export. For example:
 

docs/guide/open-telemetry.md

@@ -84,6 +84,59 @@ test('db connects properly', async () => {
 })
 ```
 
+## Browser Mode
+
+When running tests in [browser mode](/guide/browser/), Vitest propagates trace context between Node.js and the browser. Node.js side traces (test orchestration, browser driver communication) are available without additional configuration.
+
+To capture traces from the browser runtime, provide a browser-compatible SDK via `browserSdkPath`:
+
+```shell
+npm i @opentelemetry/sdk-trace-web @opentelemetry/exporter-trace-otlp-proto
+```
+
+::: code-group
+```js [otel-browser.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 [vitest.config.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',
+      },
+    },
+  },
+})
+```
+:::
+
+::: warning ASYNC CONTEXT
+Unlike Node.js, browsers do not have automatic async context propagation. Vitest handles this internally for test execution, but custom spans in deeply nested async code may not propagate context automatically.
+:::
+
 ## View Traces
 
 To generate traces, run Vitest as usual. You can run Vitest in either watch mode or run mode. Vitest will call `sdk.shutdown()` manually after everything is finished to make sure traces are handled properly.

examples/opentelemetry/jaeger-config.yml

@@ -14,13 +14,15 @@ extensions:
     storage:
       traces: main_storage
 
+# https://opentelemetry.io/docs/languages/js/exporters/#configure-cors-headers
 receivers:
   otlp:
     protocols:
-      grpc:
-        endpoint: 0.0.0.0:4317
       http:
         endpoint: 0.0.0.0:4318
+        cors:
+          allowed_origins:
+            - http://localhost:*
 
 processors:
   batch:

examples/opentelemetry/otel-browser.js

@@ -0,0 +1,24 @@
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
+import { resourceFromAttributes } from '@opentelemetry/resources'
+import { BatchSpanProcessor, WebTracerProvider } from '@opentelemetry/sdk-trace-web'
+
+const provider = new WebTracerProvider({
+  resource: resourceFromAttributes({
+    'service.name': 'vitest-browser',
+  }),
+  spanProcessors: [
+    new BatchSpanProcessor(new OTLPTraceExporter()),
+    // you can add a ConsoleSpanExporter for debugging purposes
+    // (available in @opentelemetry/sdk-trace-web)
+    // new SimpleSpanProcessor(new ConsoleSpanExporter()),
+  ],
+})
+
+provider.register({
+  // you can customize contextManager but browser support has limitation
+  // cf. https://github.com/open-telemetry/opentelemetry-js/discussions/2060
+  // contextManager: new StackContextManager(), // this is the default (avialable in sdk-trace-web)
+  // contextManager: new ZoneContextManager(), // doesn't seem to help (avialable in @opentelemetry/context-zone)
+})
+
+export default provider

examples/opentelemetry/package.json

@@ -8,7 +8,12 @@
     "test": "vitest"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-zone": "^2.2.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.208.0",
+    "@opentelemetry/resources": "^2.2.0",
     "@opentelemetry/sdk-node": "^0.208.0",
+    "@opentelemetry/sdk-trace-web": "^2.2.0",
     "@vitest/browser-playwright": "latest",
     "vite": "latest",
     "vitest": "latest"

examples/opentelemetry/src/other.test.ts

@@ -0,0 +1,31 @@
+import { trace } from '@opentelemetry/api'
+import { test } from 'vitest'
+
+test('other', async () => {
+  await new Promise(r => setTimeout(r, 150))
+})
+
+test('custom', async () => {
+  // this starts span synchronously inside test function,
+  // so trace parent works without async context manager (e.g. on browser mode).
+
+  // console.log(context.active())
+  // > vitest.test.runner.test.callback
+  //   > custom-span
+
+  const tracer = trace.getTracer('custom-scope')
+  await tracer.startActiveSpan('custom-span', async (span) => {
+    span.setAttribute('custom-attribute', 'hello world')
+    await new Promise(resolve => setTimeout(resolve, 50))
+    span.end()
+  })
+
+  // however the context is dropped on browser mode.
+  // console.log(context.active())
+})
+
+test.runIf(typeof document !== 'undefined')('browser test', async () => {
+  const { page } = await import('vitest/browser')
+  document.body.innerHTML = `<button>Hello Vitest</button>`
+  await page.getByRole('button', { name: 'Hello Vitest' }).click()
+})

examples/opentelemetry/vite.config.ts

@@ -8,6 +8,7 @@ export default defineConfig({
         // enable via CLI flag --experimental.openTelemetry.enabled=true
         enabled: false,
         sdkPath: './otel.js',
+        browserSdkPath: './otel-browser.js',
       },
     },
     browser: {

packages/browser/package.json

@@ -56,7 +56,7 @@
     "build": "premove dist && pnpm build:node && pnpm build:client",
     "build:client": "vite build src/client",
     "build:node": "rollup -c",
-    "dev:client": "vite build src/client --watch",
+    "dev:client": "node --watch-preserve-output --watch-path src/client scripts/build-client.js",
     "dev:node": "rollup -c --watch --watch.include 'src/**'",
     "dev": "premove dist && pnpm run --stream '/^dev:/'"
   },
@@ -74,6 +74,7 @@
     "ws": "catalog:"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@testing-library/user-event": "^14.6.1",
     "@types/pngjs": "^6.0.5",
     "@types/ws": "catalog:",

packages/browser/scripts/build-client.js

@@ -0,0 +1,7 @@
+// wrapper script for `node --watch`.
+// this works around some issues with `vite build --watch`.
+import { spawn } from 'node:child_process'
+
+spawn('node', ['--run', 'build:client'], {
+  stdio: 'inherit',
+})

packages/browser/src/client/channel.ts

@@ -1,4 +1,5 @@
 import type { CancelReason, FileSpecification } from '@vitest/runner'
+import type { OTELCarrier } from 'vitest/internal/browser'
 import { getBrowserState } from './utils'
 
 export interface IframeViewportEvent {
@@ -41,6 +42,7 @@ export interface IframePrepareEvent {
   event: 'prepare'
   iframeId: string
   startTime: number
+  otelCarrier?: OTELCarrier
 }
 
 export type GlobalChannelIncomingEvent = GlobalChannelTestRunCanceledEvent