The Ultimate Guide to Web Application Observability

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 sim

Apr 2, 2025 - 02:46

The Ultimate Guide to Web Application Observability

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!