Monitoring Server-Side Performance

Hello! Welcome to your penultimate lesson.

In our last session, we implemented a robust structured logging system using Pino. This gives us detailed, event-by-event insight into our server's operations. Now, we'll build on that by looking at the bigger picture: performance over time. While logs tell us what happened, metrics tell us how well it's happening, in a quantitative and aggregated way.

Today, we will address the learning outcome: Monitor server-side performance metrics, including request and response times. We'll explore how to capture, store, and visualize key performance indicators (KPIs) like request rates, error rates, and response durations. This is essential for understanding application health, identifying bottlenecks, and ensuring a good user experience.

We will cover three approaches, progressing from a simple built-in method to a full-fledged, industry-standard monitoring stack.

1. The Built-in Approach: Simple Metrics Collection

TanStack Start's architecture, particularly its middleware system, provides a straightforward way to collect basic performance data without external dependencies. This approach is great for getting started and for environments where a simpler setup is preferred.

The idea is to expand our existing middleware to not only log request durations but also to record them in a simple in-memory collector. We can then expose this data via a dedicated /metrics endpoint.

Now, let's integrate these concepts.

1.1. Creating a Metrics Collector

First, create a utility file for the MetricsCollector class.

// src/lib/metrics.ts
export 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);
    const sum = timings.reduce((a, b) => a + b, 0);

    return {
      count: timings.length,
      avg: sum / timings.length,
      p50: sorted[Math.floor(sorted.length * 0.5)],
      p95: sorted[Math.floor(sorted.length * 0.95)],
      min: sorted[0],
      max: sorted[sorted.length - 1],
    };
  }

  getAllStats() {
    const stats: Record<string, ReturnType<typeof this.getStats>> = {};
    for (const [name] of this.metrics.entries()) {
      stats[name] = this.getStats(name);
    }
    return stats;
  }
}

export const metrics = new MetricsCollector();

1.2. Updating the Middleware

Next, we'll update the loggingMiddleware from our previous lesson to use this collector.

// src/server/loggingMiddleware.ts
import { createMiddleware } from '@tanstack/start';
import { randomUUID } from 'node:crypto';
import logger from '~/lib/logger';
import { metrics } from '~/lib/metrics'; // Import our collector

// ... (RouteContext type declaration)

export const loggingMiddleware = createMiddleware().handler(
  async ({ request, next }) => {
    const start = Date.now();
    const requestId = request.headers.get('x-request-id') || randomUUID();
    const reqLogger = logger.child({ requestId });

    reqLogger.info({ /* ... */ }, 'Request started');

    const response = await next({ logger: reqLogger });

    const duration = Date.now() - start;
    
    // Record the timing
    metrics.recordTiming('http_request_duration_ms', duration);
    
    reqLogger.info({ status: response.status, duration }, 'Request finished');

    response.headers.set('x-request-id', requestId);
    return response;
  },
);

1.3. Exposing the Metrics Endpoint

Finally, create a route to expose the collected data, as shown in the documentation.

// src/routes/metrics.tsx
import { createFileRoute, json } from '@tanstack/react-router';
import { metrics } from '~/lib/metrics';
import { lazy } from 'react';

export const Route = createFileRoute('/metrics')({
  // This is a server-only route
  server: {
    handlers: {
      GET: async () => {
        return json({
          system: {
            uptime: process.uptime(),
            memory: process.memoryUsage(),
            timestamp: new Date().toISOString(),
          },
          application: metrics.getAllStats(),
        });
      },
    },
  },
  // We need a component, but it will never be rendered on the client for a GET
  component: lazy(() => import('~/components/EmptyComponent')),
});

Now, if you run your app and make some requests, navigating to /metrics will show you the aggregated statistics. This is a solid first step, but its in-memory nature means metrics are lost on every server restart. For production, we need something more robust.

2. The Production Standard: Prometheus and Grafana

For a production-grade setup, we'll use two industry-standard tools:

• Prometheus: An open-source monitoring system and time-series database. It works by "scraping" (pulling) metrics from an HTTP endpoint on your application.
• Grafana: An open-source platform for data visualization, which allows you to create powerful dashboards from data sources like Prometheus.

Since your goal includes using Bun, we'll follow a guide tailored for a Bun backend.

2.1. Instrumenting the App for Prometheus

First, we need to modify our application to expose metrics in a format Prometheus understands. We'll use the prom-client library.

You can adapt the middleware from the guide and integrate it into your TanStack Start application, similar to how we added the logging middleware. The key is to apply it to all routes so it can track every request.

2.2. Running the Monitoring Stack

With the app exposing a /metrics endpoint, we need to set up Prometheus to scrape it and Grafana to visualize it. The easiest way to run these services is with Docker.

At this point, you have a complete pipeline: your TanStack Start app generates metrics, Prometheus collects and stores them, and Grafana is ready to query and display them.

2.3. Building Dashboards and Querying Metrics

The final step is to visualize the data. Grafana uses Prometheus's query language (PromQL) to create graphs.

This setup provides a powerful, scalable, and persistent monitoring solution that is the standard for many production systems.

3. The Future: Unified Observability with OpenTelemetry

Prometheus is excellent for metrics, but modern observability often involves correlating metrics with logs and traces (detailed, step-by-step records of a request's journey). OpenTelemetry (OTel) is an emerging CNCF standard designed to unify all three "pillars of observability".

While a full OTel setup is beyond this lesson's scope, it's crucial to understand the concepts, as the industry is rapidly moving in this direction. In fact, the TanStack team has noted that direct OpenTelemetry support is a future goal for TanStack Start.

Understanding OpenTelemetry positions you at the forefront of modern application monitoring, preparing you for the next generation of observability tools that will likely be integrated directly into frameworks like TanStack Start.

Conclusion

Today you've learned how to monitor the performance of your server-side application, a critical skill for maintaining a healthy and reliable service.

Key Takeaways:

• Metrics vs. Logs: Logs record discrete events, while metrics provide quantitative, aggregated data about performance over time.
• Built-in vs. Dedicated Tools: You can start with simple, in-memory metrics collection, but production systems benefit from robust tools like Prometheus for storage and Grafana for visualization.
• Key Metrics: Request rate, error rate, and latency percentiles (p50, p95, p99) are fundamental indicators of application health.
• The Future is Unified: OpenTelemetry is the emerging standard for combining metrics, logs, and traces into a single, correlated view of your application's behavior.

This lesson concludes our module on Production Deployment and Monitoring. You are now equipped not only to build and deploy a TanStack Start application but also to operate it responsibly with proper error tracking, logging, and performance monitoring.

This also marks the end of our course. Congratulations! You have journeyed from the foundational trade-offs of SSR, through the intricacies of Tanstack Router and Start, to advanced data management, migration strategies, and finally, production-grade deployment and observability. You have built a comprehensive skill set to tackle the primary goal you set out with: transforming a SPA into a modern, performant SSR application.

Well done on your dedication and progress throughout these lessons. The next step is to apply this knowledge to your own projects. Good luck