@layerall/plugin-prometheus 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sidarta Veloso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @layerall/plugin-prometheus
+
+> Prometheus observer pronto para o `Router` do `@layerall/core` — métricas automáticas via `prom-client`.
+
+## Instalação
+
+```bash
+npm install @layerall/core @layerall/plugin-prometheus prom-client
+```
+
+> `prom-client` é uma peer dependency — você precisa instalá-lo no seu backend.
+
+## Métricas expostas
+
+| Métrica | Tipo | Labels |
+|---|---|---|
+| `layerall_requests_total`   | Counter   | `provider`, `operation`, `status` |
+| `layerall_latency_seconds`   | Histogram | `provider`, `operation` |
+| `layerall_attempts_total`   | Counter   | `provider`, `operation`, `result` |
+| `layerall_errors_total`      | Counter   | `provider`, `code` |
+
+O prefixo `layerall_` é configurável (`prefix: 'allx_'`).
+
+## Uso básico
+
+```ts
+import { PrometheusObserver } from '@layerall/plugin-prometheus';
+import { Router } from '@layerall/core';
+
+const observer = new PrometheusObserver();
+const router = new Router({ providers, policy, observer });
+
+// no seu HTTP server
+app.get('/metrics', async (_req, res) => {
+  res.set('Content-Type', observer.metricRegistry.contentType);
+  res.end(await observer.metricRegistry.metrics());
+});
+```
+
+## Factory `createMetricsRouter`
+
+Constrói o Router já com o observer injetado:
+
+```ts
+import { createMetricsRouter } from '@layerall/plugin-prometheus';
+
+const { router, observer } = createMetricsRouter({ providers, policy });
+
+app.get('/metrics', async (_req, res) => {
+  res.set('Content-Type', observer.metricRegistry.contentType);
+  res.end(await observer.metricRegistry.metrics());
+});
+
+await router.execute('create', { data: {} });
+```
+
+## Registry customizada
+
+Por padrão, as métricas vão para o registro global do `prom-client` (qualquer endpoint `/metrics` as vê). Para isolar (útil em testes), passe uma Registry própria:
+
+```ts
+import { Registry } from 'prom-client';
+import { PrometheusObserver } from '@layerall/plugin-prometheus';
+
+const registry = new Registry();
+const observer = new PrometheusObserver({ registry, prefix: 'allx_' });
+```
+
+## Prefixo customizado
+
+```ts
+const observer = new PrometheusObserver({ prefix: 'allx_' });
+// métricas viram allx_requests_total, allx_latency_seconds, ...
+```
+
+## License
+
+MIT © Sidarta Veloso

package/dist/index.d.ts

@@ -0,0 +1,63 @@
+import { Registry } from 'prom-client';
+import { RouterOptions, Observer, AttemptLog, OperationResult, Router } from '@layerall/core';
+
+interface PrometheusObserverOptions {
+    /**
+     * Registry where metrics will be registered. Defaults to the global
+     * `prom-client` registry so `/metrics` endpoints pick them up automatically.
+     * Pass a custom `Registry` to isolate metrics (useful in tests).
+     */
+    registry?: Registry;
+    /**
+     * Prefix applied to all metric names. Defaults to `layerall_`.
+     */
+    prefix?: string;
+}
+/**
+ * Observer that increments Prometheus metrics for every LayerAll Router
+ * execution. Register it on a `Router` (or use `createMetricsRouter`) and
+ * scrape `registry.metrics()` from your `/metrics` endpoint.
+ *
+ * Metrics exposed:
+ * - `<prefix>requests_total{provider,operation,status}` — Counter
+ * - `<prefix>latency_seconds{provider,operation}` — Histogram
+ * - `<prefix>attempts_total{provider,operation,result}` — Counter
+ * - `<prefix>errors_total{provider,code}` — Counter
+ */
+declare class PrometheusObserver implements Observer {
+    private readonly registry;
+    private readonly prefix;
+    private readonly requestsTotal;
+    private readonly latencySeconds;
+    private readonly attemptsTotal;
+    private readonly errorsTotal;
+    constructor(opts?: PrometheusObserverOptions);
+    /** Registry used by this observer — exposes `metrics()` and `contentType`. */
+    get metricRegistry(): Registry;
+    onStart(): void;
+    onAttempt(log: AttemptLog): void;
+    onFinish(res: OperationResult): void;
+}
+interface CreateMetricsRouterOptions extends RouterOptions {
+    prometheus?: PrometheusObserverOptions;
+}
+/**
+ * Convenience factory: builds a `Router` with a `PrometheusObserver` already
+ * wired in. Returns both the router and the observer so you can scrape the
+ * registry from your `/metrics` endpoint.
+ *
+ * @example
+ * ```ts
+ * const { router, observer } = createMetricsRouter({ providers, policy });
+ * server.get('/metrics', (_req, res) => {
+ *   res.set('Content-Type', observer.metricRegistry.contentType);
+ *   res.end(observer.metricRegistry.metrics());
+ * });
+ * ```
+ */
+declare function createMetricsRouter(opts: CreateMetricsRouterOptions): {
+    router: Router;
+    observer: PrometheusObserver;
+};
+
+export { type CreateMetricsRouterOptions, PrometheusObserver, type PrometheusObserverOptions, createMetricsRouter };

package/dist/index.js

@@ -0,0 +1,86 @@
+// src/observer.ts
+import { Counter, Histogram, register as defaultRegistry } from "prom-client";
+import { Router } from "@layerall/core";
+var PrometheusObserver = class {
+  constructor(opts = {}) {
+    this.registry = opts.registry ?? defaultRegistry;
+    this.prefix = opts.prefix ?? "layerall_";
+    const labels = {
+      requests: ["provider", "operation", "status"],
+      latency: ["provider", "operation"],
+      attempts: ["provider", "operation", "result"],
+      errors: ["provider", "code"]
+    };
+    this.requestsTotal = new Counter({
+      name: `${this.prefix}requests_total`,
+      help: "Total LayerAll requests by provider, operation and final status.",
+      labelNames: [...labels.requests],
+      registers: [this.registry]
+    });
+    this.latencySeconds = new Histogram({
+      name: `${this.prefix}latency_seconds`,
+      help: "LayerAll request latency in seconds, by provider and operation.",
+      labelNames: [...labels.latency],
+      buckets: [0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10],
+      registers: [this.registry]
+    });
+    this.attemptsTotal = new Counter({
+      name: `${this.prefix}attempts_total`,
+      help: "Total LayerAll provider attempts by provider, operation and result.",
+      labelNames: [...labels.attempts],
+      registers: [this.registry]
+    });
+    this.errorsTotal = new Counter({
+      name: `${this.prefix}errors_total`,
+      help: "Total LayerAll failed attempts by provider and error code.",
+      labelNames: [...labels.errors],
+      registers: [this.registry]
+    });
+  }
+  /** Registry used by this observer — exposes `metrics()` and `contentType`. */
+  get metricRegistry() {
+    return this.registry;
+  }
+  onStart() {
+  }
+  onAttempt(log) {
+    this.attemptsTotal.inc({
+      provider: log.provider,
+      operation: log.operation,
+      result: log.ok ? "ok" : "fail"
+    });
+    if (!log.ok) {
+      this.errorsTotal.inc({
+        provider: log.provider,
+        code: log.errorCode ?? log.error ?? "unknown"
+      });
+    }
+  }
+  onFinish(res) {
+    this.requestsTotal.inc({
+      provider: res.provider,
+      operation: res.operation,
+      status: res.status
+    });
+    this.latencySeconds.observe(
+      { provider: res.provider, operation: res.operation },
+      res.latencyMs / 1e3
+    );
+  }
+};
+function createMetricsRouter(opts) {
+  const observer = new PrometheusObserver(opts.prometheus);
+  const router = new Router({
+    providers: opts.providers,
+    policy: opts.policy,
+    tenant: opts.tenant,
+    observer,
+    defaultStrategy: opts.defaultStrategy,
+    defaultTimeoutMs: opts.defaultTimeoutMs
+  });
+  return { router, observer };
+}
+export {
+  PrometheusObserver,
+  createMetricsRouter
+};

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@layerall/plugin-prometheus",
+  "version": "0.1.0",
+  "description": "Prometheus observer for LayerAll Router — ready-to-use metrics via prom-client",
+  "keywords": [
+    "prometheus",
+    "metrics",
+    "observability",
+    "layerall",
+    "prom-client",
+    "orchestration"
+  ],
+  "author": "Sidarta Veloso <sidartaveloso@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sidartaveloso/layerall.git",
+    "directory": "packages/plugin-prometheus"
+  },
+  "bugs": {
+    "url": "https://github.com/sidartaveloso/layerall/issues"
+  },
+  "homepage": "https://github.com/sidartaveloso/layerall#readme",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@layerall/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "prom-client": "^15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "prom-client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.30",
+    "@vitest/coverage-v8": "^2.1.0",
+    "prom-client": "^15.1.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --coverage",
+    "test:watch": "vitest",
+    "test:no-coverage": "vitest run"
+  }
+}