@bitcall/pm2-pulse-agent 1.0.1-beta.0 → 1.0.1-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +123 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1 +1,123 @@
|
|
|
1
|
-
#
|
|
1
|
+
# PM2 Pulse Agent
|
|
2
|
+
|
|
3
|
+
A Node.js monitoring agent that tracks server metrics (CPU, RAM, processes) and sends real-time alerts to a gRPC monitoring service.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **Real-time Metrics Collection**: Monitors CPU usage, RAM consumption, and PM2 process states
|
|
8
|
+
- **Configurable Thresholds**: Set custom CPU and RAM alert thresholds
|
|
9
|
+
- **PM2 Integration**: Tracks all PM2-managed processes and their status
|
|
10
|
+
- **gRPC Communication**: Sends metrics to a monitoring server via gRPC
|
|
11
|
+
- **Authentication Support**: Optional Bearer token authentication
|
|
12
|
+
- **Singleton Pattern**: Ensures only one agent instance runs per server
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npm install
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
### Dependencies
|
|
21
|
+
|
|
22
|
+
- `@grpc/grpc-js` - gRPC protocol implementation
|
|
23
|
+
- `@grpc/proto-loader` - Protocol buffer loader
|
|
24
|
+
- `dotenv` - Environment variable management
|
|
25
|
+
|
|
26
|
+
## Setup
|
|
27
|
+
|
|
28
|
+
Run the interactive setup script to configure the agent:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npm run setup-agent
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
This will prompt you to configure:
|
|
35
|
+
- **AUTH_TOKEN**: Secret token for server authentication (optional)
|
|
36
|
+
- **MONITOR_SERVER**: gRPC server address (default: `localhost:50051`)
|
|
37
|
+
- **VPS_ID**: Unique identifier for this server (default: `server-{hostname}`)
|
|
38
|
+
|
|
39
|
+
Settings are saved to `.env` file.
|
|
40
|
+
|
|
41
|
+
## Usage
|
|
42
|
+
|
|
43
|
+
### Start the Agent
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
npm run agent
|
|
47
|
+
# or
|
|
48
|
+
npm run monitor
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
### Configuration Options
|
|
52
|
+
|
|
53
|
+
Environment variables in `.env`:
|
|
54
|
+
|
|
55
|
+
| Variable | Default | Description |
|
|
56
|
+
|----------|---------|-------------|
|
|
57
|
+
| `MONITOR_SERVER` | `localhost:50051` | gRPC server host:port |
|
|
58
|
+
| `VPS_ID` | `server-{hostname}` | Unique server identifier |
|
|
59
|
+
| `AUTH_TOKEN` | `` | Bearer token for authentication |
|
|
60
|
+
| `CPU_THRESHOLD` | `70` | CPU alert threshold (%) |
|
|
61
|
+
| `RAM_THRESHOLD` | `80` | RAM alert threshold (%) |
|
|
62
|
+
|
|
63
|
+
## How It Works
|
|
64
|
+
|
|
65
|
+
1. **Agent Startup**: Initializes gRPC client and logs configuration
|
|
66
|
+
2. **Metrics Collection**: Every 10 seconds, collects:
|
|
67
|
+
- CPU usage (2-second measurement window)
|
|
68
|
+
- RAM usage and statistics
|
|
69
|
+
- PM2 process information (name, status, restarts, CPU, memory)
|
|
70
|
+
3. **Alert Detection**: Triggers alerts when:
|
|
71
|
+
- CPU exceeds threshold
|
|
72
|
+
- RAM exceeds threshold
|
|
73
|
+
- Any process is not in "online" status
|
|
74
|
+
4. **Data Transmission**: Sends metrics to gRPC server with optional authentication
|
|
75
|
+
5. **Logging**: Displays metrics and alerts in console
|
|
76
|
+
|
|
77
|
+
## Metrics Structure
|
|
78
|
+
|
|
79
|
+
```javascript
|
|
80
|
+
{
|
|
81
|
+
vps_id: string, // Server identifier
|
|
82
|
+
cpu: number, // CPU usage percentage (0-100)
|
|
83
|
+
ram: number, // RAM usage percentage (0-100)
|
|
84
|
+
ram_used_mb: number, // Used RAM in MB
|
|
85
|
+
ram_total_mb: number, // Total RAM in MB
|
|
86
|
+
processes: [ // PM2 processes
|
|
87
|
+
{
|
|
88
|
+
name: string,
|
|
89
|
+
status: string, // 'online', 'stopped', etc.
|
|
90
|
+
restarts: number,
|
|
91
|
+
cpu_percent: number,
|
|
92
|
+
memory_mb: number
|
|
93
|
+
}
|
|
94
|
+
],
|
|
95
|
+
alerts: string[], // Alert messages
|
|
96
|
+
urgent: boolean, // Whether message contains alerts
|
|
97
|
+
timestamp: number // Unix timestamp
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Example Output
|
|
102
|
+
|
|
103
|
+
```
|
|
104
|
+
============================================================
|
|
105
|
+
🚀 PM2 Monitoring Agent Started
|
|
106
|
+
============================================================
|
|
107
|
+
VPS ID: server-app-01
|
|
108
|
+
Server: monitoring-server.example.com:50051
|
|
109
|
+
Authentication: ✓ Enabled
|
|
110
|
+
Check interval: 10 second(s)
|
|
111
|
+
CPU Threshold: 70%
|
|
112
|
+
RAM Threshold: 80%
|
|
113
|
+
============================================================
|
|
114
|
+
|
|
115
|
+
[14:23:45] CPU: 45% | RAM: 2048/8192MB (25%) | Alerts: 0
|
|
116
|
+
[14:23:55] CPU: 62% | RAM: 3512/8192MB (43%) | Alerts: 0
|
|
117
|
+
[14:24:05] CPU: 85% | RAM: 6144/8192MB (75%) | Alerts: 1 🚨
|
|
118
|
+
✓ Alert sent to server
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## License
|
|
122
|
+
|
|
123
|
+
MIT
|