@daemonitor/plugins 1.1.28 → 1.1.30

package/dist/plugins/index.js

@@ -10,6 +10,7 @@ import { createNetScanPlugin } from "./monitoring/NetScanPlugin.js";
 import { createSnmpPlugin } from "./monitoring/SnmpPlugin.js";
 import { createThreeCXPlugin } from "./monitoring/ThreeCXPlugin.js";
 import { createTplinkPlugin } from "./monitoring/TplinkPlugin.js";
+import { createPatroniPlugin } from "./monitoring/PatroniPlugin.js";
 // In future, implement other plugin factory functions using the same pattern
 // import { createOSPlugin } from "./monitoring/OSPlugin.js"
 // import { createMongoDBPlugin } from "./monitoring/MongoDBPlugin.js"
@@ -31,6 +32,7 @@ export default {
     Snmp: createSnmpPlugin,
     ThreeCX: createThreeCXPlugin,
     Tplink: createTplinkPlugin,
+    Patroni: createPatroniPlugin,
     // CloudflarePlugin: createCloudflarePlugin,
     // EwelinkPlugin: createEwelinkPlugin,
     // MongoDBPlugin: createMongoDBPlugin,

package/dist/plugins/monitoring/PatroniPlugin.js

@@ -0,0 +1,169 @@
+import { hostname } from "node:os";
+import { createMonitoringPlugin } from "../../lib/MonitoringPlugin.js";
+const DEFAULTS = {
+    url: "http://localhost:8008",
+    lagWarnBytes: 32 * 1024 * 1024, // 32MB: a busy node catching up
+    lagCritBytes: 256 * 1024 * 1024, // 256MB: not keeping up at all
+    requestTimeout: 5000,
+};
+/**
+ * Roles Patroni reports for a member that is holding the primary. `master` is
+ * the pre-3.0 spelling and still shows up on older clusters; `standby_leader` is
+ * the leader of a standby cluster, which is a primary as far as placement is
+ * concerned even though it is replicating from elsewhere.
+ */
+const LEADER_ROLES = new Set(["leader", "master", "primary", "standby_leader"]);
+export function isLeaderRole(role) {
+    return LEADER_ROLES.has(String(role || "").toLowerCase());
+}
+async function getJson(url, cfg) {
+    const headers = { Accept: "application/json" };
+    if (cfg.username) {
+        const raw = `${cfg.username}:${cfg.password ?? ""}`;
+        headers.Authorization = `Basic ${Buffer.from(raw).toString("base64")}`;
+    }
+    const res = await fetch(url, {
+        headers,
+        signal: AbortSignal.timeout(cfg.requestTimeout ?? DEFAULTS.requestTimeout),
+    });
+    // Patroni answers /patroni with 503 on a node that is up but not healthy (a
+    // replica that has lost its leader, a node in maintenance). The BODY is still
+    // the node's state, and that state is the whole reason to ask, so read it
+    // rather than treating the status code as a failure.
+    const text = await res.text();
+    let body = null;
+    try {
+        body = text ? JSON.parse(text) : null;
+    }
+    catch {
+        throw new Error(`non-JSON response from ${url} (HTTP ${res.status})`);
+    }
+    if (!body && !res.ok)
+        throw new Error(`HTTP ${res.status} from ${url}`);
+    return body;
+}
+/**
+ * Bytes this member is behind the leader.
+ *
+ * /cluster reports `lag` per member and it is already in bytes, but it comes
+ * back as the string "unknown" on a member the DCS cannot currently see. That
+ * must stay distinct from 0: "unknown" means no information, and coercing it to
+ * zero reports a node nobody can reach as perfectly caught up.
+ */
+function lagOf(member) {
+    const raw = member?.lag;
+    if (raw == null)
+        return null;
+    const n = Number(raw);
+    return Number.isFinite(n) ? n : null;
+}
+function normaliseMembers(cluster) {
+    const list = Array.isArray(cluster?.members) ? cluster.members : [];
+    return list.map((m) => ({
+        name: String(m?.name ?? "unknown"),
+        role: String(m?.role ?? "unknown").toLowerCase(),
+        state: String(m?.state ?? "unknown").toLowerCase(),
+        host: m?.host ?? undefined,
+        port: typeof m?.port === "number" ? m.port : undefined,
+        apiUrl: m?.api_url ?? undefined,
+        timeline: typeof m?.timeline === "number" ? m.timeline : undefined,
+        lagBytes: lagOf(m),
+    }));
+}
+export async function collectPatroni(cfg) {
+    const base = String(cfg.url || DEFAULTS.url).replace(/\/+$/, "");
+    // Ask for both, and do not let one failure hide the other. A node whose own
+    // /patroni is 503-ing can still return a perfectly good /cluster, and that is
+    // the reading that says whether the cluster as a whole has a leader.
+    const [selfRes, clusterRes] = await Promise.allSettled([
+        getJson(`${base}/patroni`, cfg),
+        getJson(`${base}/cluster`, cfg),
+    ]);
+    if (selfRes.status === "rejected" && clusterRes.status === "rejected") {
+        throw new Error(String(selfRes.reason?.message || selfRes.reason));
+    }
+    const self = selfRes.status === "fulfilled" ? selfRes.value : null;
+    const cluster = clusterRes.status === "fulfilled" ? clusterRes.value : null;
+    const members = normaliseMembers(cluster);
+    const scope = self?.patroni?.scope || cluster?.scope || undefined;
+    // Patroni's member name defaults to the hostname but is configurable, and the
+    // server matches leader-by-name against it, so report what Patroni calls this
+    // node rather than what the OS does.
+    const member = self?.patroni?.name || self?.name || hostname();
+    const selfRole = String(self?.role ?? "unknown").toLowerCase();
+    const leaderMember = members.find((m) => isLeaderRole(m.role));
+    const selfMember = members.find((m) => m.name === member);
+    return {
+        kind: "patroni",
+        name: scope || "patroni",
+        scope,
+        member,
+        reachable: true,
+        // Self-reported role. The server trusts this over any name matching: a node
+        // saying "I am the leader" identifies the leader's SYSTEM exactly, with no
+        // guessing about which host a Patroni member name belongs to.
+        role: selfRole,
+        isLeader: isLeaderRole(selfRole),
+        state: String(self?.state ?? "unknown").toLowerCase(),
+        timeline: self?.timeline ?? selfMember?.timeline ?? null,
+        serverVersion: self?.server_version ?? null,
+        patroniVersion: self?.patroni?.version ?? null,
+        // A cluster with no leader is either mid-election (seconds) or stuck
+        // (forever). The server applies a grace window rather than paging on the gap.
+        leader: leaderMember?.name ?? null,
+        hasLeader: !!leaderMember,
+        // Patroni sets this while the DCS lock is not held by anyone.
+        clusterUnlocked: self?.cluster_unlocked === true,
+        // Maintenance mode: failover is disabled, so a dead leader will NOT be
+        // replaced. Worth surfacing because everything else looks normal.
+        paused: self?.pause === true,
+        pendingRestart: self?.pending_restart === true,
+        lagBytes: selfMember?.lagBytes ?? null,
+        lagWarnBytes: cfg.lagWarnBytes ?? DEFAULTS.lagWarnBytes,
+        lagCritBytes: cfg.lagCritBytes ?? DEFAULTS.lagCritBytes,
+        members,
+        memberCount: members.length,
+        runningCount: members.filter((m) => m.state === "running" || m.state === "streaming").length,
+        // Set when /patroni answered but /cluster did not, or vice versa: the report
+        // is partial and the server should not read a missing leader as no leader.
+        partial: !self || !cluster,
+        timestamp: Date.now(),
+    };
+}
+export function createPatroniPlugin() {
+    let refreshTimer = null;
+    const refreshFn = async (plugin) => {
+        const cfg = (plugin.config || {});
+        const uid = cfg.uniqueId || "patroni";
+        try {
+            await plugin.send(await collectPatroni(cfg), uid);
+        }
+        catch (e) {
+            // Report the failure rather than going quiet. Silence from this plugin is
+            // indistinguishable from the agent being dead, and "Patroni's API is not
+            // answering on this node" is itself a finding worth an alert.
+            await plugin.send({
+                kind: "patroni",
+                name: "patroni",
+                member: hostname(),
+                reachable: false,
+                error: String(e?.message || e).slice(0, 200),
+                timestamp: Date.now(),
+            }, uid);
+        }
+    };
+    const monitorFn = async (plugin) => {
+        await refreshFn(plugin);
+        // 30s by default rather than the usual 60s: this is the input to leader
+        // placement, so the window in which daemonitor believes the old leader is
+        // still the leader is bounded by this interval.
+        refreshTimer = setInterval(() => refreshFn(plugin), plugin.config?.refreshInterval || 30000);
+    };
+    const teardownFn = async () => {
+        if (refreshTimer)
+            clearInterval(refreshTimer);
+        refreshTimer = null;
+    };
+    return createMonitoringPlugin("patroni", "patroni", "Patroni HA Postgres monitor (leader identity, member roles, replication lag)", async () => { }, monitorFn, refreshFn, teardownFn);
+}
+export default createPatroniPlugin;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daemonitor/plugins",
-  "version": "1.1.28",
+  "version": "1.1.30",
   "description": "daemonitor plugins",
   "types": "types/index.d.ts",
   "main": "dist/index.js",