Trace Vitest tests

Use Vitest’s built-in OpenTelemetry tracing to inspect test runs, workers and individual tests in Observe. This traces test execution; it does not turn tests into Future AGI evaluations or import experiment scores.

Vitest 5.0.5 or later and Node.js 22.12+, 24+, or 26+ are required. Get your Future AGI API key and secret key and choose an Observe project. OpenTelemetry initialization adds startup time to each isolated test worker.

Install

In your Vitest project, install the standard Node SDK and trace exporter:

npm install -D @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/resources @opentelemetry/exporter-trace-otlp-http

Keep your existing Vitest version if it is 5.0.5 or later; otherwise upgrade it. Use the three files below as a small runnable example.

Configure tracing

Export the credentials and the Observe project name in the shell that runs Vitest:

export FI_API_KEY="your-futureagi-api-key"
export FI_SECRET_KEY="your-futureagi-secret-key"
export FI_PROJECT_NAME="vitest-tests"

Create otel.mjs at your project root. Vitest imports this module in the runner and test workers. The SDK must start in the module and be the default export so Vitest can shut it down and flush short-lived runs. project_name belongs on the resource, not on individual spans.

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
import { resourceFromAttributes } from '@opentelemetry/resources';

for (const key of ['FI_API_KEY', 'FI_SECRET_KEY', 'FI_PROJECT_NAME']) {
  if (!process.env[key]) throw new Error(`Set ${key} before running Vitest`);
}

const sdk = new NodeSDK({
  resource: resourceFromAttributes({
    'service.name': 'vitest-tests',
    project_name: process.env.FI_PROJECT_NAME,
    project_type: 'observe',
  }),
  traceExporter: new OTLPTraceExporter({
    url: 'https://api.futureagi.com/tracer/v1/traces',
    headers: {
      'X-Api-Key': process.env.FI_API_KEY,
      'X-Secret-Key': process.env.FI_SECRET_KEY,
    },
  }),
});

sdk.start();
export default sdk;

Point Vitest at that file. Add experimental inside your existing test config rather than registering a second provider:

import { defineConfig } from 'vitest/config';

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

Run a test

import { expect, test } from 'vitest';

test('invoice totals include tax', () => {
  expect(20 * 1.1).toBeCloseTo(22);
});

Run npx vitest run. Open Observe and select vitest-tests to inspect the worker and test spans. The spans describe test execution, not model calls; model and tool spans need their own instrumentation if your tests call a model.

Test names, file paths and failure details can appear in the exported spans. Avoid sensitive values in test names and fixtures, or use an exporter-side filtering policy before sending traces. Do not put your Future AGI keys in test files or span attributes.

Troubleshooting

• No spans after a short run: Keep the sdk.start() call and the default SDK export. Vitest calls shutdown() on that export to flush pending spans.
• HTTP 400: Add the project_name resource attribute; service.name alone does not select an Observe project.
• HTTP 401: Check both credential headers and make sure the exporter URL ends in /tracer/v1/traces.
• Longer startup: Vitest initializes OpenTelemetry in each worker; reduce isolation only if your tests can safely share a worker. See Vitest’s OpenTelemetry guide for its current configuration and browser-mode setup.