> For the complete documentation index, see [llms.txt](https://kopens.gitbook.io/plantpulse-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://kopens.gitbook.io/plantpulse-platform/admin/modules/monitor.md).

# monitor (모니터링)

## 역할

플랫폼 자체의 운영 지표를 수집 / 노출하는 모니터링 에이전트. **외부 모니터링 시스템(Grafana, Prometheus, Zabbix)** 의 데이터 소스 역할을 합니다.

| 항목    | 값                                                     |
| ----- | ----------------------------------------------------- |
| 모듈명   | `plantpulse-monitor`                                  |
| 설치 경로 | `/opt/kopens/plantpulse-platform/plantpulse-monitor/` |
| 헬스 포트 | **4949**                                              |
| 외부 포트 | 4950 (HTTPS health)                                   |

## 수집 지표

```mermaid
graph LR
  MON[plantpulse-monitor<br/>:4949] --> HOST[호스트 자원<br/>CPU / 메모리 / 디스크 / 네트워크]
  MON --> JVM[JVM<br/>힙 / GC / Thread]
  MON --> SVC[모듈별 상태<br/>RUNNING / STOPPED]
  MON --> JMX[JMX 메트릭<br/>Cassandra / Kafka / Tomcat]
  MON --> APP[애플리케이션 메트릭<br/>처리량 / 에러율]
```

## 디렉토리 구조

```
plantpulse-monitor/
├── bin/start.sh stop.sh log-viewer.sh
├── config/monitor.properties
├── lib/
└── logs/system.log
```

## 주요 엔드포인트

```bash
# 헬스
curl -fsS http://127.0.0.1:4949/health

# 모든 메트릭 (Prometheus 형식)
curl -fsS http://127.0.0.1:4949/metrics

# 모듈별 상태
curl -fsS http://127.0.0.1:4949/status/services

# 외부 헬스 체크 (HTTPS)
curl -kfsS https://127.0.0.1:4950/api/health | jq
```

## JMX 포트 (사설망 only)

| 포트                                      | 대상              |
| --------------------------------------- | --------------- |
| 6199 / 6299 / 6399 / 6499               | 애플리케이션 모듈 JMX   |
| 7099 / 7299 / 7399 / 7499 / 7599 / 7899 | 인프라 / 분석 모듈 JMX |

외부 모니터링 노드에서 JMX 접속 시 source IP 허용 + 인증 설정이 필요합니다.

## Grafana 연동

플랫폼 동봉 Grafana ([timeseries 모듈](/plantpulse-platform/admin/modules/timeseries.md), 포트 3000) 또는 외부 Grafana 에서 다음 데이터 소스를 연결합니다.

* **Prometheus** — `http://[HOST]:4949/metrics` (스크레이프)
* **JMX Exporter** — JMX → Prometheus exporter (선택)

## 운영 명령

```bash
cd /opt/kopens/plantpulse-platform/plantpulse-startup

./restart-monitor.sh
./status.sh                # 4949 RUNNING 확인
```

## 자주 발생하는 문제

| 증상                   | 원인        | 조치                       |
| -------------------- | --------- | ------------------------ |
| 헬스 엔드포인트 응답 없음       | 모니터 다운    | `restart-monitor.sh`     |
| JMX 접속 실패            | 방화벽       | source IP 허용 또는 SSH 터널   |
| Prometheus 스크레이프 5xx | 백엔드 모듈 다운 | `./status.sh` 로 의존 모듈 확인 |

## 관련 문서

* [모듈 인덱스](/plantpulse-platform/admin/modules.md)
* [시스템 모니터링](/plantpulse-platform/admin/monitoring.md)
* [포트 및 서비스 관리](/plantpulse-platform/admin/ports.md)