ByteNoteByteNote

字节笔记本

2026年5月3日

TanStack Start - 可观测性 (Observability)

API中转
¥120

监控、追踪和调试应用性能与错误。TanStack Start 提供内置的可观测性模式,并与外部工具无缝集成。

官方合作伙伴:Sentry

Sentry 提供实时错误追踪、性能监控、发布健康和用户影响分析。

tsx
// app.tsx
import * as Sentry from '@sentry/react'

Sentry.init({
  dsn: import.meta.env.VITE_SENTRY_DSN,
  environment: import.meta.env.NODE_ENV,
  tracesSampleRate: 1.0,
})
tsx
// 服务端函数配置
import * as Sentry from '@sentry/node'

const serverFn = createServerFn().handler(async () => {
  try {
    return await riskyOperation()
  } catch (error) {
    Sentry.captureException(error)
    throw error
  }
})

内置可观测性模式

1. 服务端函数日志记录

tsx
const getUser = createServerFn({ method: 'GET' })
  .inputValidator((id: string) => id)
  .handler(async ({ data: id }) => {
    const startTime = Date.now()
    console.log(`[SERVER] Fetching user ${id}`)
    const user = await db.users.findUnique({ where: { id } })
    console.log(`[SERVER] User ${id} fetched in ${Date.now() - startTime}ms`)
    return user
  })

2. 请求/响应中间件

tsx
const requestLogger = createMiddleware().server(async ({ request, next }) => {
  const startTime = Date.now()
  const result = await next()
  console.log(`${request.method} ${request.url} - ${result.response.status} (${Date.now() - startTime}ms)`)
  return result
})

3. 健康检查端点

tsx
export const Route = createFileRoute('/health')({
  server: {
    handlers: {
      GET: async () => {
        return Response.json({
          status: 'healthy',
          timestamp: new Date().toISOString(),
          uptime: process.uptime(),
          memory: process.memoryUsage(),
          database: await checkDatabase(),
        })
      },
    },
  },
})

4. 性能指标收集

tsx
class MetricsCollector {
  private metrics = new Map<string, number[]>()

  recordTiming(name: string, duration: number) {
    if (!this.metrics.has(name)) this.metrics.set(name, [])
    this.metrics.get(name)!.push(duration)
  }

  getStats(name: string) {
    const timings = this.metrics.get(name) || []
    if (timings.length === 0) return null
    const sorted = timings.sort((a, b) => a - b)
    return {
      count: timings.length,
      avg: timings.reduce((a, b) => a + b, 0) / timings.length,
      p50: sorted[Math.floor(sorted.length * 0.5)],
      p95: sorted[Math.floor(sorted.length * 0.95)],
    }
  }
}

外部工具集成

New Relic

bash
node -r newrelic .output/server/index.mjs
tsx
import newrelic from 'newrelic'
import { createMiddleware } from '@tanstack/react-start'

const nrTransactionMiddleware = createMiddleware().server(
  async ({ request, next }) => {
    const reqPath = new URL(request.url).pathname
    newrelic.setControllerName(reqPath, request.method ?? 'GET')
    return await next()
  },
)

OpenTelemetry(实验性)

tsx
import { NodeSDK } from '@opentelemetry/sdk-node'
import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node'

const sdk = new NodeSDK({
  resource: new Resource({
    [SemanticResourceAttributes.SERVICE_NAME]: 'tanstack-start-app',
  }),
  instrumentations: [getNodeAutoInstrumentations()],
})
sdk.start()

工具对比

工具类型优势适用场景
Sentry错误追踪官方合作伙伴通用错误监控
New RelicAPM全栈监控企业级监控
DataDogAPM全面监控大规模应用
OpenTelemetry标准行业标准自定义可观测性
分享: