TanStack Start

autotel-tanstack instruments TanStack Start applications using the framework’s native middleware patterns. Configure global middleware once and every server function, route loader, and HTTP request is traced automatically. Works with both @tanstack/react-start and @tanstack/solid-start (^1.139.14).

Installation

npm install autotel-tanstack autotel

Quick start

Configure global middleware in start.ts:

src/start.ts

import { createStart, createMiddleware } from '@tanstack/react-start';
import { createTracingServerHandler } from 'autotel-tanstack/middleware';
import './instrumentation';

const requestTracingMiddleware = createMiddleware().server(
  createTracingServerHandler({
    captureHeaders: ['x-request-id', 'user-agent'],
    excludePaths: ['/health', '/metrics'],
  }),
);

const functionTracingMiddleware = createMiddleware({ type: 'function' }).server(
  createTracingServerHandler({ type: 'function', captureArgs: true }),
);

export const startInstance = createStart(() => ({
  requestMiddleware: [requestTracingMiddleware],
  functionMiddleware: [functionTracingMiddleware],
}));

src/instrumentation.ts

import { init } from 'autotel';

init({
  service: 'my-app',
  endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
});

Zero-config alternative

Skip the explicit init() and use environment variables instead:

src/instrumentation.ts

import 'autotel-tanstack/auto';
export {};

autotel-tanstack/auto reads OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_ENDPOINT, and OTEL_EXPORTER_OTLP_HEADERS at startup.

Server functions

With functionMiddleware configured globally, every createServerFn(...) is auto-traced:

import { createServerFn } from '@tanstack/react-start';

export const getUser = createServerFn({ method: 'GET' }).handler(
  async ({ data: id }) => {
    return await db.users.findUnique({ where: { id } });
  },
);

export const createUser = createServerFn({ method: 'POST' })
  .validator((d: UserInput) => d)
  .handler(async ({ data }) => {
    return await db.users.create({ data });
  });

Per-function middleware

For per-function options (e.g. capturing results for one operation), chain a function-scoped middleware:

import { createServerFn, createMiddleware } from '@tanstack/react-start';
import { createTracingServerHandler } from 'autotel-tanstack/middleware';

const verboseTracing = createMiddleware({ type: 'function' }).server(
  createTracingServerHandler({
    type: 'function',
    captureArgs: true,
    captureResults: true,
  }),
);

export const sensitiveOperation = createServerFn({ method: 'POST' })
  .middleware([verboseTracing])
  .handler(async ({ data }) => {
    /* ... */
  });

Route loaders

import { createFileRoute, redirect } from '@tanstack/react-router';
import { traceLoader, traceBeforeLoad } from 'autotel-tanstack/loaders';

export const Route = createFileRoute('/users/$userId')({
  beforeLoad: (ctx) =>
    traceBeforeLoad(ctx, async ({ context }) => {
      if (!context.auth.isAuthenticated) throw redirect({ to: '/login' });
    }),
  loader: (ctx) =>
    traceLoader(ctx, async ({ params }) => {
      return await getUser(params.userId);
    }),
});

Pass the route’s ctx through. TanStack Router types params, search and the context from the function you write, and the traced function receives them typed.

Middleware options

createTracingServerHandler accepts:

Option	Type	Default	Description
type	'request' | 'function'	'request'	Span kind for this middleware
captureHeaders	string[]	[]	Request headers to attach as span attributes
captureArgs	boolean	true	Record server-function arguments
captureResults	boolean	false	Record server-function results (off by default; PII risk)
excludePaths	string[]	[]	Glob paths to skip
sampling	'always' | 'adaptive' | 'never'	'adaptive'	Sampling strategy
customAttributes	({ type, name, request }) => Attributes	—	Per-span custom attributes

Span attributes

HTTP request spans

• http.request.method: GET, POST, etc.
• url.path, url.query
• http.response.status_code
• tanstack.request.duration_ms

Server function spans

• rpc.system: tanstack-start
• rpc.method: function name
• tanstack.server_function.name
• tanstack.server_function.method
• tanstack.server_function.args: when captureArgs: true

Loader spans

• tanstack.loader.route_id
• tanstack.loader.type: loader or beforeLoad
• tanstack.loader.params

Environment variables

Variable	Description	Example
OTEL_SERVICE_NAME	Service name reported on every span	my-app
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP collector URL	https://api.honeycomb.io
OTEL_EXPORTER_OTLP_HEADERS	Auth headers (key=value,key=value)	x-honeycomb-team=YOUR_KEY
AUTOTEL_DEBUG	Enable debug logging	true
E2E	Switch to in-memory exporter for tests	1

Distributed tracing

Inject and extract W3C trace context for cross-service calls:

import {
  createTracedHeaders,
  extractContextFromRequest,
} from 'autotel-tanstack/context';

// Outgoing
const headers = createTracedHeaders({ 'Content-Type': 'application/json' });
await fetch('https://api.example.com', { headers, method: 'POST', body });

// Incoming
const parentContext = extractContextFromRequest(request);

E2E testing

Set E2E=1 in your Playwright webServer command. autotel-tanstack/auto detects this and switches to an in-memory exporter so spans can be asserted on instead of being shipped to OTLP.

# playwright.config.ts webServer
E2E=1 OTEL_SERVICE_NAME=my-app vite preview --port 3100

Expose the spans over HTTP:

src/routes/api/test-spans.ts

import { createFileRoute } from '@tanstack/react-router';
import { createTestSpansHandlers } from 'autotel-tanstack/testing';

const { GET, DELETE } = createTestSpansHandlers();

export const Route = createFileRoute('/api/test-spans')({
  server: { handlers: { GET, DELETE } },
});

Then assert from Playwright using createTestSpansClient from autotel-playwright.

Unit testing

import { describe, it, expect } from 'vitest';
import { createTestCollector } from 'autotel-tanstack/testing';

describe('getUser', () => {
  it('creates a span', async () => {
    const collector = createTestCollector();
    await getUser({ data: '123' });
    const spans = collector.getSpans();
    expect(spans[0].name).toContain('getUser');
  });
});

Entry points

Import	Contents
autotel-tanstack	Everything
autotel-tanstack/auto	Zero-config auto-instrumentation
autotel-tanstack/middleware	createTracingServerHandler
autotel-tanstack/server-functions	traceServerFn (explicit wrapper)
autotel-tanstack/loaders	traceLoader, traceBeforeLoad
autotel-tanstack/handlers	wrapStartHandler (handler-level wrapping)
autotel-tanstack/context	createTracedHeaders, extractContextFromRequest
autotel-tanstack/testing	createTestCollector, createTestSpansHandlers

Supported frameworks

• @tanstack/react-start ^1.139.14
• @tanstack/solid-start ^1.139.14

Examples

• example-tanstack-start: full-stack with request and server-function middleware, route loaders, and autotel-web for browser trace propagation.