autotel-tanstack 1.1.0

package/src/testing.test.ts

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { createMockRequest, generateTraceparent } from './testing';
+
+describe('testing utilities', () => {
+  describe('createMockRequest', () => {
+    it('should create a GET request', () => {
+      const request = createMockRequest('GET', '/api/users');
+
+      expect(request.method).toBe('GET');
+      expect(request.url).toBe('http://localhost/api/users');
+    });
+
+    it('should create a POST request', () => {
+      const request = createMockRequest('POST', '/api/users', {
+        body: JSON.stringify({ name: 'Test' }),
+      });
+
+      expect(request.method).toBe('POST');
+    });
+
+    it('should include custom headers', () => {
+      const request = createMockRequest('GET', '/api/users', {
+        headers: { 'x-request-id': 'test-123' },
+      });
+
+      expect(request.headers.get('x-request-id')).toBe('test-123');
+    });
+
+    it('should include traceparent header', () => {
+      const traceparent =
+        '00-12345678901234567890123456789012-1234567890123456-01';
+      const request = createMockRequest('GET', '/api/users', { traceparent });
+
+      expect(request.headers.get('traceparent')).toBe(traceparent);
+    });
+  });
+
+  describe('generateTraceparent', () => {
+    it('should generate valid traceparent format', () => {
+      const traceparent = generateTraceparent();
+
+      // Format: version-traceId-spanId-flags
+      const parts = traceparent.split('-');
+      expect(parts).toHaveLength(4);
+      expect(parts[0]).toBe('00'); // version
+      expect(parts[1]).toHaveLength(32); // trace ID
+      expect(parts[2]).toHaveLength(16); // span ID
+      expect(parts[3]).toBe('01'); // sampled flag
+    });
+
+    it('should use provided trace ID', () => {
+      const traceId = '12345678901234567890123456789012';
+      const traceparent = generateTraceparent(traceId);
+
+      expect(traceparent).toContain(traceId);
+    });
+
+    it('should use provided span ID', () => {
+      const spanId = '1234567890123456';
+      const traceparent = generateTraceparent(undefined, spanId);
+
+      expect(traceparent).toContain(spanId);
+    });
+
+    it('should generate different values each time', () => {
+      const tp1 = generateTraceparent();
+      const tp2 = generateTraceparent();
+
+      expect(tp1).not.toBe(tp2);
+    });
+  });
+});

package/src/testing.ts

@@ -0,0 +1,276 @@
+import { type ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { InMemorySpanExporter } from 'autotel/exporters';
+import { SimpleSpanProcessor } from 'autotel/processors';
+import { init } from 'autotel';
+
+/**
+ * Test harness for TanStack instrumentation testing
+ *
+ * Provides utilities for testing TanStack Start applications
+ * with autotel-tanstack instrumentation.
+ */
+export interface TestHarness {
+  /**
+   * The in-memory span exporter
+   */
+  exporter: {
+    getFinishedSpans(): ReadableSpan[];
+    reset(): void;
+  };
+
+  /**
+   * Get all finished spans
+   */
+  getSpans(): ReadableSpan[];
+
+  /**
+   * Get spans by name (exact match or regex)
+   */
+  getSpansByName(name: string | RegExp): ReadableSpan[];
+
+  /**
+   * Get spans by TanStack type
+   */
+  getSpansByType(
+    type: 'request' | 'serverFn' | 'loader' | 'beforeLoad',
+  ): ReadableSpan[];
+
+  /**
+   * Reset collected spans
+   */
+  reset(): void;
+
+  /**
+   * Assert a span exists
+   */
+  assertSpanExists(name: string | RegExp): void;
+
+  /**
+   * Assert a span has a specific attribute
+   */
+  assertSpanHasAttribute(
+    name: string | RegExp,
+    attr: string,
+    value?: unknown,
+  ): void;
+
+  /**
+   * Assert a server function was traced
+   */
+  assertServerFnTraced(name: string): void;
+
+  /**
+   * Assert a loader was traced
+   */
+  assertLoaderTraced(routeId: string): void;
+
+  /**
+   * Assert a beforeLoad was traced
+   */
+  assertBeforeLoadTraced(routeId: string): void;
+
+  /**
+   * Assert an HTTP request was traced
+   */
+  assertRequestTraced(method: string, path: string): void;
+}
+
+/**
+ * Create a test harness for TanStack instrumentation testing
+ *
+ * This sets up autotel with an in-memory exporter for testing.
+ * Call this in your test setup to capture and assert on spans.
+ *
+ * @returns Test harness with assertion helpers
+ *
+ * @example
+ * ```typescript
+ * import { describe, it, beforeEach } from 'vitest';
+ * import { createTestHarness } from 'autotel-tanstack/testing';
+ *
+ * describe('MyServerFunction', () => {
+ *   let harness: ReturnType<typeof createTestHarness>;
+ *
+ *   beforeEach(() => {
+ *     harness = createTestHarness();
+ *   });
+ *
+ *   afterEach(() => {
+ *     harness.reset();
+ *   });
+ *
+ *   it('should trace the server function', async () => {
+ *     await myServerFunction({ id: '123' });
+ *
+ *     harness.assertServerFnTraced('myServerFunction');
+ *     harness.assertSpanHasAttribute(
+ *       /tanstack\.serverFn/,
+ *       'tanstack.server_function.name',
+ *       'myServerFunction'
+ *     );
+ *   });
+ * });
+ * ```
+ */
+export function createTestHarness(): TestHarness {
+  const exporter = new InMemorySpanExporter();
+
+  init({
+    service: 'test',
+    spanProcessors: [new SimpleSpanProcessor(exporter)],
+  });
+
+  function getSpans(): ReadableSpan[] {
+    return exporter.getFinishedSpans() as ReadableSpan[];
+  }
+
+  function getSpansByName(name: string | RegExp): ReadableSpan[] {
+    const spans = getSpans();
+    if (typeof name === 'string') {
+      return spans.filter((s) => s.name === name);
+    }
+    return spans.filter((s) => name.test(s.name));
+  }
+
+  function getSpansByType(
+    type: 'request' | 'serverFn' | 'loader' | 'beforeLoad',
+  ): ReadableSpan[] {
+    return getSpans().filter((s) => s.attributes['tanstack.type'] === type);
+  }
+
+  function reset(): void {
+    exporter.reset();
+  }
+
+  function assertSpanExists(name: string | RegExp): void {
+    const spans = getSpansByName(name);
+    if (spans.length === 0) {
+      const allSpanNames = getSpans().map((s) => s.name);
+      throw new Error(
+        `Expected span "${name}" to exist. Found spans: ${JSON.stringify(allSpanNames)}`,
+      );
+    }
+  }
+
+  function assertSpanHasAttribute(
+    name: string | RegExp,
+    attr: string,
+    value?: unknown,
+  ): void {
+    const spans = getSpansByName(name);
+    if (spans.length === 0) {
+      throw new Error(`Span "${name}" not found`);
+    }
+
+    const span = spans[0];
+    const attrValue = span.attributes[attr];
+
+    if (attrValue === undefined) {
+      throw new Error(
+        `Attribute "${attr}" not found on span "${span.name}". ` +
+          `Available attributes: ${JSON.stringify(Object.keys(span.attributes))}`,
+      );
+    }
+
+    if (value !== undefined && attrValue !== value) {
+      throw new Error(
+        `Expected attribute "${attr}" to be "${value}", got "${attrValue}"`,
+      );
+    }
+  }
+
+  function assertServerFnTraced(name: string): void {
+    assertSpanExists(`tanstack.serverFn.${name}`);
+  }
+
+  function assertLoaderTraced(routeId: string): void {
+    assertSpanExists(`tanstack.loader.${routeId}`);
+  }
+
+  function assertBeforeLoadTraced(routeId: string): void {
+    assertSpanExists(`tanstack.beforeLoad.${routeId}`);
+  }
+
+  function assertRequestTraced(method: string, path: string): void {
+    assertSpanExists(`${method} ${path}`);
+  }
+
+  return {
+    exporter,
+    getSpans,
+    getSpansByName,
+    getSpansByType,
+    reset,
+    assertSpanExists,
+    assertSpanHasAttribute,
+    assertServerFnTraced,
+    assertLoaderTraced,
+    assertBeforeLoadTraced,
+    assertRequestTraced,
+  };
+}
+
+/**
+ * Mock request factory for testing
+ *
+ * Creates mock Request objects for testing middleware and handlers.
+ *
+ * @example
+ * ```typescript
+ * const request = createMockRequest('GET', '/api/users', {
+ *   headers: { 'x-request-id': 'test-123' },
+ * });
+ * ```
+ */
+export function createMockRequest(
+  method: string,
+  path: string,
+  options: {
+    headers?: Record<string, string>;
+    body?: string;
+    traceparent?: string;
+  } = {},
+): Request {
+  const headers = new Headers(options.headers);
+
+  if (options.traceparent) {
+    headers.set('traceparent', options.traceparent);
+  }
+
+  return new Request(`http://localhost${path}`, {
+    method,
+    headers,
+    body: options.body,
+  });
+}
+
+/**
+ * Generate a valid W3C traceparent header for testing
+ *
+ * @param traceId - Optional 32-char hex trace ID
+ * @param spanId - Optional 16-char hex span ID
+ * @returns Valid traceparent header string
+ *
+ * @example
+ * ```typescript
+ * const traceparent = generateTraceparent();
+ * const request = createMockRequest('GET', '/api/users', { traceparent });
+ * ```
+ */
+export function generateTraceparent(traceId?: string, spanId?: string): string {
+  const version = '00';
+  const trace = traceId || generateHex(32);
+  const span = spanId || generateHex(16);
+  const flags = '01'; // Sampled
+
+  return `${version}-${trace}-${span}-${flags}`;
+}
+
+function generateHex(length: number): string {
+  const chars = '0123456789abcdef';
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += chars[Math.floor(Math.random() * 16)];
+  }
+  return result;
+}

package/src/types.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest';
+import { DEFAULT_CONFIG, SPAN_ATTRIBUTES } from './types';
+
+describe('types', () => {
+  describe('DEFAULT_CONFIG', () => {
+    it('should have sensible defaults', () => {
+      expect(DEFAULT_CONFIG.captureArgs).toBe(true);
+      expect(DEFAULT_CONFIG.captureResults).toBe(false);
+      expect(DEFAULT_CONFIG.captureErrors).toBe(true);
+      expect(DEFAULT_CONFIG.sampling).toBe('adaptive');
+    });
+
+    it('should capture x-request-id by default', () => {
+      expect(DEFAULT_CONFIG.captureHeaders).toContain('x-request-id');
+    });
+
+    it('should not exclude any paths by default', () => {
+      expect(DEFAULT_CONFIG.excludePaths).toEqual([]);
+    });
+  });
+
+  describe('SPAN_ATTRIBUTES', () => {
+    it('should have HTTP semantic convention attributes', () => {
+      expect(SPAN_ATTRIBUTES.HTTP_REQUEST_METHOD).toBe('http.request.method');
+      expect(SPAN_ATTRIBUTES.HTTP_RESPONSE_STATUS_CODE).toBe(
+        'http.response.status_code',
+      );
+      expect(SPAN_ATTRIBUTES.URL_PATH).toBe('url.path');
+    });
+
+    it('should have RPC semantic convention attributes', () => {
+      expect(SPAN_ATTRIBUTES.RPC_SYSTEM).toBe('rpc.system');
+      expect(SPAN_ATTRIBUTES.RPC_METHOD).toBe('rpc.method');
+    });
+
+    it('should have TanStack-specific attributes', () => {
+      expect(SPAN_ATTRIBUTES.TANSTACK_TYPE).toBe('tanstack.type');
+      expect(SPAN_ATTRIBUTES.TANSTACK_SERVER_FN_NAME).toBe(
+        'tanstack.server_function.name',
+      );
+      expect(SPAN_ATTRIBUTES.TANSTACK_LOADER_ROUTE_ID).toBe(
+        'tanstack.loader.route_id',
+      );
+    });
+  });
+});

package/src/types.ts

@@ -0,0 +1,182 @@
+import type { Attributes } from '@opentelemetry/api';
+
+/**
+ * Configuration options for TanStack Start instrumentation
+ */
+export interface TanStackInstrumentationConfig {
+  /**
+   * Service name for spans
+   * @default process.env.OTEL_SERVICE_NAME || 'tanstack-start'
+   */
+  service?: string;
+
+  /**
+   * Whether to capture function arguments as span attributes
+   * Warning: May contain PII, review before enabling in production
+   * @default true
+   */
+  captureArgs?: boolean;
+
+  /**
+   * Whether to capture function results as span attributes
+   * Warning: May contain PII, disable in production
+   * @default false
+   */
+  captureResults?: boolean;
+
+  /**
+   * Whether to capture errors and record exceptions
+   * @default true
+   */
+  captureErrors?: boolean;
+
+  /**
+   * HTTP headers to capture as span attributes
+   * @default ['x-request-id']
+   */
+  captureHeaders?: string[];
+
+  /**
+   * URL paths to exclude from tracing (glob patterns)
+   * @default []
+   */
+  excludePaths?: (string | RegExp)[];
+
+  /**
+   * Sampling strategy
+   * - 'always': Sample all requests (100%)
+   * - 'adaptive': Use autotel's adaptive sampling (errors + slow = 100%, baseline 10%)
+   * - 'never': Disable sampling (for testing/debugging)
+   * @default 'adaptive'
+   */
+  sampling?: 'always' | 'adaptive' | 'never';
+
+  /**
+   * Custom function to extract additional span attributes
+   */
+  customAttributes?: (context: {
+    type: 'request' | 'serverFn' | 'loader' | 'beforeLoad' | 'middleware';
+    name: string;
+    request?: Request;
+    args?: unknown;
+    result?: unknown;
+  }) => Attributes;
+}
+
+/**
+ * Configuration specific to tracing middleware
+ */
+export interface TracingMiddlewareConfig extends TanStackInstrumentationConfig {
+  /**
+   * Type of middleware
+   * - 'request': For global request middleware (routes, SSR)
+   * - 'function': For server function middleware
+   * @default 'request'
+   */
+  type?: 'request' | 'function';
+}
+
+/**
+ * Configuration for server function tracing
+ */
+export interface TraceServerFnConfig {
+  /**
+   * Explicit name for the span
+   * If not provided, will attempt to infer from function name
+   */
+  name?: string;
+
+  /**
+   * Whether to capture function arguments
+   * @default true
+   */
+  captureArgs?: boolean;
+
+  /**
+   * Whether to capture function results
+   * @default false
+   */
+  captureResults?: boolean;
+}
+
+/**
+ * Configuration for loader tracing
+ */
+export interface TraceLoaderConfig {
+  /**
+   * Explicit name for the span
+   * If not provided, will use route ID
+   */
+  name?: string;
+
+  /**
+   * Whether to capture route params
+   * @default true
+   */
+  captureParams?: boolean;
+
+  /**
+   * Whether to capture loader result
+   * @default false
+   */
+  captureResult?: boolean;
+}
+
+/**
+ * Configuration for handler wrapper
+ */
+export interface WrapStartHandlerConfig extends TanStackInstrumentationConfig {
+  /**
+   * OTLP endpoint URL
+   * @default process.env.OTEL_EXPORTER_OTLP_ENDPOINT
+   */
+  endpoint?: string;
+
+  /**
+   * OTLP headers (e.g., for authentication)
+   * @default parsed from process.env.OTEL_EXPORTER_OTLP_HEADERS
+   */
+  headers?: Record<string, string>;
+}
+
+/**
+ * Default configuration values
+ */
+export const DEFAULT_CONFIG: Required<
+  Omit<TanStackInstrumentationConfig, 'customAttributes' | 'service'>
+> = {
+  captureArgs: true,
+  captureResults: false,
+  captureErrors: true,
+  captureHeaders: ['x-request-id'],
+  excludePaths: [],
+  sampling: 'adaptive',
+};
+
+/**
+ * Span attribute keys following OpenTelemetry semantic conventions
+ */
+export const SPAN_ATTRIBUTES = {
+  // HTTP semantic conventions
+  HTTP_REQUEST_METHOD: 'http.request.method',
+  HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code',
+  URL_PATH: 'url.path',
+  URL_QUERY: 'url.query',
+  URL_FULL: 'url.full',
+
+  // RPC semantic conventions (for server functions)
+  RPC_SYSTEM: 'rpc.system',
+  RPC_METHOD: 'rpc.method',
+
+  // TanStack-specific attributes
+  TANSTACK_TYPE: 'tanstack.type',
+  TANSTACK_SERVER_FN_NAME: 'tanstack.server_function.name',
+  TANSTACK_SERVER_FN_METHOD: 'tanstack.server_function.method',
+  TANSTACK_SERVER_FN_ARGS: 'tanstack.server_function.args',
+  TANSTACK_SERVER_FN_RESULT: 'tanstack.server_function.result',
+  TANSTACK_LOADER_ROUTE_ID: 'tanstack.loader.route_id',
+  TANSTACK_LOADER_TYPE: 'tanstack.loader.type',
+  TANSTACK_LOADER_PARAMS: 'tanstack.loader.params',
+  TANSTACK_MIDDLEWARE_NAME: 'tanstack.middleware.name',
+  TANSTACK_REQUEST_DURATION_MS: 'tanstack.request.duration_ms',
+} as const;