debug mode default for dev

Author: sharon77242

README.md

@@ -93,7 +93,7 @@ import { ArgusAgent } from 'argus-apm';
 const { ArgusAgent } = require('argus-apm');
 
 // ✅ CommonJS project — dynamic import also works
-const { ArgusAgent } = await import('argus');
+const { ArgusAgent } = await import('argus-apm');
 ```
 
 ---
@@ -160,7 +160,7 @@ import { ArgusAgent } from 'argus-apm';
 // import { ArgusAgent } from './packages/agent/src/index.ts';
 
 const agent = await ArgusAgent.createProfile({
-  environment: 'prod',   // or 'dev' | 'test'
+  environment: 'dev',    // 'dev' prints all events to console automatically; silence with 'prod' or ARGUS_DEBUG=false
   appType: ['web', 'db'],
 }).start();
 // SIGTERM / SIGINT → flush telemetry → process.exit is wired automatically
@@ -763,7 +763,7 @@ runWithContext(agent.createContext('WORKER', '/process-job'), async () => {
 });
 ```
 
-> **Source mode (contributors):** replace `'argus'` with `'./packages/agent/src/index.ts'` and run with `node --experimental-strip-types` on Node 22.6+.
+> **Source mode (contributors):** replace `'argus-apm'` with `'./packages/agent/src/index.ts'` and run with `node --experimental-strip-types` on Node 22.6+.
 
 ---
 

packages/agent/src/argus-agent.ts

@@ -152,6 +152,8 @@ export class ArgusAgent extends EventEmitter {
   private running = false;
   // Listeners added by useConsoleLogger — kept so they can be removed on stop().
   private debugListeners: DebugListener[] = [];
+  /** Set by buildAgentProfile when environment === 'dev'. */
+  isDevMode = false;
 
   // Private constructor — use ArgusAgent.create()
   private constructor() {
@@ -471,7 +473,11 @@ export class ArgusAgent extends EventEmitter {
   public async start(): Promise<this> {
     if (this.globallyDisabled || this.running) return this;
 
-    if (process.env.ARGUS_DEBUG === "true") {
+    const debugEnv = process.env.ARGUS_DEBUG;
+    const debugEnabled = debugEnv !== undefined
+      ? debugEnv !== "false" && debugEnv !== "0"
+      : this.isDevMode;
+    if (debugEnabled) {
       this.useConsoleLogger();
     }
 
@@ -840,7 +846,7 @@ export class ArgusAgent extends EventEmitter {
    * @param level   `'warn'` — anomalies/crashes/errors only (default)
    *                `'verbose'` — also logs every query and HTTP request
    */
-  private useConsoleLogger(prefix = "[DiagAgent]", level: "warn" | "verbose" = "verbose"): this {
+  private useConsoleLogger(prefix = "[Argus]", level: "warn" | "verbose" = "verbose"): this {
     const registered = installConsoleLogger(this, prefix, level);
     this.debugListeners.push(...registered);
     return this;

packages/agent/src/internal/profile-factory.ts

@@ -20,6 +20,7 @@ import { detectAppTypes } from "../profiling/app-type-detector.ts";
  */
 export function buildAgentProfile(agent: ArgusAgent, config: AgentProfileConfig): void {
   const env = config.environment ?? "prod";
+  agent.isDevMode = env === "dev";
 
   // Resolve app types — 'auto' triggers package.json scanning
   let appTypes: AppType[];

packages/agent/src/profiling/runtime-monitor.ts

@@ -212,7 +212,6 @@ export class RuntimeMonitor extends EventEmitter {
     const now = Date.now();
 
     if (now - this.lastCpuProfileTime < this.options.cpuProfileCooldownMs!) {
-      // Fallback to simple emission if in cooldown
       this.emit("anomaly", {
         type: "event-loop-lag",
         lagMs,
@@ -225,28 +224,31 @@ export class RuntimeMonitor extends EventEmitter {
     this.isProfiling = true;
     this.lastCpuProfileTime = now;
 
+    let profileDataPath: string | undefined;
     try {
       if (!this.inspectorSession) {
         this.inspectorSession = new Session();
         this.inspectorSession.connect();
       }
 
       const profileData = await this.captureCpuProfile();
-      if (!profileData) return; // Session detached or failed
-      const tempPath = join(tmpdir(), `cpu-profile-${Date.now()}.cpuprofile`);
-      await writeFile(tempPath, JSON.stringify(profileData), "utf-8");
-
-      this.emit("anomaly", {
-        type: "event-loop-lag",
-        lagMs,
-        profileDataPath: tempPath,
-        timestamp: Date.now(),
-      } satisfies ProfilerEvent);
+      if (profileData) {
+        const tempPath = join(tmpdir(), `cpu-profile-${Date.now()}.cpuprofile`);
+        await writeFile(tempPath, JSON.stringify(profileData), "utf-8");
+        profileDataPath = tempPath;
+      }
     } catch (err) {
       this.emit("error", err);
     } finally {
       this.isProfiling = false;
     }
+
+    this.emit("anomaly", {
+      type: "event-loop-lag",
+      lagMs,
+      profileDataPath,
+      timestamp: Date.now(),
+    } satisfies ProfilerEvent);
   }
 
   /** Test helper — directly fire the heap-oom-risk logic without waiting for a real threshold. */

packages/agent/tests/profiling/runtime-monitor.test.ts

@@ -61,33 +61,41 @@ describe("RuntimeMonitor", () => {
   });
 
   it("should detect event loop lag and capture CPU profile", async () => {
-    monitor.start();
+    // Use a dedicated monitor with a very low threshold (5ms) and fast check interval
+    // so detection is reliable regardless of host load or timer resolution.
+    const lagMonitor = new RuntimeMonitor({
+      checkIntervalMs: 50,
+      eventLoopThresholdMs: 5,
+      cpuProfileDurationMs: 50,
+      cpuProfileCooldownMs: 1000,
+    });
+    lagMonitor.start();
 
     const p = new Promise<ProfilerEvent[]>((resolve) => {
       const handler = (event: ProfilerEvent) => {
         if (event.type === "event-loop-lag") {
-          monitor.off("anomaly", handler);
+          lagMonitor.off("anomaly", handler);
           resolve([event]);
         }
       };
-      monitor.on("anomaly", handler);
+      lagMonitor.on("anomaly", handler);
     });
 
     await sleep(10); // allow baseline to settle
 
-    // Create an artificial event loop block synchronously
+    // Block the event loop long enough to guarantee detection on any machine.
     const start = Date.now();
-    while (Date.now() - start < 150) {
+    while (Date.now() - start < 300) {
       // busy wait
     }
 
     const timeoutPromise = new Promise<never>((_, reject) =>
-      setTimeout(() => reject(new Error("Timeout waiting for lag event")), 1000),
+      setTimeout(() => reject(new Error("Timeout waiting for lag event")), 3000),
     );
     const [event] = await Promise.race([p, timeoutPromise]);
 
     assert.strictEqual(event.type, "event-loop-lag");
-    assert.ok(event.lagMs! >= 20);
+    assert.ok(event.lagMs! >= 5);
     // profileDataPath may be undefined if the inspector session didn't start in time (test-runner load).
     // When it is present it must be a string path.
     if (event.profileDataPath !== undefined) {
@@ -97,5 +105,7 @@ describe("RuntimeMonitor", () => {
         "profileDataPath should be a valid string path",
       );
     }
+
+    lagMonitor.stop();
   });
 });

quotes-demo-app/bin/www

@@ -4,7 +4,7 @@
  * Module dependencies.
  */
 
-// ⚡ DiagnosticAgent — must be first, before Express loads
+// ⚡ ArgusAgent — must be first, before Express loads
 require('../diagnostic');
 
 var app = require('../app');

quotes-demo-app/diagnostic.js

@@ -1,7 +1,7 @@
 'use strict';
 
 const path = require('path');
-const { DiagnosticAgent } = require(path.resolve(__dirname, '../packages/agent/dist/cjs/index.cjs'));
+const { ArgusAgent } = require(path.resolve(__dirname, '../packages/agent/dist/cjs/index.cjs'));
 
 // ── colour helpers (no deps) ──────────────────────────────────────────────────
 const c = {
@@ -12,7 +12,7 @@ const c = {
 const stamp = () => new Date().toISOString().slice(11, 23); // HH:MM:SS.mmm
 const tag = (colour, label) => `${colour}${c.bold}[${label}]${c.reset}`;
 
-const agent = DiagnosticAgent.createProfile({
+const agent = ArgusAgent.createProfile({
   environment: process.env.NODE_ENV === 'production' ? 'prod' : 'dev',
   appType: ['web', 'db'],
   workspaceDir: path.resolve(__dirname, '..'),

quotes-demo-app/routes/debug.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * Debug routes — intentionally trigger every DiagnosticAgent monitoring feature.
+ * Debug routes — intentionally trigger every ArgusAgent monitoring feature.
  * Never use patterns like these in production code.
  */
 

quotes-demo-app/services/db.js

@@ -9,14 +9,14 @@ const dbChannel = diagnostics_channel.channel('db.query.execution');
 
 /**
  * Query the database using the pool.
- * Also publishes to diagnostics_channel so the DiagnosticAgent can trace it.
+ * Also publishes to diagnostics_channel so the ArgusAgent can trace it.
  */
 async function query(sql, params) {
     const start = performance.now();
     const {rows} = await pool.query(sql, params);
     const durationMs = performance.now() - start;
 
-    // Broadcast to DiagnosticAgent
+    // Broadcast to ArgusAgent
     if (dbChannel.hasSubscribers) {
         dbChannel.publish({ query: sql, durationMs });
     }

quotes-demo-app/simulate.js

@@ -8,7 +8,7 @@
 
 const http = require('http');
 
-// ── 1. Boot DiagnosticAgent (must be first) ───────────────────────────────────
+// ── 1. Boot ArgusAgent (must be first) ───────────────────────────────────────
 const agent = require('./diagnostic');
 
 // ── 2. Boot Express app ───────────────────────────────────────────────────────