서비스 모니터 가이드

GIIP 생태계에서 동작하는 서비스·크론 스크립트의 실시간 상태와 건강도, 실행 이력을 하나의 관리자 화면에서 감시합니다. 요약 대시보드로 전체 현황을 훑고, 목록·플로우·트리거 뷰로 개별 서비스를 상세히 들여다볼 수 있습니다.

🖥️ 서비스 모니터 페이지로 이동 →

📋 개요

서비스 모니터 페이지는 GIIP 생태계에서 돌아가는 크론 스크립트·에이전트 워커·Azure Function의 실시간 상태를 관제하는 관리자 화면입니다. 각 서비스가 마지막으로 리포트한 상태(실행중/정상/오류/미보고), 실행 시각, 텔레메트리(성공·실패·스킵 등)를 표로 보여주고, 상단 요약 카드로 전체 건강도를 한눈에 파악할 수 있습니다. 데이터는 에이전트가 시계열 저장소(tKVS)에 올린 상태 리포트에서 오며, 이 화면은 운영자가 "무엇이 돌고 무엇이 멈췄는지"를 판단하는 관제 화면입니다.

⚠️ 이 화면은 관리자 전용입니다. 접근하려면 관리자 레벨 **uLevel >= 70**이 필요합니다. 그 미만 사용자는 홈으로 리다이렉트됩니다.

🔍 화면 구성

1. 상단 헤더

• 페이지 제목/설명: "서비스 모니터"(현지화됨)와 요약 설명.
• 뷰 전환 버튼: 목록 / 플로우 / 트리거 세 가지 뷰를 토글합니다.
• 스크립트 추가 버튼(목록 뷰 전용, giip #1307): 새 모니터링 대상 스크립트를 등록하는 모달을 엽니다.
• 새로고침 버튼: 서비스 상태를 즉시 다시 불러옵니다(로딩 중 아이콘 회전). 목록 뷰는 30초, 플로우·트리거 뷰는 60초마다 자동 갱신됩니다.

2. 요약 대시보드

상단 4개 카드로 전체 서비스의 집계 현황을 보여줍니다.

카드	의미
전체(Total)	모니터링 대상 서비스/스크립트 총 개수
실행중(Running)	현재 RUNNING 상태로 실행 중인 서비스 수
정상(Healthy)	IDLE(정상 대기) 상태로 리포트한 서비스 수
오류(Error)	ERROR(실패/비정상) 상태로 리포트한 서비스 수

3. 목록 뷰(서비스 표)

각 행이 하나의 서비스/스크립트를 나타내며, 클릭하면 펼쳐 상세(하위 작업·지표)를 볼 수 있습니다.

컬럼	설명
Script Name	스크립트/서비스 이름
Migration	Azure Function 이관 상태(완료/대기/해당없음)
Hostname	리포트를 올린 호스트
Status	상태 배지(RUNNING / IDLE / ERROR / UNKNOWN)
Last Execution	마지막 실행 시각
Telemetry	성공·실패·스킵·강제종료 등 실행 지표
Details	펼치기(하위 작업·원본 리포트 확인)

각 행 오른쪽에는 최대 두 개의 액션 아이콘이 있습니다(giip #1307로 명확히 구분):

아이콘	문구	동작	대상
🚫 (원+X, 주황)	"모니터링 대상에서 제거"	tServiceMonitorScript.enabled를 끕니다(소프트 삭제). tKVS 텔레메트리는 건드리지 않음.	DB에 등록된 모든 행(모니터링 목록 출처, UNKNOWN이라 raw/ksn이 없는 행도 포함)
🗑️ (휴지통, 빨강)	"삭제"(giip #1214)	ksn 기준으로 tKVS 텔레메트리 레코드 1건을 삭제합니다.	raw.ksn이 있는 행만(실제 리포트가 온 행)

⚠️ 두 버튼은 완전히 다른 기능입니다. 휴지통(빨강)은 텔레메트리 이력 1건만 지우고, 화면에서 스크립트 행 자체를 없애려면(특히 한 번도 리포트를 안 보낸 UNKNOWN 행) 반드시 주황 아이콘 ("모니터링 대상에서 제거")을 써야 합니다. giip #1214 당시 이 구분이 없어서 UNKNOWN 행을 지울 방법이 없었던 문제(giip #1307)를 해결한 기능입니다.

4. 플로우 뷰

서비스 간 의존 관계와 데이터 흐름을 시각화합니다(ServiceMonitorFlow). 어떤 서비스가 어떤 서비스로 이어지는지 흐름도로 확인합니다.

5. 트리거 뷰

등록된 알림 트리거(tKVSTrigger)의 실시간 평가 현황을 표로 보여줍니다. 배치 SP dbo.pKVSCheckSchd가 5분마다(Azure Function KVSCheckSchdTimer, giip #2098) 이 조건들을 재평가해 ktChkDt를 갱신하고, 조건을 초과한 트리거는 Mail 채널이 켜져 있으면 실제로 이메일을 발송합니다.

컬럼 의미

컬럼	의미
키(Key)	감시 대상 식별자. ktype='lssn'이면 서버(lssn) 번호입니다.
팩터(Factor)	감시 대상 지표 이름(예: DISKUSAGE, CPUUSAGE). tKVS에 실제 리포트가 들어올 때 쓰는 것과 동일한 키입니다. 이 값이 비어 있으면 tKVS와 절대 조인될 수 없어 영구히 "비활성" 상태입니다(아래 상태 배지 표 참고).
조건	kAttrib kLogic kVal 형식(예: Capacity gt 90 = "Capacity 값이 90 초과"). kAttrib='giipLogDate'는 특수 케이스로 "마지막 리포트 이후 경과 초"를 비교합니다(예: giipLogDate gt 600 = "10분 이상 리포트 없음").
마지막 리포트	이 키+팩터 조합으로 tKVS에 실제 값이 마지막으로 들어온 시각. -이면 최근 2일간 리포트가 전혀 없었다는 뜻입니다.
마지막 체크	배치(pKVSCheckSchd)가 이 트리거를 마지막으로 평가한 시각(5분 주기 갱신). 이 값이 오래됐다면 배치 자체가 멈춘 것이니 KVSCheckSchdTimer(Azure Function) 가동 여부부터 확인하세요.
알림 채널	Mail / SMS / Slack 중 이 트리거에서 켜진 채널. Mail은 실제로 발송됩니다(giip #2098, tEmailServerConfig의 활성 SMTP 설정 + giipApiSendEmail을 재사용). SMS는 발송 게이트웨이가 연동되어 있지 않아 표시만 되고 실제 발송되지 않습니다. Slack은 트리거별 웹훅(kSlackWebhook)이 설정된 경우에만 발송되며, 2026-09-07 기준 실제로 웹훅이 설정된 트리거는 0건입니다. Mail 수신처 결정 규칙(giip #2412): (1) kMail이 비어 있지 않고 '-'가 아니면 그 값, (2) 그 외이며 해당 usn이 tKVSTriggerDefaultMail에 등록되어 있으면 그 기본 수신처, (3) 둘 다 없으면 발송하지 않고 [WARN] no recipient for ktSn=... 로그만 남김. kMailAct=0이면 위와 무관하게 발송 안 함.
상태	아래 배지 4종 중 하나.

상태 배지

배지	조건	의미
정상(초록)	팩터 있음 + 최근 리포트 있음 + 조건 미초과	정상 동작 중. 조치 불필요.
초과(빨강, 깜빡임)	팩터 있음 + 조건 초과	실제 이상 신호. 아래 "조치 예시" 참고.
데이터 없음(회색)	팩터 있음 + 최근 2일간 리포트 없음	감시 대상 자체가 리포트를 안 보내고 있음(에이전트 중단 가능성).
비활성(회색, 흐림, 기본 숨김)	팩터 값이 비어 있음	tKVS와 조인 조건 자체가 성립할 수 없어 영원히 매칭되지 않는 죽은 트리거 정의입니다. 실제 이상이 아니므로 목록에서 기본적으로 숨겨지며, 표 상단의 "비활성 트리거 표시"를 눌러야 보입니다(giip #2098). 정리하려면 DB에서 해당 tKVSTrigger 행의 kfactor를 채우거나 그 행을 삭제하세요.

조치 예시 (조건 조합 → 의미 → 조치)

키	팩터	조건	상태	의미	조치
584	DISKUSAGE	Capacity gt 90	초과(빨강)	lssn=584 서버 디스크 사용률이 90%를 초과함	해당 서버(lssn 584)에 접속해 디스크 정리(로그·임시파일 삭제) 또는 볼륨 증설. Mail 채널이 켜져 있으면 kMail 주소로 이미 이메일이 발송됐을 것입니다.
2622	CPUUSAGE	giipLogDate gt 600	초과(빨강)	lssn=2622 서버의 CPUUSAGE 리포트가 600초(10분) 이상 끊김	해당 서버의 에이전트(giipAgent) 프로세스·스케줄러가 살아있는지 확인.
(임의)	(임의)	(아무 조건)	데이터 없음(회색)	최근 2일간 이 키+팩터 리포트가 전혀 없음	에이전트 설치·네트워크·시크릿키 문제부터 점검. 트리거 정의 자체가 오래된 오타(팩터명 불일치)일 수도 있음.
(임의)	(비어있음)	조건이 불완전하게 보임	비활성(회색, 흐림, 기본 숨김)	팩터가 없어 영구 매칭 불가능한 죽은 정의	실제 감시가 필요하면 kfactor를 채워 재설정하고, 필요없으면 DB에서 삭제.

🛠️ 상태 점검 방법

1. 화면에 들어오면 상단 요약 카드로 오류(Error) 개수를 먼저 확인합니다.
2. 목록 뷰에서 상태 배지가 ERROR이거나 UNKNOWN(리포트 없음)인 행을 찾습니다.
3. 해당 행을 클릭해 펼쳐 Last Execution / Telemetry / 하위 작업을 검토합니다 — 마지막 실행 시각이 오래됐거나 실패 지표가 높으면 비가동 후보입니다.
4. 새로고침 버튼으로 최신 리포트를 다시 불러와 일시적 지연인지 확인합니다.
5. 트리거 뷰로 넘어가 예정 주기를 넘긴(초과) 트리거가 있는지 교차 확인합니다.

💡 참고

• 상태 값 의미: RUNNING=실행 중, IDLE=정상 대기(요약의 "정상"에 집계), ERROR=실패, UNKNOWN=최근 리포트 없음(에이전트가 tKVS에 상태를 올리지 않은 상태).
• UNKNOWN이 많은 경우는 서비스가 죽었다기보다 해당 에이전트/스크립트가 텔레메트리를 리포트하지 못하는 상태일 수 있습니다 — 에이전트 가동 여부부터 확인하세요.
• 자동 갱신: 목록 30초, 플로우·트리거 60초 주기로 자동 새로고침되므로 값이 주기적으로 바뀔 수 있습니다.
• 접근 권한은 prop 모드로 페이지에 minLevel={70}이 하드코딩되어 있어 항상 uLevel >= 70이 필요합니다(메뉴 설정 값과 무관).

API 참조

이 페이지는 디스패치 커맨드(fetchAzureCommand 경유)로 백엔드와 통신합니다. 별도 API 가이드가 없으므로 핵심을 여기에 기술합니다.

상태 폴링(tKVS)

커맨드	용도	백엔드 SP
ApiServiceMonitorGetStatus	모니터링 대상 스크립트의 tKVS 상태(RUNNING/IDLE/ERROR) 조회(30초 폴링)	pApiApiServiceMonitorGetStatusbyAK
ApiServiceMonitorGetFlow	플로우 뷰의 노드/엣지 조회	(플로우용 SP)
ApiServiceMonitorGetTriggerStatus	트리거 뷰의 트리거별 실행 현황 조회	pApiApiServiceMonitorGetTriggerStatusbyAK
ApiServiceMonitorDelete	목록 뷰의 서비스 상태 레코드 1건을 ksn 기준으로 삭제(휴지통 버튼, 삭제 확인 모달 필수). 안전장치: 해당 행의 kFactor 가 서비스 모니터 factor 일 때만 삭제하고, 아니면 403 반환. 요청 본문 { ksn }. (giip #1214)	pApiApiServiceMonitorDeletebyAK

모니터링 대상 스크립트 CRUD(giip #1307, tServiceMonitorScript)

"행 자체가 화면에 뜨는지"를 결정하는 목록. 과거에는 useServiceStatus.ts의 CRON_SCRIPTS 배열에 하드코딩되어 있었으나, 이 테이블+API로 이관되어 배포 없이 UI에서 CRUD가 가능해졌다.

커맨드	용도	백엔드 SP
ApiServiceMonitorScriptList	모니터링 대상 스크립트 목록 조회(enabled=1, sortOrder 순). 요청 본문은 비워도 됨({}).	pApiApiServiceMonitorScriptListbyAK
ApiServiceMonitorScriptAdd	신규 스크립트 등록("스크립트 추가" 모달). 요청 본문 { scriptName(필수), category?, azureFunction?, migrationStatus? }. 과거 제거된 동일 이름이 있으면 재활성화(200), 신규면 201, 이미 활성 상태면 409.	pApiApiServiceMonitorScriptAddbyAK
ApiServiceMonitorScriptDelete	모니터링 대상에서 제거(주황 아이콘). tKVS는 건드리지 않고 tServiceMonitorScript.enabled만 끈다 — UNKNOWN(텔레메트리 미보고) 행도 제거 가능. 요청 본문 { scriptId } 또는 { scriptName }.	pApiApiServiceMonitorScriptDeletebyAK

• 응답은 결과셋 배열 형태이며(예: [데이터, 상태]), 클라이언트는 첫 번째(데이터) 배열을 읽습니다.
• 상태 필드 RstVal = 200(List/Delete/재등록) 또는 201(Add 신규)은 정상, 409는 이미 모니터링 중, 401은 세션 만료/미인증(재로그인 필요)을 뜻합니다.
• 성역(giipfaw run.ps1) 무수정: giipApi가 명령명→SP 이름으로 일반 라우팅하므로 giipdb에 SP만 추가하면 giipfaw 코드 변경 없이 동작합니다(giip-1214와 동일 패턴).

문제 해결

증상	원인	해결
접속 즉시 홈으로 튕김	uLevel이 70 미만	관리자 계정(레벨 70+)으로 로그인하세요.
"세션 만료" / 401 오류	인증 토큰 만료 또는 없음	다시 로그인한 뒤 새로고침을 누르세요.
표의 대부분이 UNKNOWN	에이전트/스크립트가 tKVS에 상태를 리포트하지 않음	해당 에이전트 가동 여부와 텔레메트리 리포트 경로를 확인하세요.
회색 흐린 "비활성" 행이 많이 보임	kfactor가 비어 있어 tKVS와 영구히 매칭될 수 없는 죽은 트리거 정의(정상적인 현상, 실제 이상 아님)	기본적으로 숨겨져 있습니다. 필요 시 상단의 "비활성 트리거 표시"로 확인한 뒤, DB에서 kfactor를 채우거나 삭제해 정리하세요(giip #2098).
"초과(빨강)" 트리거가 있는데 메일이 안 옴	kMailAct가 꺼져 있거나, kMail과 usn 기본 수신처(tKVSTriggerDefaultMail) 모두 비어 있거나, 배치(KVSCheckSchdTimer)가 아직 이 트리거를 평가하지 못했을 수 있음	먼저 "마지막 체크" 시각이 최근인지 확인(배치 가동 여부), "알림 채널"에 Mail이 표시되는지 확인. 그래도邮件이 안 오면 kMail 주소(트리거 행)와 tKVSTriggerDefaultMail(해당 usn) 모두 DB에서 확인하세요. kMail이 비어 있어도 usn 기본 수신처가 있으면 그 주소로 폴백 발송됩니다(giip #2412).
"알림 채널"에 SMS/Slack이 표시되는데 알림이 안 옴	SMS는 발송 게이트웨이가 아직 연동되지 않았고, Slack은 트리거별 웹훅이 실제로 설정된 경우만 동작(2026-09-07 기준 설정된 트리거 0건)	현재는 Mail 채널만 실제로 발송됩니다. SMS/Slack이 꼭 필요하면 giip 이슈로 게이트웨이/웹훅 연동을 요청하세요.
값이 계속 바뀜	30초/60초 자동 새로고침 동작	정상입니다. 특정 시점을 고정해 보려면 값을 캡처해 두세요.
상단 가이드 버튼(📖)이 안 보임	가이드 매핑 누락(구버전 배포)	이 가이드가 배포·인덱싱되면 표시됩니다.
UNKNOWN 행이 안 지워짐	휴지통(빨강) 버튼을 눌렀는데, 그건 tKVS 레코드 삭제라 애초에 UNKNOWN 행(ksn 없음)엔 안 보임	주황색 "모니터링 대상에서 제거" 아이콘을 사용하세요(giip #1307).
"스크립트 추가" 후에도 안 보임	같은 이름이 이미 활성 상태로 등록되어 있어 409 응답(추가 실패)	목록에서 동일 이름을 찾아 이미 있는지 확인하세요.

---

버전: 1.2 최종 수정: 2026-09-07 (giip #2098: 트리거 뷰 UI 개선(죽은 트리거 숨김/알림 채널 상태 명시) + 알림 배치 부활 반영) 소스 파일: giipv3/public/help/service-monitor.ko.md