sentinel-mac 0.1.0__tar.gz
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.
- sentinel_mac-0.1.0/LICENSE +21 -0
- sentinel_mac-0.1.0/PKG-INFO +276 -0
- sentinel_mac-0.1.0/README.md +245 -0
- sentinel_mac-0.1.0/pyproject.toml +46 -0
- sentinel_mac-0.1.0/sentinel_mac/__init__.py +3 -0
- sentinel_mac-0.1.0/sentinel_mac/__main__.py +5 -0
- sentinel_mac-0.1.0/sentinel_mac/core.py +832 -0
- sentinel_mac-0.1.0/sentinel_mac.egg-info/PKG-INFO +276 -0
- sentinel_mac-0.1.0/sentinel_mac.egg-info/SOURCES.txt +12 -0
- sentinel_mac-0.1.0/sentinel_mac.egg-info/dependency_links.txt +1 -0
- sentinel_mac-0.1.0/sentinel_mac.egg-info/entry_points.txt +2 -0
- sentinel_mac-0.1.0/sentinel_mac.egg-info/requires.txt +3 -0
- sentinel_mac-0.1.0/sentinel_mac.egg-info/top_level.txt +1 -0
- sentinel_mac-0.1.0/setup.cfg +4 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 raunplaymore
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sentinel-mac
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: AI Session Guardian for macOS — monitors battery, thermal, memory, disk, and AI processes with smart phone alerts
|
|
5
|
+
Author: raunplaymore
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/raunplaymore/sentinel
|
|
8
|
+
Project-URL: Repository, https://github.com/raunplaymore/sentinel
|
|
9
|
+
Project-URL: Issues, https://github.com/raunplaymore/sentinel/issues
|
|
10
|
+
Keywords: macos,monitoring,ai,battery,thermal,sentinel,notification
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: MacOS X
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: MacOS
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Topic :: System :: Monitoring
|
|
23
|
+
Classifier: Topic :: Utilities
|
|
24
|
+
Requires-Python: >=3.8
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
License-File: LICENSE
|
|
27
|
+
Requires-Dist: psutil<7,>=5.9
|
|
28
|
+
Requires-Dist: pyyaml<7,>=6.0
|
|
29
|
+
Requires-Dist: requests<3,>=2.28
|
|
30
|
+
Dynamic: license-file
|
|
31
|
+
|
|
32
|
+
<p align="center">
|
|
33
|
+
<h1 align="center">Sentinel</h1>
|
|
34
|
+
<p align="center">
|
|
35
|
+
<strong>AI Session Guardian for macOS</strong>
|
|
36
|
+
</p>
|
|
37
|
+
<p align="center">
|
|
38
|
+
AI 에이전트가 장시간 돌아갈 때, 맥북의 배터리·발열·메모리·디스크·네트워크를 감시하고<br/>
|
|
39
|
+
핸드폰으로 스마트 알림을 보내주는 경량 모니터링 데몬
|
|
40
|
+
</p>
|
|
41
|
+
<p align="center">
|
|
42
|
+
<a href="https://pypi.org/project/sentinel-mac/"><img src="https://img.shields.io/pypi/v/sentinel-mac" alt="PyPI"></a>
|
|
43
|
+
<img src="https://img.shields.io/badge/platform-macOS-blue" alt="macOS">
|
|
44
|
+
<img src="https://img.shields.io/badge/python-3.8+-green" alt="Python 3.8+">
|
|
45
|
+
<img src="https://img.shields.io/badge/notifications-ntfy.sh-yellow" alt="ntfy.sh">
|
|
46
|
+
<img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT License">
|
|
47
|
+
</p>
|
|
48
|
+
</p>
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Why Sentinel?
|
|
53
|
+
|
|
54
|
+
Claude, GPT, Ollama 같은 AI 에이전트를 수시간 돌려놓고 자리를 비우는 상황, 익숙하시죠?
|
|
55
|
+
|
|
56
|
+
돌아와보면 이런 일이 벌어져 있습니다:
|
|
57
|
+
|
|
58
|
+
- 배터리 0%로 세션이 날아감
|
|
59
|
+
- CPU 과열로 쓰로틀링 걸려 작업이 멈춤
|
|
60
|
+
- 메모리 부족으로 프로세스가 kill됨
|
|
61
|
+
- 무한루프에 빠져 몇 시간째 전력만 소모 중
|
|
62
|
+
|
|
63
|
+
**Sentinel**은 이 문제를 해결합니다. 30초마다 시스템 상태를 체크하고, 위험 상황이 감지되면 핸드폰으로 즉시 알림을 보냅니다.
|
|
64
|
+
|
|
65
|
+
## Quick Start
|
|
66
|
+
|
|
67
|
+
### Option A: pip install (PyPI)
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
pip install sentinel-mac
|
|
71
|
+
sentinel --init-config # config 생성 + ntfy 토픽 자동 발급
|
|
72
|
+
sentinel --once # 시스템 상태 즉시 확인
|
|
73
|
+
sentinel # 데몬 시작
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
### Option B: git clone (macOS 자동 시작 포함)
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
git clone https://github.com/raunplaymore/sentinel.git
|
|
80
|
+
cd sentinel
|
|
81
|
+
bash install.sh # venv + 패키지 설치 + launchd 등록 (로그인 시 자동 시작)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
**핸드폰 설정**
|
|
85
|
+
|
|
86
|
+
1. [ntfy 앱](https://ntfy.sh) 설치 (iOS / Android)
|
|
87
|
+
2. 설치 시 출력된 토픽을 앱에서 구독
|
|
88
|
+
|
|
89
|
+
끝. 이제 알림이 자동으로 옵니다.
|
|
90
|
+
|
|
91
|
+
## What It Monitors
|
|
92
|
+
|
|
93
|
+
| 카테고리 | 감지 항목 | 알림 조건 |
|
|
94
|
+
|:--------:|----------|----------|
|
|
95
|
+
| **Battery** | 잔량, 충전 상태, 소모 속도 (%/h) | 20% 이하, 급속 방전 감지 |
|
|
96
|
+
| **Thermal** | CPU 온도, thermal throttling | 85°C 이상, 쓰로틀링 |
|
|
97
|
+
| **Memory** | 사용률, AI 프로세스 점유량 | 90% 이상 |
|
|
98
|
+
| **Disk** | 디스크 사용률, 잔여 공간 | 90% 이상 |
|
|
99
|
+
| **AI Session** | 프로세스 식별, 실행 시간 | 3시간+, 무한루프 의심 |
|
|
100
|
+
| **Network** | 전송량 추적 | 간격당 100MB 초과 |
|
|
101
|
+
| **Night Watch** | 새벽 방치 + 배터리 사용 | 0시~6시 미충전 세션 |
|
|
102
|
+
|
|
103
|
+
## Smart Alerts
|
|
104
|
+
|
|
105
|
+
단순 임계치가 아닌, **상황을 조합한** 알림을 보냅니다:
|
|
106
|
+
|
|
107
|
+
```
|
|
108
|
+
🔴 Critical 배터리 10% + 충전기 미연결 + AI 세션 활성
|
|
109
|
+
→ 긴급 알림 (소리 + 진동)
|
|
110
|
+
|
|
111
|
+
🟠 Warning AI 프로세스 CPU 높은데 네트워크 I/O 없음
|
|
112
|
+
→ 무한루프 의심 알림
|
|
113
|
+
|
|
114
|
+
🟡 Night Watch 새벽 3시 + AI 세션 + 배터리 방전 중
|
|
115
|
+
→ 야간 방치 감지
|
|
116
|
+
|
|
117
|
+
📊 Status 매시간 자동 상태 리포트
|
|
118
|
+
→ CPU, 메모리, 배터리, 디스크 요약
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
알림은 카테고리별 쿨다운이 적용되어 스팸 없이 정확한 타이밍에 도착합니다. Critical 알림은 쿨다운이 1/3로 짧아져 긴급 상황에서 빠르게 반복됩니다.
|
|
122
|
+
|
|
123
|
+
## AI Process Detection
|
|
124
|
+
|
|
125
|
+
Sentinel은 3단계 전략으로 AI 프로세스를 식별합니다:
|
|
126
|
+
|
|
127
|
+
| Tier | 방식 | 예시 |
|
|
128
|
+
|:----:|------|------|
|
|
129
|
+
| **1** | 확실한 AI 프로세스 이름 | `ollama`, `llamaserver`, `mlx_lm` |
|
|
130
|
+
| **2** | 일반 프로세스 + 커맨드라인 키워드 | `python3` + `transformers` |
|
|
131
|
+
| **3** | 커맨드라인 키워드만 | `*` + `langchain`, `torch` |
|
|
132
|
+
|
|
133
|
+
일반적인 `node`, `python3` 프로세스가 AI로 오탐되는 것을 방지합니다.
|
|
134
|
+
|
|
135
|
+
## Commands
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
# 현재 상태 즉시 확인
|
|
139
|
+
sentinel --once
|
|
140
|
+
|
|
141
|
+
# 출력 예시:
|
|
142
|
+
# ==================================================
|
|
143
|
+
# Sentinel — System Snapshot
|
|
144
|
+
# 2025-01-15 14:32:10
|
|
145
|
+
# ==================================================
|
|
146
|
+
# CPU: 23.4%
|
|
147
|
+
# Thermal: nominal
|
|
148
|
+
# Memory: 67.2% (10.8GB)
|
|
149
|
+
# Battery: 85.3% (충전중 🔌)
|
|
150
|
+
# Disk: 45.2% (잔여 234.5GB)
|
|
151
|
+
# Network: ↑0.12MB ↓1.45MB
|
|
152
|
+
#
|
|
153
|
+
# AI Processes (2):
|
|
154
|
+
# ollama CPU: 45.2% MEM:3200MB
|
|
155
|
+
# python3 CPU: 12.1% MEM: 890MB
|
|
156
|
+
# ==================================================
|
|
157
|
+
|
|
158
|
+
# 알림 테스트 (핸드폰으로 테스트 알림 발송)
|
|
159
|
+
sentinel --test-notify
|
|
160
|
+
|
|
161
|
+
# 버전 확인
|
|
162
|
+
sentinel --version
|
|
163
|
+
|
|
164
|
+
# 로그 실시간 확인
|
|
165
|
+
tail -f logs/sentinel.log
|
|
166
|
+
|
|
167
|
+
# 서비스 관리
|
|
168
|
+
launchctl unload ~/Library/LaunchAgents/com.sentinel.agent.plist # 중지
|
|
169
|
+
launchctl load ~/Library/LaunchAgents/com.sentinel.agent.plist # 시작
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Configuration
|
|
173
|
+
|
|
174
|
+
`config.yaml` 에서 모든 설정을 조정할 수 있습니다:
|
|
175
|
+
|
|
176
|
+
```yaml
|
|
177
|
+
# 모니터링
|
|
178
|
+
check_interval_seconds: 30 # 체크 간격 (초)
|
|
179
|
+
status_interval_minutes: 60 # 상태 리포트 주기 (분)
|
|
180
|
+
cooldown_minutes: 10 # 같은 알림 반복 방지 (분)
|
|
181
|
+
|
|
182
|
+
# 임계값
|
|
183
|
+
thresholds:
|
|
184
|
+
battery_warning: 20 # 배터리 경고 (%)
|
|
185
|
+
battery_critical: 10 # 배터리 긴급 (%)
|
|
186
|
+
battery_drain_rate: 10 # 급속 방전 기준 (%/시간)
|
|
187
|
+
temp_warning: 85 # CPU 온도 경고 (°C)
|
|
188
|
+
temp_critical: 95 # CPU 온도 긴급 (°C)
|
|
189
|
+
memory_critical: 90 # 메모리 경고 (%)
|
|
190
|
+
disk_critical: 90 # 디스크 경고 (%)
|
|
191
|
+
network_spike_mb: 100 # 네트워크 급증 기준 (MB/간격)
|
|
192
|
+
session_hours_warning: 3 # 장시간 세션 경고 (시간)
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
설정 파일이 손상되거나 없어도 내장 기본값으로 동작합니다.
|
|
196
|
+
|
|
197
|
+
## Optional: CPU Temperature
|
|
198
|
+
|
|
199
|
+
기본적으로 macOS thermal pressure 기반으로 동작하지만, 정확한 CPU 온도를 보려면:
|
|
200
|
+
|
|
201
|
+
```bash
|
|
202
|
+
brew install osx-cpu-temp
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
설치 후 Sentinel이 자동으로 감지합니다.
|
|
206
|
+
|
|
207
|
+
## Architecture
|
|
208
|
+
|
|
209
|
+
```
|
|
210
|
+
sentinel/
|
|
211
|
+
├── pyproject.toml # PyPI 패키지 정의
|
|
212
|
+
├── LICENSE
|
|
213
|
+
├── README.md
|
|
214
|
+
├── sentinel_mac/ # Python 패키지
|
|
215
|
+
│ ├── __init__.py # 버전 정보
|
|
216
|
+
│ ├── __main__.py # python -m sentinel_mac
|
|
217
|
+
│ └── core.py # 모든 핵심 로직
|
|
218
|
+
├── sentinel.py # install.sh 호환 래퍼
|
|
219
|
+
├── config.yaml # 사용자 설정 템플릿
|
|
220
|
+
├── install.sh # 원커맨드 설치 + launchd 등록
|
|
221
|
+
└── uninstall.sh # 클린 제거
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
**내부 구조:**
|
|
225
|
+
|
|
226
|
+
```
|
|
227
|
+
MacOSCollector 시스템 메트릭 수집 (psutil + macOS 네이티브)
|
|
228
|
+
↓
|
|
229
|
+
AlertEngine 복합 조건 평가 + 쿨다운 관리
|
|
230
|
+
↓
|
|
231
|
+
NtfyNotifier 알림 발송 + 실패 시 재시도 큐
|
|
232
|
+
↓
|
|
233
|
+
Sentinel 메인 루프 + 시그널 핸들링 + PID 락
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
## Reliability
|
|
237
|
+
|
|
238
|
+
- **로그 로테이션** — 5MB x 3파일, 디스크를 잡아먹지 않음
|
|
239
|
+
- **중복 실행 방지** — 파일 락으로 데몬 이중 실행 차단
|
|
240
|
+
- **알림 재시도** — 네트워크 끊김 시 최대 3회 재전송
|
|
241
|
+
- **설정 폴백** — config.yaml 오류 시 기본값으로 자동 전환
|
|
242
|
+
- **Graceful Shutdown** — SIGTERM/SIGINT 시 락 해제 후 정상 종료
|
|
243
|
+
- **Auto Restart** — launchd KeepAlive로 크래시 시 자동 재시작
|
|
244
|
+
|
|
245
|
+
## Requirements
|
|
246
|
+
|
|
247
|
+
- macOS 10.15+ (Catalina 이상)
|
|
248
|
+
- Python 3.8+
|
|
249
|
+
- 인터넷 연결 (ntfy.sh 알림 발송)
|
|
250
|
+
|
|
251
|
+
의존성은 `install.sh`가 자동으로 설치합니다:
|
|
252
|
+
- `psutil` — 시스템 메트릭
|
|
253
|
+
- `pyyaml` — 설정 파싱
|
|
254
|
+
- `requests` — HTTP 알림 발송
|
|
255
|
+
|
|
256
|
+
## Uninstall
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
bash uninstall.sh
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
서비스 중지, 가상환경, 로그를 제거합니다. 소스와 설정 파일은 보존됩니다.
|
|
263
|
+
|
|
264
|
+
완전 삭제: `rm -rf sentinel/`
|
|
265
|
+
|
|
266
|
+
## Roadmap
|
|
267
|
+
|
|
268
|
+
- [ ] 웹 대시보드 (로컬 Flask + 실시간 차트)
|
|
269
|
+
- [ ] 세션 종료 리포트 (시간, 소모량, 최고온도 요약)
|
|
270
|
+
- [ ] Discord / Telegram 봇 (양방향 원격 제어)
|
|
271
|
+
- [ ] API 비용 추적 (프록시 기반 토큰 계산)
|
|
272
|
+
- [ ] 멀티 디바이스 통합
|
|
273
|
+
|
|
274
|
+
## License
|
|
275
|
+
|
|
276
|
+
MIT
|
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<h1 align="center">Sentinel</h1>
|
|
3
|
+
<p align="center">
|
|
4
|
+
<strong>AI Session Guardian for macOS</strong>
|
|
5
|
+
</p>
|
|
6
|
+
<p align="center">
|
|
7
|
+
AI 에이전트가 장시간 돌아갈 때, 맥북의 배터리·발열·메모리·디스크·네트워크를 감시하고<br/>
|
|
8
|
+
핸드폰으로 스마트 알림을 보내주는 경량 모니터링 데몬
|
|
9
|
+
</p>
|
|
10
|
+
<p align="center">
|
|
11
|
+
<a href="https://pypi.org/project/sentinel-mac/"><img src="https://img.shields.io/pypi/v/sentinel-mac" alt="PyPI"></a>
|
|
12
|
+
<img src="https://img.shields.io/badge/platform-macOS-blue" alt="macOS">
|
|
13
|
+
<img src="https://img.shields.io/badge/python-3.8+-green" alt="Python 3.8+">
|
|
14
|
+
<img src="https://img.shields.io/badge/notifications-ntfy.sh-yellow" alt="ntfy.sh">
|
|
15
|
+
<img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT License">
|
|
16
|
+
</p>
|
|
17
|
+
</p>
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## Why Sentinel?
|
|
22
|
+
|
|
23
|
+
Claude, GPT, Ollama 같은 AI 에이전트를 수시간 돌려놓고 자리를 비우는 상황, 익숙하시죠?
|
|
24
|
+
|
|
25
|
+
돌아와보면 이런 일이 벌어져 있습니다:
|
|
26
|
+
|
|
27
|
+
- 배터리 0%로 세션이 날아감
|
|
28
|
+
- CPU 과열로 쓰로틀링 걸려 작업이 멈춤
|
|
29
|
+
- 메모리 부족으로 프로세스가 kill됨
|
|
30
|
+
- 무한루프에 빠져 몇 시간째 전력만 소모 중
|
|
31
|
+
|
|
32
|
+
**Sentinel**은 이 문제를 해결합니다. 30초마다 시스템 상태를 체크하고, 위험 상황이 감지되면 핸드폰으로 즉시 알림을 보냅니다.
|
|
33
|
+
|
|
34
|
+
## Quick Start
|
|
35
|
+
|
|
36
|
+
### Option A: pip install (PyPI)
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
pip install sentinel-mac
|
|
40
|
+
sentinel --init-config # config 생성 + ntfy 토픽 자동 발급
|
|
41
|
+
sentinel --once # 시스템 상태 즉시 확인
|
|
42
|
+
sentinel # 데몬 시작
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Option B: git clone (macOS 자동 시작 포함)
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
git clone https://github.com/raunplaymore/sentinel.git
|
|
49
|
+
cd sentinel
|
|
50
|
+
bash install.sh # venv + 패키지 설치 + launchd 등록 (로그인 시 자동 시작)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
**핸드폰 설정**
|
|
54
|
+
|
|
55
|
+
1. [ntfy 앱](https://ntfy.sh) 설치 (iOS / Android)
|
|
56
|
+
2. 설치 시 출력된 토픽을 앱에서 구독
|
|
57
|
+
|
|
58
|
+
끝. 이제 알림이 자동으로 옵니다.
|
|
59
|
+
|
|
60
|
+
## What It Monitors
|
|
61
|
+
|
|
62
|
+
| 카테고리 | 감지 항목 | 알림 조건 |
|
|
63
|
+
|:--------:|----------|----------|
|
|
64
|
+
| **Battery** | 잔량, 충전 상태, 소모 속도 (%/h) | 20% 이하, 급속 방전 감지 |
|
|
65
|
+
| **Thermal** | CPU 온도, thermal throttling | 85°C 이상, 쓰로틀링 |
|
|
66
|
+
| **Memory** | 사용률, AI 프로세스 점유량 | 90% 이상 |
|
|
67
|
+
| **Disk** | 디스크 사용률, 잔여 공간 | 90% 이상 |
|
|
68
|
+
| **AI Session** | 프로세스 식별, 실행 시간 | 3시간+, 무한루프 의심 |
|
|
69
|
+
| **Network** | 전송량 추적 | 간격당 100MB 초과 |
|
|
70
|
+
| **Night Watch** | 새벽 방치 + 배터리 사용 | 0시~6시 미충전 세션 |
|
|
71
|
+
|
|
72
|
+
## Smart Alerts
|
|
73
|
+
|
|
74
|
+
단순 임계치가 아닌, **상황을 조합한** 알림을 보냅니다:
|
|
75
|
+
|
|
76
|
+
```
|
|
77
|
+
🔴 Critical 배터리 10% + 충전기 미연결 + AI 세션 활성
|
|
78
|
+
→ 긴급 알림 (소리 + 진동)
|
|
79
|
+
|
|
80
|
+
🟠 Warning AI 프로세스 CPU 높은데 네트워크 I/O 없음
|
|
81
|
+
→ 무한루프 의심 알림
|
|
82
|
+
|
|
83
|
+
🟡 Night Watch 새벽 3시 + AI 세션 + 배터리 방전 중
|
|
84
|
+
→ 야간 방치 감지
|
|
85
|
+
|
|
86
|
+
📊 Status 매시간 자동 상태 리포트
|
|
87
|
+
→ CPU, 메모리, 배터리, 디스크 요약
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
알림은 카테고리별 쿨다운이 적용되어 스팸 없이 정확한 타이밍에 도착합니다. Critical 알림은 쿨다운이 1/3로 짧아져 긴급 상황에서 빠르게 반복됩니다.
|
|
91
|
+
|
|
92
|
+
## AI Process Detection
|
|
93
|
+
|
|
94
|
+
Sentinel은 3단계 전략으로 AI 프로세스를 식별합니다:
|
|
95
|
+
|
|
96
|
+
| Tier | 방식 | 예시 |
|
|
97
|
+
|:----:|------|------|
|
|
98
|
+
| **1** | 확실한 AI 프로세스 이름 | `ollama`, `llamaserver`, `mlx_lm` |
|
|
99
|
+
| **2** | 일반 프로세스 + 커맨드라인 키워드 | `python3` + `transformers` |
|
|
100
|
+
| **3** | 커맨드라인 키워드만 | `*` + `langchain`, `torch` |
|
|
101
|
+
|
|
102
|
+
일반적인 `node`, `python3` 프로세스가 AI로 오탐되는 것을 방지합니다.
|
|
103
|
+
|
|
104
|
+
## Commands
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
# 현재 상태 즉시 확인
|
|
108
|
+
sentinel --once
|
|
109
|
+
|
|
110
|
+
# 출력 예시:
|
|
111
|
+
# ==================================================
|
|
112
|
+
# Sentinel — System Snapshot
|
|
113
|
+
# 2025-01-15 14:32:10
|
|
114
|
+
# ==================================================
|
|
115
|
+
# CPU: 23.4%
|
|
116
|
+
# Thermal: nominal
|
|
117
|
+
# Memory: 67.2% (10.8GB)
|
|
118
|
+
# Battery: 85.3% (충전중 🔌)
|
|
119
|
+
# Disk: 45.2% (잔여 234.5GB)
|
|
120
|
+
# Network: ↑0.12MB ↓1.45MB
|
|
121
|
+
#
|
|
122
|
+
# AI Processes (2):
|
|
123
|
+
# ollama CPU: 45.2% MEM:3200MB
|
|
124
|
+
# python3 CPU: 12.1% MEM: 890MB
|
|
125
|
+
# ==================================================
|
|
126
|
+
|
|
127
|
+
# 알림 테스트 (핸드폰으로 테스트 알림 발송)
|
|
128
|
+
sentinel --test-notify
|
|
129
|
+
|
|
130
|
+
# 버전 확인
|
|
131
|
+
sentinel --version
|
|
132
|
+
|
|
133
|
+
# 로그 실시간 확인
|
|
134
|
+
tail -f logs/sentinel.log
|
|
135
|
+
|
|
136
|
+
# 서비스 관리
|
|
137
|
+
launchctl unload ~/Library/LaunchAgents/com.sentinel.agent.plist # 중지
|
|
138
|
+
launchctl load ~/Library/LaunchAgents/com.sentinel.agent.plist # 시작
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
## Configuration
|
|
142
|
+
|
|
143
|
+
`config.yaml` 에서 모든 설정을 조정할 수 있습니다:
|
|
144
|
+
|
|
145
|
+
```yaml
|
|
146
|
+
# 모니터링
|
|
147
|
+
check_interval_seconds: 30 # 체크 간격 (초)
|
|
148
|
+
status_interval_minutes: 60 # 상태 리포트 주기 (분)
|
|
149
|
+
cooldown_minutes: 10 # 같은 알림 반복 방지 (분)
|
|
150
|
+
|
|
151
|
+
# 임계값
|
|
152
|
+
thresholds:
|
|
153
|
+
battery_warning: 20 # 배터리 경고 (%)
|
|
154
|
+
battery_critical: 10 # 배터리 긴급 (%)
|
|
155
|
+
battery_drain_rate: 10 # 급속 방전 기준 (%/시간)
|
|
156
|
+
temp_warning: 85 # CPU 온도 경고 (°C)
|
|
157
|
+
temp_critical: 95 # CPU 온도 긴급 (°C)
|
|
158
|
+
memory_critical: 90 # 메모리 경고 (%)
|
|
159
|
+
disk_critical: 90 # 디스크 경고 (%)
|
|
160
|
+
network_spike_mb: 100 # 네트워크 급증 기준 (MB/간격)
|
|
161
|
+
session_hours_warning: 3 # 장시간 세션 경고 (시간)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
설정 파일이 손상되거나 없어도 내장 기본값으로 동작합니다.
|
|
165
|
+
|
|
166
|
+
## Optional: CPU Temperature
|
|
167
|
+
|
|
168
|
+
기본적으로 macOS thermal pressure 기반으로 동작하지만, 정확한 CPU 온도를 보려면:
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
brew install osx-cpu-temp
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
설치 후 Sentinel이 자동으로 감지합니다.
|
|
175
|
+
|
|
176
|
+
## Architecture
|
|
177
|
+
|
|
178
|
+
```
|
|
179
|
+
sentinel/
|
|
180
|
+
├── pyproject.toml # PyPI 패키지 정의
|
|
181
|
+
├── LICENSE
|
|
182
|
+
├── README.md
|
|
183
|
+
├── sentinel_mac/ # Python 패키지
|
|
184
|
+
│ ├── __init__.py # 버전 정보
|
|
185
|
+
│ ├── __main__.py # python -m sentinel_mac
|
|
186
|
+
│ └── core.py # 모든 핵심 로직
|
|
187
|
+
├── sentinel.py # install.sh 호환 래퍼
|
|
188
|
+
├── config.yaml # 사용자 설정 템플릿
|
|
189
|
+
├── install.sh # 원커맨드 설치 + launchd 등록
|
|
190
|
+
└── uninstall.sh # 클린 제거
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
**내부 구조:**
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
MacOSCollector 시스템 메트릭 수집 (psutil + macOS 네이티브)
|
|
197
|
+
↓
|
|
198
|
+
AlertEngine 복합 조건 평가 + 쿨다운 관리
|
|
199
|
+
↓
|
|
200
|
+
NtfyNotifier 알림 발송 + 실패 시 재시도 큐
|
|
201
|
+
↓
|
|
202
|
+
Sentinel 메인 루프 + 시그널 핸들링 + PID 락
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
## Reliability
|
|
206
|
+
|
|
207
|
+
- **로그 로테이션** — 5MB x 3파일, 디스크를 잡아먹지 않음
|
|
208
|
+
- **중복 실행 방지** — 파일 락으로 데몬 이중 실행 차단
|
|
209
|
+
- **알림 재시도** — 네트워크 끊김 시 최대 3회 재전송
|
|
210
|
+
- **설정 폴백** — config.yaml 오류 시 기본값으로 자동 전환
|
|
211
|
+
- **Graceful Shutdown** — SIGTERM/SIGINT 시 락 해제 후 정상 종료
|
|
212
|
+
- **Auto Restart** — launchd KeepAlive로 크래시 시 자동 재시작
|
|
213
|
+
|
|
214
|
+
## Requirements
|
|
215
|
+
|
|
216
|
+
- macOS 10.15+ (Catalina 이상)
|
|
217
|
+
- Python 3.8+
|
|
218
|
+
- 인터넷 연결 (ntfy.sh 알림 발송)
|
|
219
|
+
|
|
220
|
+
의존성은 `install.sh`가 자동으로 설치합니다:
|
|
221
|
+
- `psutil` — 시스템 메트릭
|
|
222
|
+
- `pyyaml` — 설정 파싱
|
|
223
|
+
- `requests` — HTTP 알림 발송
|
|
224
|
+
|
|
225
|
+
## Uninstall
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
bash uninstall.sh
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
서비스 중지, 가상환경, 로그를 제거합니다. 소스와 설정 파일은 보존됩니다.
|
|
232
|
+
|
|
233
|
+
완전 삭제: `rm -rf sentinel/`
|
|
234
|
+
|
|
235
|
+
## Roadmap
|
|
236
|
+
|
|
237
|
+
- [ ] 웹 대시보드 (로컬 Flask + 실시간 차트)
|
|
238
|
+
- [ ] 세션 종료 리포트 (시간, 소모량, 최고온도 요약)
|
|
239
|
+
- [ ] Discord / Telegram 봇 (양방향 원격 제어)
|
|
240
|
+
- [ ] API 비용 추적 (프록시 기반 토큰 계산)
|
|
241
|
+
- [ ] 멀티 디바이스 통합
|
|
242
|
+
|
|
243
|
+
## License
|
|
244
|
+
|
|
245
|
+
MIT
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=68.0", "wheel"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "sentinel-mac"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "AI Session Guardian for macOS — monitors battery, thermal, memory, disk, and AI processes with smart phone alerts"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.8"
|
|
12
|
+
authors = [
|
|
13
|
+
{ name = "raunplaymore" },
|
|
14
|
+
]
|
|
15
|
+
keywords = ["macos", "monitoring", "ai", "battery", "thermal", "sentinel", "notification"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Environment :: MacOS X",
|
|
19
|
+
"Intended Audience :: Developers",
|
|
20
|
+
"Operating System :: MacOS",
|
|
21
|
+
"Programming Language :: Python :: 3",
|
|
22
|
+
"Programming Language :: Python :: 3.8",
|
|
23
|
+
"Programming Language :: Python :: 3.9",
|
|
24
|
+
"Programming Language :: Python :: 3.10",
|
|
25
|
+
"Programming Language :: Python :: 3.11",
|
|
26
|
+
"Programming Language :: Python :: 3.12",
|
|
27
|
+
"Programming Language :: Python :: 3.13",
|
|
28
|
+
"Topic :: System :: Monitoring",
|
|
29
|
+
"Topic :: Utilities",
|
|
30
|
+
]
|
|
31
|
+
dependencies = [
|
|
32
|
+
"psutil>=5.9,<7",
|
|
33
|
+
"pyyaml>=6.0,<7",
|
|
34
|
+
"requests>=2.28,<3",
|
|
35
|
+
]
|
|
36
|
+
|
|
37
|
+
[project.urls]
|
|
38
|
+
Homepage = "https://github.com/raunplaymore/sentinel"
|
|
39
|
+
Repository = "https://github.com/raunplaymore/sentinel"
|
|
40
|
+
Issues = "https://github.com/raunplaymore/sentinel/issues"
|
|
41
|
+
|
|
42
|
+
[project.scripts]
|
|
43
|
+
sentinel = "sentinel_mac.core:main"
|
|
44
|
+
|
|
45
|
+
[tool.setuptools.packages.find]
|
|
46
|
+
include = ["sentinel_mac*"]
|