0
# Monitoring and Information
1

2
Comprehensive monitoring, process information retrieval, and performance analysis capabilities for PM2-managed applications. Includes real-time metrics collection, log management, process communication, and debugging tools.
3

4
## Capabilities
5

6
### Process Information
7

8
Retrieve detailed information about managed processes and their current state.
9

10
```javascript { .api }
11
/**
12
 * Get list of all managed processes
13
 * @param callback - Called with error and array of process descriptions
14
 */
15
function list(callback: (err: Error, processes: ProcessDescription[]) => void): void;
16

17
/**
18
 * Get detailed information about specific process
19
 * @param process - Process name or ID
20
 * @param callback - Called with error and process description array
21
 */
22
function describe(process: string | number, callback: (err: Error, description: ProcessDescription[]) => void): void;
23

24
/**
25
 * Get process PIDs
26
 * @param app_name - Process name (optional, returns all PIDs if not provided)
27
 * @param callback - Called with PID information
28
 */
29
function getPID(app_name?: string, callback?: (err: Error, proc: Proc) => void): void;
30
```
31

32
**Usage Examples:**
33

34
```javascript
35
// List all processes
36
pm2.list((err, processes) => {
37
  if (err) throw err;
38
  processes.forEach(proc => {
39
    console.log(`${proc.name}: ${proc.pm2_env.status} (PID: ${proc.pid})`);
40
    console.log(`  Memory: ${proc.monit.memory} bytes`);
41
    console.log(`  CPU: ${proc.monit.cpu}%`);
42
  });
43
});
44

45
// Describe specific process
46
pm2.describe('my-app', (err, description) => {
47
  if (err) throw err;
48
  const proc = description[0];
49
  console.log('Process Details:');
50
  console.log(`  Name: ${proc.name}`);
51
  console.log(`  Status: ${proc.pm2_env.status}`);
52
  console.log(`  Uptime: ${proc.pm2_env.pm_uptime}`);
53
  console.log(`  Restarts: ${proc.pm2_env.restart_time}`);
54
  console.log(`  Script: ${proc.pm2_env.pm_exec_path}`);
55
});
56

57
// Get PIDs for all processes
58
pm2.getPID((err, proc) => {
59
  if (err) throw err;
60
  console.log('Process PIDs:', proc);
61
});
62
```
63

64
### System Monitoring
65

66
Launch and manage system-level monitoring for resource usage tracking.
67

68
```javascript { .api }
69
/**
70
 * Launch system monitoring for CPU and memory usage
71
 * @param callback - Called when monitoring is launched
72
 */
73
function launchSysMonitoring(callback?: (err: Error) => void): void;
74

75
/**
76
 * Launch message bus for process events
77
 * @param callback - Called with error and bus object for event listening
78
 */
79
function launchBus(callback: (err: Error, bus: any) => void): void;
80
```
81

82
**Usage Examples:**
83

84
```javascript
85
// Launch system monitoring
86
pm2.launchSysMonitoring((err) => {
87
  if (err) throw err;
88
  console.log('System monitoring started');
89
});
90

91
// Launch event bus
92
pm2.launchBus((err, bus) => {
93
  if (err) throw err;
94
  
95
  // Listen to process events
96
  bus.on('process:msg', (packet) => {
97
    console.log('Process message:', packet);
98
  });
99
  
100
  bus.on('process:exception', (packet) => {
101
    console.log('Process exception:', packet);
102
  });
103
});
104
```
105

106
### Performance Profiling
107

108
CPU and memory profiling capabilities for performance analysis.
109

110
```javascript { .api }
111
/**
112
 * Profile CPU or memory usage
113
 * @param type - 'cpu' for CPU profiling, 'mem' for memory profiling
114
 * @param time - Duration in seconds (default: 10)
115
 * @param callback - Called when profiling is complete
116
 */
117
function profile(type: 'cpu' | 'mem', time?: number, callback?: (err: Error) => void): void;
118
```
119

120
**Usage Examples:**
121

122
```javascript
123
// CPU profiling for 30 seconds
124
pm2.profile('cpu', 30, (err) => {
125
  if (err) throw err;
126
  console.log('CPU profiling completed, check PM2 logs for results');
127
});
128

129
// Memory profiling with default duration
130
pm2.profile('mem', (err) => {
131
  if (err) throw err;
132
  console.log('Memory profiling completed');
133
});
134
```
135

136
### Process Communication
137

138
Send data and communicate with managed processes.
139

140
```javascript { .api }
141
/**
142
 * Send data to specific process
143
 * @param proc_id - Process ID
144
 * @param packet - Data object to send
145
 * @param callback - Called when data is sent
146
 */
147
function sendDataToProcessId(proc_id: number, packet: object, callback: (err: Error, result: any) => void): void;
148

149
/**
150
 * Send data using packet format
151
 * @param packet - Formatted packet with id, type, topic, and data
152
 */
153
function sendDataToProcessId(packet: {id: number, type: 'process:msg', topic: true, data: object}): void;
154

155
/**
156
 * Send line to process stdin
157
 * @param pm_id - Process ID or name
158
 * @param line - Line to send
159
 * @param separator - Line separator (default: '\n')
160
 * @param callback - Called when line is sent
161
 */
162
function sendLineToStdin(pm_id: string | number, line: string, separator?: string, callback?: (err: Error) => void): void;
163

164
/**
165
 * Trigger custom action on process
166
 * @param pm_id - Process ID or name
167
 * @param action_name - Name of action to trigger
168
 * @param params - Parameters to pass to action
169
 * @param callback - Called when action completes
170
 */
171
function trigger(pm_id: string | number, action_name: string, params?: any, callback?: (err: Error) => void): void;
172
```
173

174
**Usage Examples:**
175

176
```javascript
177
// Send data to process
178
pm2.sendDataToProcessId(0, { message: 'Hello from PM2' }, (err, result) => {
179
  if (err) throw err;
180
  console.log('Data sent to process');
181
});
182

183
// Send formatted packet
184
pm2.sendDataToProcessId({
185
  id: 0,
186
  type: 'process:msg',
187
  topic: true,
188
  data: { command: 'refresh', config: { timeout: 5000 } }
189
});
190

191
// Send line to stdin
192
pm2.sendLineToStdin(0, 'reload-config', '\n', (err) => {
193
  if (err) throw err;
194
  console.log('Command sent to process stdin');
195
});
196

197
// Trigger custom action
198
pm2.trigger('my-app', 'graceful-shutdown', { timeout: 30000 }, (err) => {
199
  if (err) throw err;
200
  console.log('Graceful shutdown triggered');
201
});
202
```
203

204
### Signal Management
205

206
Send system signals to managed processes.
207

208
```javascript { .api }
209
/**
210
 * Send signal to process by name
211
 * @param signal - Signal to send (e.g., 'SIGUSR1', 'SIGTERM')
212
 * @param process - Process name or ID
213
 * @param callback - Called when signal is sent
214
 */
215
function sendSignalToProcessName(signal: string | number, process: number | string, callback: (err: Error, result: any) => void): void;
216

217
/**
218
 * Send signal to process by ID directly
219
 * @param signal - Signal to send (e.g., 'SIGUSR1', 'SIGTERM')
220
 * @param process_id - Process ID
221
 * @param callback - Called when signal is sent
222
 */
223
function sendSignalToProcessId(signal: string | number, process_id: number, callback: (err: Error, result: any) => void): void;
224
```
225

226
**Usage Examples:**
227

228
```javascript
229
// Send SIGUSR1 signal
230
pm2.sendSignalToProcessName('SIGUSR1', 'my-app', (err, result) => {
231
  if (err) throw err;
232
  console.log('Signal sent to process');
233
});
234

235
// Send SIGTERM to process ID
236
pm2.sendSignalToProcessName('SIGTERM', 0, (err, result) => {
237
  if (err) throw err;
238
  console.log('SIGTERM sent to process 0');
239
});
240
```
241

242
### Log Management
243

244
Manage and access process logs.
245

246
```javascript { .api }
247
/**
248
 * Flush process logs
249
 * @param process - Process name, ID, or "all"
250
 * @param callback - Called when logs are flushed
251
 */
252
function flush(process: number | string, callback: (err: Error, result: any) => void): void;
253

254
/**
255
 * Rotate log files
256
 * @param callback - Called when log rotation is complete
257
 */
258
function reloadLogs(callback: (err: Error, result: any) => void): void;
259

260
/**
261
 * Attach to process logs
262
 * @param pm_id - Process ID or name
263
 * @param separator - Log line separator
264
 * @param callback - Called when attached
265
 */
266
function attach(pm_id: string | number, separator?: string, callback?: (err: Error) => void): void;
267
```
268

269
**Usage Examples:**
270

271
```javascript
272
// Flush all logs
273
pm2.flush('all', (err, result) => {
274
  if (err) throw err;
275
  console.log('All logs flushed');
276
});
277

278
// Rotate log files
279
pm2.reloadLogs((err, result) => {
280
  if (err) throw err;
281
  console.log('Log files rotated');
282
});
283

284
// Attach to process logs
285
pm2.attach(0, '\n', (err) => {
286
  if (err) throw err;
287
  console.log('Attached to process 0 logs');
288
});
289
```
290

291
### System Information
292

293
Get PM2 system information and health status.
294

295
```javascript { .api }
296
/**
297
 * Get PM2 daemon version
298
 * @param callback - Called with version information
299
 */
300
function getVersion(callback: (err: Error) => void): void;
301

302
/**
303
 * Generate comprehensive system report
304
 * @returns System report with all process and system information
305
 */
306
function report(): void;
307

308
/**
309
 * Ping PM2 daemon to check connectivity
310
 * @param callback - Called with ping result
311
 */
312
function ping(callback: (err: Error) => void): void;
313
```
314

315
**Usage Examples:**
316

317
```javascript
318
// Get PM2 version
319
pm2.getVersion((err) => {
320
  if (err) throw err;
321
  console.log('PM2 version retrieved');
322
});
323

324
// Generate system report
325
pm2.report(); // Outputs comprehensive system information
326

327
// Ping daemon
328
pm2.ping((err) => {
329
  if (err) throw err;
330
  console.log('PM2 daemon is responsive');
331
});
332
```
333

334
### Environment and Debugging
335

336
Access process environment and debugging capabilities.
337

338
```javascript { .api }
339
/**
340
 * Get process environment variables
341
 * @param app_id - Process name or ID
342
 * @param callback - Called with environment variables
343
 */
344
function env(app_id: string | number, callback?: (err: Error) => void): void;
345

346
/**
347
 * Inspect process for debugging
348
 * @param app_name - Process name
349
 * @param callback - Called with inspect information
350
 */
351
function inspect(app_name: string, callback?: (err: Error) => void): void;
352
```
353

354
**Usage Examples:**
355

356
```javascript
357
// Get process environment
358
pm2.env('my-app', (err) => {
359
  if (err) throw err;
360
  console.log('Environment variables retrieved');
361
});
362

363
// Inspect process for debugging
364
pm2.inspect('my-app', (err) => {
365
  if (err) throw err;
366
  console.log('Process inspection started');
367
});
368
```
369

370
## Core Types
371

372
```javascript { .api }
373
interface ProcessDescription {
374
  /** Process name */
375
  name?: string;
376
  /** System process ID */
377
  pid?: number;
378
  /** PM2 internal process ID */
379
  pm_id?: number;
380
  /** Real-time monitoring data */
381
  monit?: {
382
    /** Memory usage in bytes */
383
    memory?: number;
384
    /** CPU usage percentage */
385
    cpu?: number;
386
  };
387
  /** PM2 environment data */
388
  pm2_env?: {
389
    /** Working directory */
390
    pm_cwd?: string;
391
    /** Stdout log file path */
392
    pm_out_log_path?: string;
393
    /** Stderr log file path */
394
    pm_err_log_path?: string;
395
    /** Script interpreter */
396
    exec_interpreter?: string;
397
    /** Process uptime in milliseconds */
398
    pm_uptime?: number;
399
    /** Number of unstable restarts */
400
    unstable_restarts?: number;
401
    /** Last restart timestamp */
402
    restart_time?: number;
403
    /** Current process status */
404
    status?: ProcessStatus;
405
    /** Number of instances */
406
    instances?: number | 'max';
407
    /** Executable script path */
408
    pm_exec_path?: string;
409
  };
410
}
411

412
interface Monit {
413
  /** Memory usage in bytes */
414
  memory?: number;
415
  /** CPU usage percentage */
416
  cpu?: number;
417
}
418

419
interface Pm2Env {
420
  /** Working directory */
421
  pm_cwd?: string;
422
  /** Stdout log file path */
423
  pm_out_log_path?: string;
424
  /** Stderr log file path */
425
  pm_err_log_path?: string;
426
  /** Script interpreter */
427
  exec_interpreter?: string;
428
  /** Process uptime in milliseconds */
429
  pm_uptime?: number;
430
  /** Number of unstable restarts */
431
  unstable_restarts?: number;
432
  /** Last restart timestamp */
433
  restart_time?: number;
434
  /** Current process status */
435
  status?: ProcessStatus;
436
  /** Number of instances */
437
  instances?: number | 'max';
438
  /** Executable script path */
439
  pm_exec_path?: string;
440
}
441

442
type ProcessStatus = 'online' | 'stopping' | 'stopped' | 'launching' | 'errored' | 'one-launch-status' | 'waiting_restart';
443
```