Forem: André Escobar

The Ultimate Guide to Web Application Observability

André Escobar — Wed, 02 Apr 2025 01:23:01 +0000

In modern web apps, keeping an eye on how things are running is a big deal. Tools like Prometheus, Grafana, and Alloy give us a way to monitor our apps, check performance, and track down issues before they become a problem.

In this guide, I’ll walk you through how to set up observability for a Nuxt-based server-side app that runs in a Docker container. We’ll use Prometheus to collect metrics and Grafana to visualize them. Let’s dive in!

What is Observability?

Simply put, observability is all about understanding what’s happening inside your system based on what it’s outputting like logs, metrics, and traces. With these, you can spot problems, troubleshoot, and make sure everything’s running smoothly.

The Tools We’ll Use

Prometheus: This open-source toolkit helps us gather performance data over time and analyze it with PromQL (a fancy query language). It’s like our system’s health monitor.
Grafana: It connects to Prometheus and gives us nice charts and dashboards to visualize our app’s performance. Think of it as the app’s “health dashboard.”
Alloy: Alloy makes it easy to integrate Prometheus and Grafana to monitor web apps, simplifying the setup.

We won’t go super deep into how these tools work internally, but we’ll cover what they do and how to set them up for your Nuxt app.

Step 1: Create a Prometheus Registry in Nuxt

Let’s start by adding a Prometheus registry to the backend of our Nuxt app.

Install Prometheus Client

We need the prom-client package. Go ahead and install it:

npm install prom-client

Create the Metrics Service

Inside your Nuxt app’s server folder, create a file server/services/prometheus.ts:

import { Registry, collectDefaultMetrics, Counter } from 'prom-client';

const registry = new Registry();

// Collect default metrics like CPU usage, memory usage, etc.
collectDefaultMetrics({ register: registry });

// Create a custom metric for counting HTTP requests
const httpRequestsTotal = new Counter({
  name: 'http_requests_total',
  help: 'Total number of HTTP requests',
  labelNames: ['method', 'route', 'status_code'],
});

registry.registerMetric(httpRequestsTotal);

export default registry;

This sets up the Prometheus registry, collects some basic metrics (like CPU and memory), and also adds a custom metric to count HTTP requests.

Expose the Metrics

Next, let’s make those metrics available through an API route. Create server/routes/metrics.ts:

import registry from './metrics';

export default (req, res) => {
  res.setHeader('Content-Type', registry.contentType);
  res.end(await registry.metrics());
};

Once the app is up and running, head to http://localhost:3000/metrics, and you should see Prometheus-formatted metrics.

It’ll look something like this:

# HELP process_cpu_user_seconds_total Total user CPU time spent in seconds.
# TYPE process_cpu_user_seconds_total counter

# HELP process_cpu_system_seconds_total Total system CPU time spent in seconds.
# TYPE process_cpu_system_seconds_total counter

...

# HELP http_requests_total Total number of HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",route="/api/metrics",status_code="200"} 42

If you want to secure this endpoint, you can add basic authentication or restrict access by IP.

Step 2: Set Up Alloy for Grafana Scraping

Now we need to set up Alloy to scrape those metrics from your Nuxt app. Alloy will help Grafana get the data it needs to visualize it.

Create the Alloy Config

Create a file called config.alloy in your root project directory (or wherever you keep your Alloy config):

logging {
  level = "info"
}

prometheus.scrape "nuxt_app" {
  targets = [{
    __address__ = "host.docker.internal:3000",
    project = "project_name",
  }]
  metrics_path = "/metrics"
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.scrape "node_exporter" {
  targets = [{
    __address__ = "node-exporter:9100",
    instance = "node-exporter",
    project = "project_name",
    environment = env("${CI_ENVIRONMENT_NAME}"),
  }]
  forward_to = [prometheus.remote_write.default.receiver]
}

prometheus.remote_write "default" {
  endpoint {
    url = env("GRAFANA_CLOUD_API_KEY")
    basic_auth {
      username = env("GRAFANA_CLOUD_USERNAME")
      password = env("GRAFANA_CLOUD_PASSWORD")
    }
  }
}

This config tells Alloy how to scrape the metrics from your Nuxt app and forward them to Grafana Cloud (or wherever you’re storing the data). It also sets up basic authentication for your Nuxt app’s /metrics endpoint.

Make sure to set the right environment variables for things like basic auth and Grafana credentials.

If you have one or more enviroment, you can set on prometheus.scrape a enviroment like enviroment: env('CI_ENVIROMENT_NAME')

Step 3: Running Alloy with Docker Compose

We’re going to run both the Nuxt app and Alloy using Docker Compose. It’ll simplify things like networking and orchestration.

Create the Docker Compose File

Here’s a simple docker-compose.yml file to get everything running:

services:
  nuxt_app:
    container_name: nuxt_app
    image: 'node:lts-alpine'
    working_dir: /app
    volumes:
      - './:/app'  # Mount the app code
    environment:
      - NUXT_HOST=0.0.0.0
      - NUXT_PORT=3000
    ports:
      - '3000:3000'
    command: 'npm run dev'

  alloy:
    container_name: alloy
    image: 'grafana/alloy:latest'
    environment:
      CI_ENVIRONMENT_NAME: ${CI_ENVIRONMENT_NAME}
      GRAFANA_CLOUD_USERNAME: ${GRAFANA_CLOUD_USERNAME}
      GRAFANA_CLOUD_PASSWORD: ${GRAFANA_CLOUD_PASSWORD}
      GRAFANA_CLOUD_API_KEY: ${GRAFANA_CLOUD_API_KEY}
    volumes:
      - './config.alloy:/etc/alloy/config.alloy'
    ports:
      - '12345:12345'
    command: 'run --server.http.listen-addr=0.0.0.0:12345 --storage.path=/var/lib/alloy/data /etc/alloy/config.alloy'

This will spin up both services: your Nuxt app and Alloy. The Nuxt app will be available at http://localhost:3000, and Alloy will be at http://localhost:12345.

Run it with:

docker-compose up

Step 4: Visualizing Metrics with Grafana

Now that Prometheus is scraping metrics and Alloy is running, you can hook Grafana up to your Prometheus instance. From there, you can create dashboards to keep an eye on your app’s health and performance in real time.

Conclusion

With this setup, you’ve got a streamlined way to monitor your Nuxt app inside Docker using Prometheus, Grafana, and Alloy. It’s an efficient way to track performance and quickly spot issues before they affect your users.

Hope this guide helped you get things set up! If you have any questions or need some tweaks, feel free to reach out!

References

How to Fix Hydration Mismatch Errors in Nuxt App's

André Escobar — Sat, 01 Mar 2025 01:20:45 +0000

If you've ever seen those annoying "Hydration mismatch" errors in your Nuxt app, you know how frustrating they can be. They usually happen when the HTML your server sends doesn't match what Vue expects when it takes over on the client side. But don’t worry! In this post, I’ll walk you through how to track down these issues and fix them, based on my own experience.

First off all, what is Hydration?

Hydration is the process that happens after Nuxt renders a page on the server and sends it to the browser. First, Nuxt runs your Vue.js code on the server, generating a fully rendered HTML page. The browser downloads this HTML and displays it instantly, just like a traditional server-rendered page. Then, Vue.js takes over, running the same JavaScript code in the browser and attaching event listeners to make the page interactive. This step is called hydration. Once hydration is complete, the page is fully interactive with features like dynamic updates and smooth transitions.

However, if the HTML generated on the server doesn't exactly match what Vue tries to render on the client, you get a hydration mismatch error. Let's dive into what causes these errors and how to fix them.

If you want to get more into the nitty-gritty of rendering modes in Nuxt, check out the docs for a deeper dive.

What Causes Hydration Mismatch?

A hydration mismatch happens when the server and client render things differently. One common issue is using random values like Math.random(), timestamps, or UUIDs in SSR. Another cause is relying on browser-only APIs, such as window, document, or localStorage, which don’t exist during server rendering.

Differences in computed properties or reactive state can also lead to mismatches, especially if they depend on data that changes between SSR and CSR. API calls returning different results on the server and client create inconsistencies too.

Invalid HTML structure is another culprit. Placing a <div> inside a <p> tag, for example, leads to an automatic browser correction that changes the DOM structure, causing discrepancies. Similarly, dynamically rendered elements that apply different attributes between SSR and CSR—such as conditional classes or IDs can trigger hydration errors.

Here’s a simple Vue component that can cause a hydration mismatch:

<template>
  <div>
    <p>{{ randomNumber }}</p>
  </div>
</template>

<script setup>
const randomNumber = Math.random();
</script>

When this component is server-rendered, randomNumber is generated once and included in the initial HTML. However, when the client re-renders it, a new random number is generated, leading to a mismatch between the SSR and CSR output.

Another Example: Number Formatting Issue I Faced This Week

This past week, I ran into a real-world case of hydration mismatch when formatting numbers differently between the server and client.

Consider the following function:

export function floatToLocaleString(
    floatCurrency: number = 0,
    config: Intl.NumberFormatOptions = {}
) {
    const floatCurrencyFixed = convertCurrencyValueToFloat(floatCurrency);
    const twoPlacedFloat = parseInt((floatCurrencyFixed * 100).toString()) / 100;
    const minMaxFractionDigits = Number.isInteger(floatCurrencyFixed) ? 0 : 2;
    return twoPlacedFloat.toLocaleString('pt-BR', {
        minimumFractionDigits: minMaxFractionDigits,
        maximumFractionDigits: minMaxFractionDigits,
        currency: 'BRL',
        ...config
    });
}

This function takes a float and formats it using toLocaleString(). The issue arose because toLocaleString() can produce slightly different outputs depending on the environment (server vs. client). Small rounding variations occurred when converting floating-point numbers, leading to different HTML structures and causing a hydration mismatch.

To fix this, I ensured that the server and client always returned the same formatted value by rounding it explicitly before formatting:

export function floatToLocaleString(
    floatCurrency: number = 0,
    config: Intl.NumberFormatOptions = {}
) {
    const floatCurrencyFixed = convertCurrencyValueToFloat(floatCurrency);
    const roundedValue = Math.ceil(floatCurrencyFixed);
    return new Intl.NumberFormat('pt-BR', {
        style: 'currency',
        currency: 'BRL',
        minimumFractionDigits: 0,
        maximumFractionDigits: 0,
        ...config
    }).format(roundedValue);
}

By explicitly rounding the value with Math.ceil(), I eliminated inconsistencies that arose from fractional differences, ensuring the output remained the same between SSR and CSR. This small change saved me a lot of debugging time!

How to Debug Hydration Mismatch

One of the simplest ways to catch hydration issues is to disable JavaScript in your browser and compare the raw HTML with the fully rendered page. You can do this by opening DevTools, going to the Network tab, and checking the HTML response under the document request. If things look different, you’ve found a clue.

Another useful trick is comparing the page source with the rendered DOM. Right-click on your page, select View Page Source, and compare it with what’s displayed in the Elements tab of DevTools. If there are differences, something is changing after hydration.

For an even easier approach, you can use the nuxt-hydration module by huang-julien/nuxt-hydration, which show exactly where hydration mismatches occur. To install it, use:

yarn|pnpm|npm install -D nuxt-hydration

Once installed, add it to your nuxt.config.ts. When enabled, it will show a interface with hydration mismatches, helping you pinpoint the code that is causing the issue.

While this module can be helpful for identifying which part of your code triggers the hydration error, it’s worth noting that it may not always offer a complete solution. The solution can sometimes be a bit generic, so while it helps you track down the general area of the problem, you may still need to dig deeper to fix the root cause.

Wrapping Up

Hydration mismatches in Nuxt can be frustrating, but they’re definitely fixable. By checking raw HTML, using nuxt-hydration, and ensuring consistency between SSR and CSR, you can avoid these issues and keep your app running smoothly.

However, it’s important to note that these hydration errors aren’t just annoying—they can escalate into more serious problems, like 500 errors, which may crash your app and significantly disrupt the user experience. I’ve personally run into this, and it can be quite challenging to pinpoint and resolve under pressure.

So, don’t ignore hydration errors. It’s easy to let them slide, but accumulating these issues over time can make it harder to fix them all at once. Addressing them early will save you time in the long run and ensure a smoother, more reliable app. The more you delay, the more difficult it becomes to track down and resolve each individual issue.

This is my first post on the DEV.to, and I’m excited to share more of my experiences from my career as a software engineer. I hope to contribute more insights and lessons learned along the way.

Have you run into hydration mismatches before? What tricks helped you fix them? Drop a comment and let’s talk!