Expose Moleculer Service Metrics to Prometheus – A Practical Guide

Problem: How to monitor a Moleculer microservice without reinventing the wheel

When you run a distributed system, you need to know how each service behaves. Traditional logs give you a narrative, but they don’t answer questions like “How many times did this action fail?” or “What’s the average latency of my service?” A common solution is to expose metrics in a format that a monitoring system like Prometheus can scrape. Moleculer already ships a metrics middleware that does most of the heavy lifting, but the details of enabling it, securing the endpoint, and extending it with custom counters are often overlooked.

Thesis: Leveraging Moleculer’s built‑in metrics middleware is a low‑effort, high‑value way to get Prometheus‑ready metrics for every service action.

By simply adding the middleware to your broker configuration, you get a fully‑exposed /metrics endpoint that follows the Prometheus exposition format. You can then add custom metrics, secure the endpoint, and monitor the impact on performance—all without writing a single line of instrumentation code.

1. Enabling the Metrics Middleware

The middleware is part of Moleculer’s core. To activate it, add the metrics option to the broker configuration or use the --metrics CLI flag.

// broker.js
const { ServiceBroker } = require("moleculer");

const broker = new ServiceBroker({
    nodeID: "service-1",
    // Enable metrics middleware
    metrics: true,
    // Optional: expose the endpoint on a custom port
    // metricsPort: 9090,
});

broker.start();

After starting the broker, the /metrics HTTP endpoint will be listening on the broker’s HTTP port (default 3000). A simple curl http://localhost:3000/metrics will output a Prometheus‑compatible text block.

2. Scraping with Prometheus

Configure Prometheus to scrape the endpoint. Below is a minimal prometheus.yml snippet.

scrape_configs:
  - job_name: "moleculer-service"
    static_configs:
      - targets: ["localhost:3000"]

Once Prometheus starts, you’ll see metrics prefixed with moleculer_, such as moleculer_actions_total and moleculer_actions_latency_seconds_bucket. These expose call counts, error counts, and latency histograms per service and action.

3. Adding Custom Metrics

Sometimes you need a metric that isn’t automatically generated. Moleculer exposes the underlying Prometheus client via broker.metrics. Below is an example that registers a gauge tracking the number of active requests per action.

broker.on("started", () => {
    const { Gauge } = broker.metrics;
    const activeRequests = new Gauge({
        name: "service_active_requests",
        help: "Active requests per action",
        labelNames: ["service", "action"],
    });

    broker.middleware("actions", {
        before: (ctx, next) => {
            activeRequests.labels(ctx.service.name, ctx.action.name).inc();
            return next();
        },
        after: (ctx, next) => {
            activeRequests.labels(ctx.service.name, ctx.action.name).dec();
            return next();
        },
    });
});

After adding this, the new gauge appears in the /metrics output and can be queried in Prometheus with service_active_requests{service="user",action="login"}.

4. Security & Performance Trade‑offs

• Exposure risk: The /metrics endpoint is publicly reachable by default. If your service handles sensitive data, expose only non‑sensitive metrics or protect the endpoint behind an authentication layer (e.g., basic auth or an API gateway).
• High‑cardinality labels: Using labels like request IDs or user IDs can explode the number of distinct metric series, consuming memory. Stick to service, action, and status labels.
• Overhead: The middleware adds a small CPU and memory cost. In high‑traffic environments, monitor the broker’s resource usage and consider disabling the middleware for low‑priority services.

Actionable Next Steps

1. Enable the metrics middleware in your production broker config.
2. Secure the /metrics endpoint with a reverse proxy or authentication middleware.
3. Add any custom gauges or counters that match your business KPIs.
4. Configure Prometheus to scrape the endpoint and set up dashboards in Grafana.
5. Monitor the broker’s CPU/memory usage; adjust metric cardinality if needed.

By following these steps, you’ll have a robust, Prometheus‑ready observability layer for all your Moleculer services with minimal code changes.