feat: log cluster module IPC via onelogger

Add structured logging on every master<->app worker IPC point in Node.js
cluster mode (process mode only). Covers both application-layer messages
and the internal NODE_CLUSTER fd dispatch / fd ack.

Application layer (always on):
- master->app send (AppProcessWorker#send)
- master->app sticky-session Socket direct send (master.ts)
- master<-app recv (cluster.on 'fork' -> worker.on 'message')
- app->master send (static AppProcessWorker.send)
- app<-master recv (process.on 'message' in app_worker.ts)

Internal cluster layer (opt-in via EGG_CLUSTER_IPC_LOG=1, very verbose):
- master<-app internal (worker.process.on 'internalMessage'):
  online / listening / queryServer / accepted (fd ack) / close
- app<-master internal (process.on 'internalMessage'):
  newconn (fd dispatch, with handle) / disconnect / suicide

Users can replace the default console sink via onelogger.setLogger().

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: killagu

package.json

@@ -43,7 +43,8 @@
     "graceful-process": "^2.0.0",
     "sendmessage": "^3.0.1",
     "terminal-link": "^2.1.1",
-    "utility": "^2.2.0"
+    "utility": "^2.2.0",
+    "onelogger": "^1.0.1"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.17.1",

src/app_worker.ts

@@ -8,6 +8,7 @@ import { importModule } from '@eggjs/utils';
 import { BaseAppWorker } from './utils/mode/base/app.js';
 import { AppThreadWorker } from './utils/mode/impl/worker_threads/app.js';
 import { AppProcessWorker } from './utils/mode/impl/process/app.js';
+import { ipcLogger, formatIpcMessage, internalIpcLogEnabled } from './utils/ipc_logger.js';
 
 const debug = debuglog('@eggjs/cluster/app_worker');
 
@@ -38,6 +39,29 @@ async function main() {
     AppWorker = AppThreadWorker as any;
   } else {
     AppWorker = AppProcessWorker as any;
+    // D. master -> app (recv): log every IPC message delivered to this worker via the cluster channel.
+    // Handle is present when master forwards a `net.Socket` (sticky-session mode).
+    // This listener is read-only; other `process.on('message')` listeners (framework, sticky handler,
+    // etc.) are unaffected.
+    process.on('message', (msg: any, handle: any) => {
+      const body = typeof msg === 'string' ? { action: msg } : msg;
+      ipcLogger.info(formatIpcMessage(`app#${process.pid}<-master`, body, handle));
+    });
+
+    // F. master -> app internal NODE_CLUSTER messages (newconn with fd, disconnect, suicide, ...).
+    // `internalMessage` is an undocumented but stable Node.js event.
+    // Opt-in via EGG_CLUSTER_IPC_LOG because `newconn` fires once per HTTP request.
+    if (internalIpcLogEnabled) {
+      process.on('internalMessage', (msg: { cmd?: string; act?: string; ack?: number }, handle: unknown) => {
+        if (!msg || msg.cmd !== 'NODE_CLUSTER') return;
+        const label = msg.act ? `cluster:${msg.act}` : `cluster:ack#${msg.ack ?? '?'}`;
+        ipcLogger.info(formatIpcMessage(
+          `app#${process.pid}<-master`,
+          { action: label, data: msg },
+          handle,
+        ));
+      });
+    }
   }
 
   const consoleLogger = new ConsoleLogger({

src/master.ts

@@ -23,6 +23,7 @@ import {
 } from './utils/mode/impl/worker_threads/agent.js';
 import { AppThreadWorker, AppThreadUtils as WorkerThreadsAppWorker } from './utils/mode/impl/worker_threads/app.js';
 import { ClusterWorkerExceptionError } from './error/ClusterWorkerExceptionError.js';
+import { ipcLogger, formatIpcMessage } from './utils/ipc_logger.js';
 
 const debug = debuglog('@eggjs/cluster/master');
 
@@ -265,6 +266,11 @@ export class Master extends ReadyEventEmitter {
         connection.destroy();
       } else {
         const worker = this.stickyWorker(connection.remoteAddress) as AppProcessWorker;
+        ipcLogger.info(formatIpcMessage(
+          `master->app#${worker.workerId}`,
+          { action: 'sticky-session:connection' },
+          connection,
+        ));
         worker.instance.send('sticky-session:connection', connection);
       }
     }).listen(this.#realPort, cb);

src/utils/ipc_logger.ts

@@ -0,0 +1,84 @@
+import net from 'node:net';
+import { getLogger } from 'onelogger';
+import type { MessageBody } from './messenger.js';
+
+/**
+ * onelogger instance for Node.js cluster module IPC traffic between master and app workers.
+ * Users can override the underlying sink via `onelogger.setLogger()` / `setCustomLogger()`.
+ */
+export const ipcLogger = getLogger('@eggjs/cluster:ipc');
+
+/**
+ * Whether internal-level cluster IPC logs (NODE_CLUSTER newconn/accepted/listening/...) are enabled.
+ * These are very verbose (one `cluster:newconn` per HTTP request), so they are opt-in
+ * via the `EGG_CLUSTER_IPC_LOG` environment variable (any truthy value enables).
+ */
+export const internalIpcLogEnabled = !!process.env.EGG_CLUSTER_IPC_LOG;
+
+const MAX_STRING_LEN = 200;
+const MAX_TOTAL_LEN = 1024;
+
+function describeHandle(handle: unknown): string {
+  if (handle == null) return '';
+  if (handle instanceof net.Socket) {
+    const fd = (handle as unknown as { _handle?: { fd?: number } })._handle?.fd;
+    return fd != null ? `<Socket fd=${fd}>` : '<Socket>';
+  }
+  if (handle instanceof net.Server) {
+    return '<Server>';
+  }
+  const ctor = (handle as { constructor?: { name?: string } })?.constructor?.name;
+  return ctor ? `<${ctor}>` : '<handle>';
+}
+
+function makeReplacer() {
+  const seen = new WeakSet<object>();
+  return function replacer(_key: string, value: unknown) {
+    if (value && typeof value === 'object') {
+      if (seen.has(value as object)) return '<Circular>';
+      seen.add(value as object);
+      if (value instanceof net.Socket) return describeHandle(value);
+      if (value instanceof net.Server) return '<Server>';
+      if (Buffer.isBuffer(value)) return `<Buffer len=${value.length}>`;
+    }
+    if (typeof value === 'string' && value.length > MAX_STRING_LEN) {
+      return `${value.slice(0, MAX_STRING_LEN)}...(truncated)`;
+    }
+    return value;
+  };
+}
+
+function stringifyData(data: unknown): string {
+  let out: string;
+  try {
+    out = JSON.stringify(data, makeReplacer());
+  } catch (err) {
+    return `<unserializable: ${(err as Error).message}>`;
+  }
+  if (out && out.length > MAX_TOTAL_LEN) {
+    out = `${out.slice(0, MAX_TOTAL_LEN)}...(truncated)`;
+  }
+  return out;
+}
+
+/**
+ * Format a single IPC message into a one-line log string.
+ * @param direction e.g. 'master->app#12345' / 'app#12345<-master'
+ * @param msg       the message body (supports cluster internal msgs via `action: 'cluster:<act>'`)
+ * @param handle    optional handle (net.Socket / net.Server) attached to the IPC message
+ */
+export function formatIpcMessage(
+  direction: string,
+  msg: Partial<MessageBody> & { action?: string; data?: unknown },
+  handle?: unknown,
+): string {
+  const action = msg?.action ?? '<unknown>';
+  let out = `[${direction}] action=${action}`;
+  if (msg && msg.data !== undefined) {
+    out += ` data=${stringifyData(msg.data)}`;
+  }
+  if (handle) {
+    out += ` +handle=${describeHandle(handle)}`;
+  }
+  return out;
+}

src/utils/mode/impl/process/app.ts

@@ -5,6 +5,7 @@ import { graceful as gracefulExit, type Options as gracefulExitOptions } from 'g
 import { BaseAppWorker, BaseAppUtils } from '../../base/app.js';
 import { terminate } from '../../../terminate.js';
 import type { MessageBody } from '../../../messenger.js';
+import { ipcLogger, formatIpcMessage, internalIpcLogEnabled } from '../../../ipc_logger.js';
 
 export class AppProcessWorker extends BaseAppWorker<ClusterProcessWorker> {
   get id() {
@@ -24,6 +25,7 @@ export class AppProcessWorker extends BaseAppWorker<ClusterProcessWorker> {
   }
 
   send(message: MessageBody) {
+    ipcLogger.info(formatIpcMessage(`master->app#${this.workerId}`, message));
     sendmessage(this.instance, message);
   }
 
@@ -43,6 +45,7 @@ export class AppProcessWorker extends BaseAppWorker<ClusterProcessWorker> {
 
   static send(message: MessageBody) {
     message.senderWorkerId = String(process.pid);
+    ipcLogger.info(formatIpcMessage(`app#${process.pid}->master`, message));
     process.send!(message);
   }
 
@@ -78,16 +81,37 @@ export class AppProcessUtils extends BaseAppUtils {
       const appWorker = new AppProcessWorker(worker);
       this.emit('worker_forked', appWorker);
       appWorker.disableRefork = true;
-      worker.on('message', msg => {
+      worker.on('message', (msg, handle) => {
         if (typeof msg === 'string') {
           msg = {
             action: msg,
             data: msg,
           };
         }
         msg.from = 'app';
+        ipcLogger.info(formatIpcMessage(
+          `master<-app#${worker.process.pid}`,
+          msg,
+          handle,
+        ));
         this.messenger.send(msg);
       });
+
+      // cluster internal NODE_CLUSTER messages (listening / online / queryServer / accepted (fd ack) / close / ...)
+      // Must hook on `worker.process` (ChildProcess) — `cluster.Worker` doesn't forward `internalMessage`.
+      // Note: `internalMessage` is not a documented Node.js event but has been stable across major versions.
+      // Opt-in via EGG_CLUSTER_IPC_LOG because this is very verbose under load.
+      if (internalIpcLogEnabled) {
+        worker.process.on('internalMessage', (msg: { cmd?: string; act?: string; ack?: number }, handle: unknown) => {
+          if (!msg || msg.cmd !== 'NODE_CLUSTER') return;
+          const label = msg.act ? `cluster:${msg.act}` : `cluster:ack#${msg.ack ?? '?'}`;
+          ipcLogger.info(formatIpcMessage(
+            `master<-app#${worker.process.pid}`,
+            { action: label, data: msg },
+            handle,
+          ));
+        });
+      }
       this.log('[master] app_worker#%s:%s start, state: %s, current workers: %j',
         appWorker.id, appWorker.workerId, appWorker.state,
         Object.keys(cluster.workers!));