@ecdt/server-common 1.1.0 → 1.4.0

package/README.md

@@ -79,6 +79,54 @@ app.use(expressCors({ origins: [...], extraHeaders: ["X-Custom-Header"] }));
 app.use(expressCors({ origins: [...], headers: ["Content-Type"], methods: ["GET", "POST"] }));
 ```
 
+### `setupRedMetrics(app, options?)`
+
+Instrumenta o servidor com métricas **RED** (Rate, Errors, Duration) e expõe o endpoint `/metrics` no formato Prometheus, em uma linha. Todas as requisições passam a alimentar o histograma `http_request_duration_seconds{method, route, status_code}`.
+
+> Requer `prom-client` instalado no microsserviço (é uma `peerDependency`).
+
+| Opção | Tipo | Descrição |
+|---|---|---|
+| `serviceName` | `string` | Nome do MS; vira o label `service` em todas as métricas. Fallback: env `SERVICE_NAME` > `npm_package_name` |
+| `metricsPath` | `string` | Caminho do endpoint de métricas. Default: `/metrics` |
+| `buckets` | `number[]` | Buckets de latência (segundos). Default: `[0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]` |
+| `collectDefaultMetrics` | `boolean` | Coletar métricas default do Node (heap, event loop, GC...). Default: `true` |
+| `registry` | `Registry` | Registry alternativo do prom-client. Default: registry global |
+
+```js
+const express = require("express");
+const { setupRedMetrics } = require("@ecdt/server-common");
+
+const app = express();
+
+// ANTES de montar as rotas:
+setupRedMetrics(app, { serviceName: "dev-mkt-busca" });
+
+app.get("/users/:id", (req, res) => res.json({ id: req.params.id }));
+
+app.listen(3000);
+```
+
+O label `route` usa o **template** da rota (`/users/:id`), nunca a URL crua — isso mantém a cardinalidade (e o custo de ingestão) sob controle.
+
+#### Consultas (PromQL) habilitadas
+
+```promql
+# Latência p95 por endpoint
+histogram_quantile(0.95, sum by (le, route)(rate(http_request_duration_seconds_bucket{service="dev-mkt-busca"}[5m])))
+
+# Taxa de requisições por segundo (RPS)
+sum(rate(http_request_duration_seconds_count{service="dev-mkt-busca"}[1m]))
+
+# Erros 5xx por segundo
+sum(rate(http_request_duration_seconds_count{service="dev-mkt-busca",status_code=~"5.."}[5m]))
+
+# Endpoints que mais geram erro
+topk(10, sum by (route)(rate(http_request_duration_seconds_count{service="dev-mkt-busca",status_code=~"5.."}[5m])))
+```
+
+Para wiring manual, a lib também exporta `redMetricsMiddleware(options?)` e `metricsHandler(registry?)`.
+
 ---
 
 ## Instalação

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecdt/server-common",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "description": "Conjunto de ferramentas e configurações comuns nos servidores da Econodata",
   "main": "src/index.js",
   "scripts": {
@@ -11,5 +11,8 @@
   "dependencies": {
     "body-parser": "^2.2.2",
     "cors": "^2.8.6"
+  },
+  "peerDependencies": {
+    "prom-client": "^15.0.0"
   }
 }

package/src/index.d.ts

@@ -38,4 +38,38 @@ declare module '@ecdt/server-common' {
      * Uso: app.use(expressCors({ origins: ["https://app.econodata.com.br"] }))
      */
     export function expressCors(options: ExpressCorsOptions): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+
+    export interface RedMetricsOptions {
+        /** Nome do microsserviço. Vira o label `service` em todas as métricas. Fallback: env SERVICE_NAME > npm_package_name. */
+        serviceName?: string;
+        /** Caminho do endpoint de métricas. Default: '/metrics'. */
+        metricsPath?: string;
+        /** Buckets do histograma de latência, em segundos. */
+        buckets?: number[];
+        /** Coletar métricas default do Node (heap, event loop, GC...). Default: true. */
+        collectDefaultMetrics?: boolean;
+        /** Registry alternativo do prom-client. Default: registry global. */
+        registry?: unknown;
+    }
+
+    /**
+     * Configura as métricas RED (Rate, Errors, Duration) no app express: registra o
+     * middleware de medição (antes das rotas) e o endpoint /metrics.
+     *
+     * Alimenta o histograma `http_request_duration_seconds{method,route,status_code}`,
+     * que habilita latência por endpoint, latência total, RPS, erros e top endpoints com erro.
+     *
+     * Requer `prom-client` instalado no microsserviço (peerDependency).
+     *
+     * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
+     */
+    export function setupRedMetrics(app: unknown, options?: RedMetricsOptions): void;
+
+    /** Middleware do express que alimenta o histograma `http_request_duration_seconds`. */
+    export function redMetricsMiddleware(
+        options?: Pick<RedMetricsOptions, "buckets" | "registry">
+    ): (req: unknown, res: unknown, next: (err?: unknown) => void) => void;
+
+    /** Handler do endpoint de métricas (exposição no formato Prometheus). */
+    export function metricsHandler(registry?: unknown): (req: unknown, res: unknown) => void;
 }

package/src/index.js

@@ -1,6 +1,8 @@
 const bodyParser = require("body-parser");
 const { devMktTokenSanitaze } = require("./services/tokenService.js");
 const { expressCors } = require("./services/corsService.js");
+const { setupGracefulShutdown } = require("./services/shutdownService.js");
+const { setupRedMetrics, redMetricsMiddleware, metricsHandler } = require("./services/redMetricsService.js");
 
 function expressCommonMiddlewares({ cookieName } = {}){
     return [bodyParser.text(), bodyParser.json(), bodyParser.urlencoded({extended: false}), devMktTokenSanitaze({ cookieName })];
@@ -9,4 +11,4 @@ function expressCommonMiddlewares({ cookieName } = {}){
 
 
 
-module.exports = { expressCommonMiddlewares, expressCors }
+module.exports = { expressCommonMiddlewares, expressCors, setupGracefulShutdown, setupRedMetrics, redMetricsMiddleware, metricsHandler }

package/src/services/redMetricsService.js

@@ -0,0 +1,108 @@
+const client = require("prom-client");
+
+const METRIC_NAME = "http_request_duration_seconds";
+const DEFAULT_BUCKETS = [0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10];
+
+/**
+ * get-or-create do histograma. Reaproveita a métrica se já registrada, evitando
+ * o erro "A metric with the name ... has already been registered" em import duplo
+ * ou múltiplas chamadas de setup.
+ * @param {import("prom-client").Registry} registry
+ * @param {number[]} buckets
+ */
+function getHistogram(registry, buckets) {
+    const existing = registry.getSingleMetric(METRIC_NAME);
+    if (existing) return existing;
+    return new client.Histogram({
+        name: METRIC_NAME,
+        help: "Duração das requisições HTTP, em segundos",
+        labelNames: ["method", "route", "status_code"],
+        buckets,
+        registers: [registry],
+    });
+}
+
+/**
+ * Extrai o TEMPLATE da rota (ex.: "/users/:id"), com o prefixo de routers aninhados.
+ * Nunca usa a URL crua — evita explosão de cardinalidade (e custo de ingestão no GMP).
+ */
+function routeTemplate(req) {
+    const path = req.route && req.route.path;
+    if (!path) return "unmatched";
+    const p = Array.isArray(path) ? path[0] : path;
+    return `${req.baseUrl || ""}${p}` || "unmatched";
+}
+
+/**
+ * Middleware do express que mede cada requisição e alimenta o histograma RED
+ * (http_request_duration_seconds) com os labels method, route e status_code.
+ *
+ * @param {object} [options]
+ * @param {number[]} [options.buckets] - buckets de latência em segundos
+ * @param {import("prom-client").Registry} [options.registry] - registry (default: global do prom-client)
+ * @returns middleware do express
+ */
+function redMetricsMiddleware({ buckets, registry } = {}) {
+    const reg = registry || client.register;
+    const histogram = getHistogram(reg, buckets || DEFAULT_BUCKETS);
+    return function (req, res, next) {
+        const stop = histogram.startTimer();
+        // 'finish' dispara após a rota resolver -> req.route já está preenchido aqui.
+        res.on("finish", () =>
+            stop({
+                method: req.method,
+                route: routeTemplate(req),
+                status_code: String(res.statusCode),
+            })
+        );
+        next();
+    };
+}
+
+/**
+ * Handler do endpoint de métricas (exposição no formato Prometheus).
+ * @param {import("prom-client").Registry} [registry] - default: global do prom-client
+ * @returns handler do express
+ */
+function metricsHandler(registry = client.register) {
+    return async function (_req, res) {
+        res.set("Content-Type", registry.contentType);
+        res.end(await registry.metrics());
+    };
+}
+
+/**
+ * Configura as métricas RED no app express em uma linha. Registra o middleware
+ * (aplique ANTES das rotas) e o endpoint /metrics.
+ *
+ * Uso: setupRedMetrics(app, { serviceName: "dev-mkt-busca" })
+ *
+ * @param {object} app - instância do express
+ * @param {object} [options]
+ * @param {string} [options.serviceName] - nome do MS; vira o label `service` em todas as métricas.
+ *        Fallback: env SERVICE_NAME > npm_package_name.
+ * @param {string} [options.metricsPath] - caminho do endpoint de métricas (default: "/metrics")
+ * @param {number[]} [options.buckets] - buckets de latência em segundos
+ * @param {boolean} [options.collectDefaultMetrics] - coletar métricas default do Node
+ *        (heap, event loop, GC...). Default: true.
+ * @param {import("prom-client").Registry} [options.registry] - registry alternativo (default: global)
+ */
+function setupRedMetrics(app, options = {}) {
+    const registry = options.registry || client.register;
+    const serviceName =
+        options.serviceName || process.env.SERVICE_NAME || process.env.npm_package_name;
+    if (serviceName) registry.setDefaultLabels({ service: serviceName });
+
+    // guard: collectDefaultMetrics chamado 2x joga "already registered".
+    if (
+        options.collectDefaultMetrics !== false &&
+        !registry.getSingleMetric("process_cpu_user_seconds_total")
+    ) {
+        client.collectDefaultMetrics({ register: registry });
+    }
+
+    app.use(redMetricsMiddleware({ buckets: options.buckets, registry }));
+    app.get(options.metricsPath || "/metrics", metricsHandler(registry));
+}
+
+module.exports = { setupRedMetrics, redMetricsMiddleware, metricsHandler };

package/src/services/shutdownService.js

@@ -0,0 +1,54 @@
+/**
+ * Graceful shutdown padrão dos microsserviços da Econodata em Kubernetes.
+ * @param {import('http').Server} server - servidor retornado por http.createServer(app).listen(...) ou app.listen(...)
+ * @param {object} [options]
+ * @param {() => (Promise<void>|void)} [options.onShutdown] - cleanup extra (fechar pools, Redis, etc.) executado após o server fechar
+ * @param {number} [options.failsafeTimeoutMs] - tempo máximo do graceful antes de forçar a saída (default 10s: grace 40s − 20s de preStop)
+ */
+function setupGracefulShutdown(server, { onShutdown, failsafeTimeoutMs = 10 * 1000 } = {}) {
+    let shuttingDown = false;
+    const gracefulShutdown = signal => {
+        if (shuttingDown) return;
+        shuttingDown = true;
+        console.warn(JSON.stringify({
+            severity: 'WARNING',
+            message: `[shutdown] ${signal} recebido — encerrando`,
+        }));
+
+        server.close(async err => {
+            if (err) {
+                console.error('[shutdown] Erro ao fechar o server HTTP:', err.message || err);
+            } else {
+                console.warn(JSON.stringify({
+                    severity: 'WARNING',
+                    message: '[shutdown] Server HTTP fechado, conexões em voo drenadas',
+                }));
+            }
+            if (onShutdown) {
+                try {
+                    await onShutdown();
+                } catch (cleanupErr) {
+                    console.warn(JSON.stringify({
+                        severity: 'WARNING',
+                        message: `[shutdown] Falha no cleanup: ${cleanupErr.message || cleanupErr}`,
+                    }));
+                }
+            }
+            process.exit(err ? 1 : 0);
+        });
+
+        // fecha conexões keep-alive ociosas, senão um keepAliveTimeout alto segura o close()
+        server.closeIdleConnections();
+
+        // failsafe antes do SIGKILL
+        setTimeout(() => {
+            console.error('[shutdown] Timeout no graceful shutdown, forçando saída');
+            process.exit(1);
+        }, failsafeTimeoutMs).unref();
+    };
+
+    process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
+    process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+}
+
+module.exports = { setupGracefulShutdown };