hobots 2.2.0 → 2.3.0

package/README.md

@@ -44,7 +44,7 @@ Hobots.init({
   clientSecret: 'hb_<64 hex>',
   instanceId: 'vm-cliente-01',
   heartbeat: true,                              // telemetria: "estou vivo" a cada 30s
-  tasks: { pollIntervalMs: 5_000 },             // execução sob demanda
+  tasks: { pollIntervalMs: 2_000 },             // execução sob demanda
 });
 
 Hobots.register('processar-nfe', async (params, ctx) => {
@@ -99,6 +99,7 @@ Hobots.init({
 | `tracesSampleRate` | `number` | `1` | amostragem de transactions (0..1) |
 | `maxBreadcrumbs` | `number` | `100` | tamanho do buffer de breadcrumbs |
 | `captureUnhandled` | `boolean` | `true` | handlers globais de erro (`uncaughtException`/`unhandledRejection`) |
+| `machineMetrics` | `boolean` | `true` | CPU/memória/disco no heartbeat, no poll e em `contexts.machine` dos eventos |
 | `heartbeat` | `boolean \| HeartbeatOptions` | `false` | heartbeat periódico (`true` usa defaults) |
 | `tasks` | `boolean \| TasksOptions` | `false` | habilita a execução sob demanda (`true` usa defaults) — veja [Tasks](#tasks-execução-sob-demanda) |
 | `beforeSend` | `(event) => event \| null` | — | edita/descarta evento (retorne `null` para descartar) |
@@ -196,6 +197,17 @@ Hobots.init({
 
 O heartbeat é **essencial** para agentes só de telemetria; com `tasks: true` ele é **opcional**, porque o poll de tasks já marca a presença do agente no painel. Conceito: [Heartbeat](./docs/concepts.md#heartbeat).
 
+### Recursos da máquina (CPU, memória, disco)
+
+Ligado por padrão em Node (`machineMetrics: true`), o SDK coleta CPU do sistema, memória, disco do volume do bot e RSS/CPU do próprio processo — **sem dependência nova** e sem timer próprio: a leitura pega carona em cada heartbeat e em cada poll de tasks (série da instância em **Instâncias → recursos da máquina**) e vai como `contexts.machine` em cada evento (card **"máquina no momento do erro"** no detalhe da issue). Assim dá para responder se o ambiente tem recurso suficiente e se um erro coincidiu com CPU/memória no limite.
+
+```js
+Hobots.init({ clientSecret, instanceId: 'vm-01', heartbeat: true }); // coleta ligada
+Hobots.init({ clientSecret, instanceId: 'vm-01', machineMetrics: false }); // desliga
+```
+
+O snapshot tem ~600 bytes (teto do servidor: 4 KiB). Formato em [Protocolo → MachineSnapshot](./docs/protocol.md#machinesnapshot).
+
 ### Flush e close
 
 ```js
@@ -241,7 +253,7 @@ process.on('SIGINT', () => {
 
 | Opção (`TasksOptions`) | Tipo | Default | Descrição |
 | --- | --- | --- | --- |
-| `pollIntervalMs` | `number` | `5000` | intervalo entre polls sem trabalho (mínimo `1000`) |
+| `pollIntervalMs` | `number` | `2000` | intervalo entre polls sem trabalho (mínimo `1000`) |
 | `concurrency` | `number` | `1` | runs simultâneas (clamp 1..5) |
 | `taskTimeoutMs` | `number` | — | timeout client-side por run (não mata o handler; servidor é o backstop) |
 | `logFlushIntervalMs` | `number` | `2000` | intervalo do envio incremental de logs |

package/dist/index.cjs

@@ -161,7 +161,7 @@ function scrubSecrets(text) {
 
 // src/utils.ts
 var SDK_NAME = "hobots";
-var SDK_VERSION = true ? "2.2.0" : "0.0.0-dev";
+var SDK_VERSION = true ? "2.3.0" : "0.0.0-dev";
 function isNode() {
   return typeof process !== "undefined" && typeof process.versions?.node === "string";
 }
@@ -454,6 +454,7 @@ var Client = class {
   #options;
   #config;
   transport;
+  machine;
   constructor(options, config = resolveConfig(options)) {
     this.#options = options;
     this.debug = !!options.debug;
@@ -473,6 +474,10 @@ var Client = class {
   get config() {
     return this.#config;
   }
+  /** Sampler de recursos da máquina — cada evento passa a levar `contexts.machine`. */
+  attachMachineSampler(sampler) {
+    this.machine = sampler;
+  }
   /** Serialização explícita nunca inclui o secret. */
   toJSON() {
     return { sdk: SDK_NAME, version: SDK_VERSION, baseUrl: this.#config.baseUrl };
@@ -504,6 +509,8 @@ var Client = class {
   prepareEvent(event, hint, scope2) {
     const tags = { ...this.options.tags, ...scope2.tags, ...event.tags, ...hint?.tags };
     const extra = { ...scope2.extra, ...event.extra, ...hint?.extra };
+    const sampled = this.machine?.sample();
+    const machine = sampled ? { machine: sampled } : {};
     return {
       ...event,
       type: hint?.type ?? event.type ?? scope2.type ?? "error",
@@ -512,7 +519,7 @@ var Client = class {
       tags: Object.keys(tags).length > 0 ? tags : void 0,
       extra: Object.keys(extra).length > 0 ? extra : void 0,
       user: event.user ?? scope2.user,
-      contexts: { ...runtimeContexts(), ...scope2.contexts, ...event.contexts },
+      contexts: { ...runtimeContexts(), ...machine, ...scope2.contexts, ...event.contexts },
       breadcrumbs: scope2.breadcrumbs.length > 0 ? [...scope2.breadcrumbs] : event.breadcrumbs,
       fingerprint: hint?.fingerprint ?? event.fingerprint ?? scope2.fingerprint
     };
@@ -547,8 +554,9 @@ var DEFAULT_INTERVAL_MS = 3e4;
 var MIN_REPORTED_INTERVAL_MS = 1e3;
 var MAX_REPORTED_INTERVAL_MS = 9e5;
 var Heartbeat = class {
-  constructor(client2, options = {}, instanceId) {
+  constructor(client2, options = {}, instanceId, sampler) {
     this.client = client2;
+    this.sampler = sampler;
     this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
     this.instanceId = instanceId;
     this.name = options.name ?? instanceId;
@@ -587,7 +595,9 @@ var Heartbeat = class {
       name: this.name,
       interval_ms: Math.min(Math.max(this.intervalMs, MIN_REPORTED_INTERVAL_MS), MAX_REPORTED_INTERVAL_MS),
       timestamp: nowISO(),
-      metadata: this.metadata
+      metadata: this.metadata,
+      // recursos da máquina a cada beat — a série da instância no app
+      machine: this.sampler?.sample()
     });
   }
 };
@@ -618,50 +628,184 @@ function hasInstalledGlobalHandlers() {
   return installed;
 }
 function installGlobalHandlers(client2, getScope) {
-  if (installed) return;
+  if (installed) return () => void 0;
   installed = true;
   if (isNode()) {
-    process.on(
-      "uncaughtException",
-      markInternal((error) => {
-        client2.captureException(error, { type: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
-        void client2.flush(2e3).then(async () => {
-          if (externalListenerCount("uncaughtException") === 0) {
-            await awaitEmergencyTasks(EMERGENCY_REPORT_CAP_MS);
-            console.error(error);
-            process.exit(1);
-          }
-        });
-      })
-    );
-    process.on(
-      "unhandledRejection",
-      markInternal((reason) => {
-        client2.captureException(reason, { type: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
-        void client2.flush(2e3);
-      })
-    );
-    process.on(
-      "beforeExit",
-      markInternal(() => {
-        void client2.flush(2e3);
-      })
-    );
-    return;
+    const onUncaught = markInternal((error) => {
+      client2.captureException(error, { type: "fatal", tags: { mechanism: "uncaughtException" } }, getScope());
+      void client2.flush(2e3).then(async () => {
+        if (externalListenerCount("uncaughtException") === 0) {
+          await awaitEmergencyTasks(EMERGENCY_REPORT_CAP_MS);
+          console.error(error);
+          process.exit(1);
+        }
+      });
+    });
+    const onRejection = markInternal((reason) => {
+      client2.captureException(reason, { type: "error", tags: { mechanism: "unhandledRejection" } }, getScope());
+      void client2.flush(2e3);
+    });
+    const onBeforeExit = markInternal(() => {
+      void client2.flush(2e3);
+    });
+    process.on("uncaughtException", onUncaught);
+    process.on("unhandledRejection", onRejection);
+    process.on("beforeExit", onBeforeExit);
+    return () => {
+      process.off("uncaughtException", onUncaught);
+      process.off("unhandledRejection", onRejection);
+      process.off("beforeExit", onBeforeExit);
+      installed = false;
+    };
   }
   if (typeof window !== "undefined") {
-    window.addEventListener("error", (event) => {
+    const onError = (event) => {
       client2.captureException(event.error ?? event.message, { tags: { mechanism: "onerror" } }, getScope());
-    });
-    window.addEventListener("unhandledrejection", (event) => {
+    };
+    const onRejection = (event) => {
       client2.captureException(event.reason, { tags: { mechanism: "onunhandledrejection" } }, getScope());
-    });
-    window.addEventListener("pagehide", () => {
+    };
+    const onPageHide = () => {
       void client2.flush(1e3);
-    });
+    };
+    window.addEventListener("error", onError);
+    window.addEventListener("unhandledrejection", onRejection);
+    window.addEventListener("pagehide", onPageHide);
+    return () => {
+      window.removeEventListener("error", onError);
+      window.removeEventListener("unhandledrejection", onRejection);
+      window.removeEventListener("pagehide", onPageHide);
+      installed = false;
+    };
   }
+  return () => {
+    installed = false;
+  };
 }
 
+// src/machine.ts
+var MIN_CPU_WINDOW_MS = 1e3;
+var round1 = (value) => Math.round(value * 10) / 10;
+var clampPercent = (value) => Math.min(100, Math.max(0, value));
+var MachineSampler = class {
+  constructor(instanceId, logger) {
+    this.instanceId = instanceId;
+    this.logger = logger;
+  }
+  os;
+  fs;
+  ready = false;
+  prevCpu;
+  prevProcessCpu;
+  prevAt = 0;
+  lastCpuPercent = null;
+  lastProcessCpuPercent = null;
+  /** Carrega os módulos e tira a leitura-base de CPU (a primeira amostra ainda sai com cpu_percent null). */
+  async start() {
+    if (!isNode()) return;
+    try {
+      this.os = await import("os");
+      this.fs = await import("fs");
+      this.prevCpu = this.cpuTotals();
+      this.prevProcessCpu = process.cpuUsage();
+      this.prevAt = Date.now();
+      this.ready = true;
+    } catch (error) {
+      this.logger.debug("m\xE9tricas de m\xE1quina indispon\xEDveis neste runtime", error);
+    }
+  }
+  sample() {
+    if (!this.ready || !this.os) return void 0;
+    try {
+      const os = this.os;
+      const cpuCount = Math.max(1, os.cpus().length);
+      this.updateCpu(cpuCount);
+      const snapshot = {
+        sampled_at: nowISO(),
+        instance_id: this.instanceId,
+        hostname: os.hostname(),
+        os: process.platform,
+        arch: process.arch,
+        cpu_count: cpuCount,
+        cpu_percent: this.lastCpuPercent,
+        process: {
+          pid: process.pid,
+          uptime_s: Math.round(process.uptime()),
+          cpu_percent: this.lastProcessCpuPercent
+        },
+        source: "stdlib"
+      };
+      if (process.platform !== "win32") {
+        const load = os.loadavg()[0];
+        if (typeof load === "number" && Number.isFinite(load)) snapshot.load_1 = round1(load);
+      }
+      const memTotal = os.totalmem();
+      const memFree = os.freemem();
+      if (memTotal > 0) {
+        snapshot.mem_total_bytes = memTotal;
+        snapshot.mem_available_bytes = memFree;
+        snapshot.mem_percent = round1(clampPercent((memTotal - memFree) / memTotal * 100));
+      }
+      const disk = this.diskUsage();
+      if (disk) Object.assign(snapshot, disk);
+      const mem = process.memoryUsage();
+      snapshot.process.rss_bytes = mem.rss;
+      snapshot.process.heap_used_bytes = mem.heapUsed;
+      return snapshot;
+    } catch (error) {
+      this.logger.debug("falha ao coletar m\xE9tricas de m\xE1quina", error);
+      return void 0;
+    }
+  }
+  cpuTotals() {
+    let busy = 0;
+    let total = 0;
+    for (const cpu of this.os.cpus()) {
+      const t = cpu.times;
+      const cpuBusy = t.user + t.nice + t.sys + t.irq;
+      busy += cpuBusy;
+      total += cpuBusy + t.idle;
+    }
+    return { busy, total };
+  }
+  /** Média desde a leitura anterior; leituras com menos de 1s de janela reutilizam a última média. */
+  updateCpu(cpuCount) {
+    const now = Date.now();
+    const elapsedMs = now - this.prevAt;
+    if (elapsedMs < MIN_CPU_WINDOW_MS) return;
+    const cpu = this.cpuTotals();
+    if (this.prevCpu) {
+      const total = cpu.total - this.prevCpu.total;
+      if (total > 0) this.lastCpuPercent = round1(clampPercent((cpu.busy - this.prevCpu.busy) / total * 100));
+    }
+    this.prevCpu = cpu;
+    const usage = process.cpuUsage(this.prevProcessCpu);
+    const usedMicros = usage.user + usage.system;
+    this.lastProcessCpuPercent = round1(clampPercent(usedMicros / (elapsedMs * 1e3 * cpuCount) * 100));
+    this.prevProcessCpu = process.cpuUsage();
+    this.prevAt = now;
+  }
+  diskUsage() {
+    const statfs = this.fs?.statfsSync;
+    if (typeof statfs !== "function") return void 0;
+    try {
+      const path = process.cwd();
+      const stat = statfs(path);
+      const total = stat.bsize * stat.blocks;
+      const free = stat.bsize * stat.bavail;
+      if (total <= 0) return void 0;
+      return {
+        disk_path: path,
+        disk_total_bytes: total,
+        disk_free_bytes: free,
+        disk_percent: round1(clampPercent((total - free) / total * 100))
+      };
+    } catch {
+      return void 0;
+    }
+  }
+};
+
 // src/scope.ts
 var Scope = class _Scope {
   tags = {};
@@ -1980,7 +2124,10 @@ var TaskAgent = class {
             // o servidor calcula a tolerância de offline (3×) a partir disto em
             // agentes poll-only — sem o campo, um poll lento flaparia offline/online.
             // Clampado à faixa aceita pelo schema do poll (1s..15min).
-            poll_interval_ms: Math.min(Math.max(this.pollIntervalMs, 1e3), 9e5)
+            poll_interval_ms: Math.min(Math.max(this.pollIntervalMs, 1e3), 9e5),
+            // recursos da máquina — alimenta a série da instância em agentes sem heartbeat
+            // (o servidor grava no máx. 1 ponto/30s por instância)
+            machine: this.options.machineSampler?.sample()
           },
           max: Math.min(MAX_CONCURRENCY, this.concurrency - this.activeRuns.size),
           tasks: [...this.registry.keys()]
@@ -2128,7 +2275,9 @@ var DEFAULT_MAX_BREADCRUMBS = 100;
 var client;
 var scope = new Scope();
 var heartbeat;
+var machineSampler;
 var agent;
+var uninstallGlobalHandlers;
 var registry = /* @__PURE__ */ new Map();
 var warnedTasksDisabled = false;
 function init(options) {
@@ -2141,21 +2290,26 @@ function init(options) {
     void agent.stop(0);
     agent = void 0;
   }
+  uninstallGlobalHandlers?.();
+  uninstallGlobalHandlers = void 0;
   warnedTasksDisabled = false;
   const config = resolveConfig(options);
   client = new Client(options, config);
+  machineSampler = options.machineMetrics === false ? void 0 : new MachineSampler(options.instanceId, client.logger);
+  void machineSampler?.start();
+  client.attachMachineSampler(machineSampler);
   if (options.captureUnhandled !== false) {
-    installGlobalHandlers(client, () => scope);
+    uninstallGlobalHandlers = installGlobalHandlers(client, () => scope);
   }
   if (options.heartbeat) {
     const heartbeatOptions = options.heartbeat === true ? {} : options.heartbeat;
-    heartbeat = new Heartbeat(client, heartbeatOptions, options.instanceId);
+    heartbeat = new Heartbeat(client, heartbeatOptions, options.instanceId, machineSampler);
     heartbeat.start();
   }
   if (options.tasks) {
     const tasksOptions = options.tasks === true ? {} : options.tasks;
     agent = new TaskAgent(
-      { ...tasksOptions, config, instanceId: options.instanceId, debug: options.debug, client },
+      { ...tasksOptions, config, instanceId: options.instanceId, debug: options.debug, client, machineSampler },
       registry
     );
   }