# Monitor

장시간 실행되는 스크립트에서 이벤트를 스트리밍하는 백그라운드 모니터를 시작합니다. 표준 출력의 각 줄이 알림이 됩니다 — 작업을 계속하면서 이벤트가 채팅에 도착합니다.

## 사용 시점

- 배포가 실행되는 동안 로그 파일의 오류, 경고 또는 충돌 특징을 지속적으로 추적할 때
- 원격 API, PR 또는 CI 파이프라인을 30초마다 폴링하여 새로운 상태 이벤트를 확인할 때
- 파일시스템 디렉토리나 빌드 출력의 변화를 실시간으로 감시할 때
- 많은 반복에 걸쳐 특정 조건을 기다릴 때 (예: 학습 단계 마일스톤 또는 큐 소진)
- 단순한 "완료까지 대기"에는 **사용하지 않는다** — 그 경우 `run_in_background`가 있는 `Bash`를 사용하면 프로세스 종료 시 완료 알림이 한 번 전송된다

## 매개변수

- `command` (문자열, 필수): 실행할 셸 명령 또는 스크립트. 표준 출력에 쓰인 각 줄이 독립적인 알림 이벤트가 된다. 프로세스가 종료되면 모니터가 끝난다.
- `description` (문자열, 필수): 모든 알림에 표시되는 짧고 읽기 쉬운 레이블. 구체적으로 작성할 것 — "deploy.log의 오류"가 "로그 감시 중"보다 낫다. 이 레이블로 어떤 모니터가 발동했는지 식별한다.
- `timeout_ms` (숫자, 기본값 `300000`, 최대 `3600000`): 강제 종료 기한 (밀리초). 이 시간이 지나면 프로세스가 종료된다. `persistent: true`일 때는 무시된다.
- `persistent` (불리언, 기본값 `false`): `true`로 설정하면 모니터가 타임아웃 없이 세션 전체 동안 실행된다. `TaskStop`으로 명시적으로 중지한다.

## 예시

### 예시 1: 로그 파일의 오류와 충돌 추적

이 예시는 모든 종료 상태를 커버한다: 성공 마커, 트레이스백, 일반적인 오류 키워드, OOM 강제 종료, 예기치 않은 프로세스 종료.

```bash
tail -F /var/log/deploy.log | grep -E --line-buffered \
  "deployed|Traceback|Error|FAILED|assert|Killed|OOM"
```

모든 파이프에서 `grep --line-buffered`를 사용할 것. 사용하지 않으면 OS가 4 KB 블록 단위로 출력을 버퍼링하여 이벤트가 수 분 지연된다. 교대 패턴은 성공 경로(`deployed`)와 실패 경로(`Traceback`, `Error`, `FAILED`, `Killed`, `OOM`) 모두를 커버한다. 성공 마커만 감시하는 모니터는 충돌 시 침묵한다 — 침묵은 "아직 실행 중"과 구별할 수 없다.

### 예시 2: 원격 API를 30초마다 폴링

```bash
while true; do
  curl -sf "https://api.example.com/status" || true
  sleep 30
done | grep --line-buffered -E "completed|failed|error"
```

`|| true`는 일시적인 네트워크 장애로 루프가 종료되는 것을 방지한다. 속도 제한을 피하려면 원격 API에 30초 이상의 폴링 간격이 적절하다. grep 패턴을 조정하여 성공과 실패 응답을 모두 캡처하고 API 측 오류가 침묵으로 가려지지 않도록 한다.

## 참고사항

- **파이프에서 항상 `grep --line-buffered`를 사용할 것.** 사용하지 않으면 OS가 4 KB 블록이 채워질 때까지 출력을 축적하기 때문에 파이프 버퍼링으로 인해 이벤트가 수 분 지연된다. `--line-buffered`는 각 줄 후에 강제로 플러시한다.
- **필터는 성공과 실패 시그니처를 모두 커버해야 한다.** 성공 마커만 감시하는 모니터는 충돌, 행, 예기치 않은 종료 시 침묵한다. 교대 패턴을 넓힌다: 성공 키워드 외에도 `Error`, `Traceback`, `FAILED`, `Killed`, `OOM` 등 종료 상태 마커를 포함한다.
- **원격 API의 폴링 간격은 30초 이상으로 할 것.** 외부 서비스에 대한 고빈도 폴링은 속도 제한 오류나 차단 위험이 있다. 로컬 파일시스템이나 프로세스 확인에는 0.5~1초가 적절하다.
- **세션 전체 모니터링에는 `persistent: true`를 사용할 것.** 기본 `timeout_ms`는 300,000ms(5분)으로 프로세스가 종료된다. 명시적으로 중지할 때까지 계속 실행하려면 `persistent: true`를 설정하고 완료 후 `TaskStop`을 호출한다.
- **이벤트 과다 시 자동 중지.** 표준 출력의 각 줄이 대화 메시지가 된다. 필터가 너무 넓어 너무 많은 이벤트가 발생하면 모니터가 자동으로 중지된다. 더 좁은 `grep` 패턴으로 재시작할 것. 200ms 이내에 도착하는 줄들은 하나의 알림으로 묶인다.
