서비스 개요 — 큐레이션 라이브 보드

개요 — 무엇을 하나

서비스 개요(Service Overview) 는 InfraGuard 의 Service 대메뉴 첫 화면(/service)으로, 운영 중인 서비스(데몬)의 큐레이션 라이브 관제 보드입니다. 운영자가 관심 있는 서비스를 직접 골라 우선순위 카드로 배치하면, 각 카드가 종류별 대표 지표를 실시간으로 보여주고, 맨 앞(우선) 카드로 가용성 게이지를, 하단에서 선택 카드들의 라이브 시계열을 그립니다.

특징:

선택·순서는 브라우저(localStorage)가 소유 — 서버에 저장하지 않습니다. 같은 계정이라도 브라우저마다 보드 구성이 다를 수 있습니다.
전부 읽기 전용·경량 — ServiceBoardService(15초 캐시)가 하위 서비스(웹·DB·세션·Catalog)의 지표를 하나의 정규 카드 형태로 통합합니다. 화면이 원격 서버에 직접 연결을 새로 여는 일은 없습니다(단, DB 카드는 데이터가 오래되면 즉석 1회 샘플 — 아래 참조).
논리 도달성/부하만 봅니다. 물리 포트 오픈·노출 스캔은 Firewall 소관입니다(역할 경계).

이 보드는 데모용 가짜 fleet 이 아니라 전부 실데이터입니다. 지표 원천은 이미 수집기가 채운 infr_web_metric · infr_db_metric · infr_redis_metric 와 infr_service(Catalog) 입니다.

언제 쓰나

아침에 출근해 핵심 서비스 몇 개(예: 대표 웹사이트, 메인 DB, 세션 Redis)의 상태를 한 화면에서 빠르게 훑고 싶을 때.
NOC / 상황판용 전체화면 대시보드가 필요할 때(전체화면 버튼 + 높이 슬라이더로 화면에 맞춤).
특정 서비스의 최근 추세(1시간·6시간·하루)를 시계열로 확인하고 싶을 때.
세부 진단이 필요하면 여기서 감을 잡고 Web · Database · Sessions · Catalog 전용 화면으로 내려갑니다.

화면 구성

상단 KPI 스트립

realKpi() 가 계산하는 전사 요약(30초 폴링으로 갱신):

KPI	의미	원천
웹 트래픽(web)	등록 웹서비스 총 RPS · 대역폭	`WebMetricService::kpi(dashboard())`
DB 부하(db)	access=database 수집기별 최신 저장 QPS 합 · 총 연결수	`DbCollectorService::latest()` 합산
웹 가동률(uptime)	24h 가동률	`WebProbeService::availabilityOrPassive()`(능동 프로브 우선)
평균 지연(latency)	프로브 평균 응답(ms)	동일
인시던트(incidents)	최근 7일 등록 건수	`InfrIncident` `created_at ≥ now-7d`

웹 가동률·평균 지연은 능동 합성 프로브를 우선합니다. 수동 vts 트래픽 카운터만으로는 트래픽 없는 완전 다운·3xx 뒤 숨은 5xx·카운터 리셋을 오진하므로, WebProbeService 의 실제 HTTP 프로브 결과를 씁니다. 프로버가 아직 안 돌아 커버리지가 없으면 passive(web24h) 로 폴백합니다.

서비스 가용성 게이지

우선순위 첫 web/db/session 카드의 속성으로 conic 도넛/아크를 그립니다(그 3종 카드가 하나도 없으면 placeholder 안내).

카드 종류	게이지 모양	중앙 값	톤 규칙
web	응답코드 4구간 도넛	REQ(현재 RPS)	2xx=good · 3xx=info · 4xx=warn · 5xx=crit
database	연결 포화도(conn_pct) 아크	QPS	≥90 crit · ≥70 warn · 그외 good
session	적중률(hit_rate) 아크	OPS	≥90 good · ≥70 warn · 그외 crit

서비스 보드(카드 그리드)

선택한 서비스가 우선순위 순서로 카드 배치됩니다. 각 카드는 종류별로 다른 KPI를 표시합니다:

종류	daemon 기본	헤더(alias)	주요 KPI
web	nginx	대표 도메인	지연 · RPS · 열린 세션(활성 커넥션) · 24시간 누적 요청 · 에러율
database	mysql/mariadb/postgres/mongo	수집기 alias	QPS · 좌석(연결/최대) · 포화도 · 실행 중 · lock(row-lock 평균 ms) · Slow 누적 · 대기
session	redis	노드 alias	OPS · 적중률 · 클라이언트(현재 세션) · 키 · 포화도(메모리 수용률)
proxy	software_key/proxy	인스턴스 alias	의존성(+N) · 지연 · 리슨 포트
docker	software_key/docker	인스턴스 alias	의존성(+N) · 지연 · 리슨 포트

카드는 드래그 핸들로 재정렬(SortableJS) — DOM 순서가 곧 우선순위(sel)로 다시 쓰이고 localStorage 에 저장됩니다.
카드 우상단 ✕ 로 보드에서 제거합니다.
proxy/docker 카드는 가용성 도넛·시계열이 없습니다(web/db/session 전용).

라이브 서비스(하단 시계열)

시리즈가 있는 선택 카드(web/db/session)를 2열 그리드의 SVG area+line 스파크로 그립니다. 각 그래프에는 ruler(세로 그리드 + start·mid·end HH:MM 라벨)가 붙어 타임라인을 식별합니다. 상단 range 토글(1h · 6h · 1d) 로 창을 바꿉니다(기본 1h).

헤더 컨트롤

LIVE 토글 — 30초 폴링 켜기/끄기.
전체화면 버튼 — 상단 네비를 숨기고 body 를 꽉 채웁니다(ESC 로 해제 · fullscreen 믹스인 · body.infr-fs).
높이 슬라이더 2종 — 보드 카드 높이(기본 118px, 90~~240) · 라이브 차트 높이(기본 50px, 34~~160). 전체화면 fit 조절값은 localStorage 에 유지됩니다.

사용법

1) 서비스 고르기

보드 헤더의 [서비스 선택] 또는 [서비스 추가] 를 눌러 선택 모달을 엽니다.
모달은 사용 가능한 전체 서비스를 종류별 그룹(web → database → session → proxy → docker)으로 보여줍니다.
원하는 서비스를 켜고(✓) 끕니다. 선택은 즉시 보드에 반영되고 localStorage 에 저장됩니다.

첫 방문 기본값 = web · database · session 각 종류의 첫 항목이 자동 선택되어 가용성 게이지가 바로 동작합니다. 원치 않으면 모달에서 해제하세요.

2) 우선순위 조정

카드의 드래그 핸들을 잡고 옮기면 순서가 바뀝니다. 맨 앞 web/db/session 카드가 가용성 게이지 대상이 됩니다.

3) 시계열 창 바꾸기

하단 라이브 스트립의 1h / 6h / 1d 버튼으로 range 를 전환합니다. 전환 시 POST /service/series 로 선택 카드 key 들의 대표 지표를 그 창에서 다시 조회하고(다운샘플 최대 60포인트), 응답이 비면 카드 번들 시리즈로 폴백합니다.

// POST /service/series 요청 예시
{ "keys": ["web:12", "db:db@blue", "session:blue"], "range": "6h" }

카드 key 규약:

web:{infr_web_service.id}
db:{infr_collector.key}      예: db@blue
session:{node_alias}         예: blue
proxy:{infr_service.id}
docker:{infr_service.id}

4) 전체화면 상황판

전체화면 버튼 → 높이 슬라이더로 카드·차트 높이를 화면에 맞추면 벽면 모니터용 NOC 보드가 됩니다.

데이터 소스

카드 종류	빌더	실제 테이블
web	`WebMetricService::dashboard()` + `WebProbeService::overlayStatus()`	`infr_web_metric`(vts 카운터) · `infr_web_check`(능동 프로브) · `infr_web_service`
database	`InfrCollector(access=database)` + `DbCollectorService::latest()/series()`	`infr_db_metric` · `infr_collector`
session	`RedisMetricService::dashboard()`	`infr_redis_metric` · `infr_instance`
proxy/docker	`InfrService(kind IN proxy,container)`	`infr_service` · `infr_instance`
KPI 인시던트	—	`infr_incident`(최근 7일)

시계열 원천:

web — infr_web_metric 의 주 도메인·주 노드 request_counter delta → RPS(멀티노드 카운터 혼선 회피).
database — infr_db_metric.qps(저장 지표, 라이브 연결 없음).
session — infr_redis_metric.instantaneous_ops_per_sec.

상태(status) 토큰

토큰	의미
up	정상
degraded	열화
down	중단(실제 연결·프로브 실패)
pending	대기(데이터 지연 등 판정 보류)

DB 카드 false-red 방지 — economy 수집 모드에서 수집이 잠시 밀려 마지막 샘플이 5분 이상 오래되면 statusOf 는 stale 사유로 down 을 냅니다. DB 는 멀쩡한데 빨간 알람이 뜨는 오진이므로, 보드는 stale down 을 pending 으로 강등하고 실제 연결 실패(ok=false)만 down 을 유지합니다. 또한 보드를 보는 present 사용자에게만 마지막 샘플이 45초 이상 밀렸을 때 ensureFresh(45) 로 즉석 1회 샘플을 뜨며(스케줄러가 수집 중이면 연결 없이 no-op), 이 샘플러는 finally 에서 연결을 purge 해 누수를 막습니다.

권한

읽기(보기): 인증된 모든 사용자(demo=1 이상). /service 는 infr.auth 그룹에만 속하고 별도 레벨 게이트가 없습니다.
쓰기 없음: 이 화면은 순수 조회입니다. 카드 선택·순서·높이·range 는 전부 브라우저 localStorage 에만 저장되며 서버에 쓰지 않습니다. 파괴적 작업이 없으므로 감사 로그도 남기지 않습니다.
세부 화면(Web 웹사이트 관리, Database, Catalog 빌드/편집)의 쓰기는 그쪽에서 level≥2 등으로 게이팅됩니다.

localStorage 키:

infr:svcboard:sel:v1        선택 서비스 key 배열(순서=우선순위)
infr:svcboard:h:v1          보드/라이브 높이 슬라이더 값
infr:range:service-overview 하단 시계열 range(1h/6h/1d)

문제해결 · FAQ

보드가 비어 있어요. 헤더 [서비스 추가] 로 관심 서비스를 배치하세요. 사용 가능한 서비스가 하나도 없다면(=수집기가 아직 데이터를 안 채웠다면) 모달 그룹이 비어 보일 수 있습니다 — Collectors 등록과 수집 파이프라인을 먼저 확인하세요.

가용성 게이지가 안 떠요. 게이지는 우선순위 첫 web/db/session 카드가 있어야 그립니다. proxy/docker 만 골랐다면 placeholder 안내가 나옵니다. web/db/session 카드를 하나 이상 앞쪽에 두세요.

하단 시계열이 비어 있어요. 시계열은 web/db/session 카드만 가집니다. proxy/docker 는 제외됩니다. 또한 원천 테이블에 해당 창(1h/6h/1d) 데이터가 없으면 빈 그래프가 됩니다.

DB 카드가 빨간색인데 DB는 멀쩡해요. 데이터 지연이면 pending(회색/대기)으로 강등됩니다. 그래도 down 이면 실제 연결 실패이니 Database 화면과 Collectors의 access=database 수집기 상태를 확인하세요.

새로고침해도 카드가 그대로예요 / 다른 PC에선 다르게 보여요. 선택·순서는 브라우저 localStorage 소유라 서버 계정 설정이 아닙니다. 브라우저·기기마다 독립적입니다.

range 를 5분으로 바꾸고 싶어요. 현재 구현의 range 창은 1h · 6h · 1d 세 가지입니다(기본 1h). 더 짧은 관측이 필요하면 Servers·Database 등 전용 화면을 사용하세요.