5 min read

서비스 모니터 가이드

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. 트리거 뷰

등록된 트리거(스케줄)별 최근 실행 현황과 초과(overdue) 여부를 표로 보여줍니다. 예정 주기를 넘겨 리포트가 없는 트리거를 격리해 확인할 수 있습니다.

🛠️ 상태 점검 방법

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

💡 참고

상태 값 의미: 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 리포트와 조인이 성립하지 않는 구조적 오탐 가능	개별 트리거의 최근 리포트 유무를 확인하고, 실제 '멈춘' 트리거만 조치하세요.
값이 계속 바뀜	30초/60초 자동 새로고침 동작	정상입니다. 특정 시점을 고정해 보려면 값을 캡처해 두세요.
상단 가이드 버튼(📖)이 안 보임	가이드 매핑 누락(구버전 배포)	이 가이드가 배포·인덱싱되면 표시됩니다.
`UNKNOWN` 행이 안 지워짐	휴지통(빨강) 버튼을 눌렀는데, 그건 tKVS 레코드 삭제라 애초에 `UNKNOWN` 행(`ksn` 없음)엔 안 보임	주황색 "모니터링 대상에서 제거" 아이콘을 사용하세요(giip #1307).
"스크립트 추가" 후에도 안 보임	같은 이름이 이미 활성 상태로 등록되어 있어 409 응답(추가 실패)	목록에서 동일 이름을 찾아 이미 있는지 확인하세요.

버전: 1.1 최종 수정: 2026-08-21 (giip #1307: 모니터링 대상 스크립트 DB화 + CRUD API/UI 반영) 소스 파일: giipv3/public/help/service-monitor.ko.md

← PreviousSES Proposals Admin Next →Service Patterns Auto-Discovery