서비스 패턴 자동 발견 가이드
네트워크/DB 접속 텔레메트리(netstat, DB 커넥션)에서 실제로 관찰된 애플리케이션·프로세스 목록을 보여주고, 클릭 한 번으로 Normal Service 패턴으로 등록하거나 해제할 수 있는 관리자 화면입니다.
📋 개요
서비스 패턴 자동 발견(Auto-Discovery) 페이지는 giipAgent가 수집한 네트워크 연결(netstat)과 DB 커넥션(db_connections) 텔레메트리에서 실제로 관찰된 프로그램/프로세스 이름을 집계해 보여줍니다. 이미 Normal Service Patterns 페이지에 등록된 패턴인지 여부를 표시하며, 미등록 항목은 버튼 한 번으로 패턴에 추가할 수 있습니다. 이 화면에서 활성화한 패턴은 Network Topology(sql3d) 화면에서 해당 클라이언트를 **Cyan(하늘색)**으로 표시하는 데 쓰입니다.
⚠️ 이 화면은 관리자 전용입니다. 접근하려면 **
uLevel >= 50**이 필요합니다(코드에 직접 지정된 prop 모드 값). 그 미만 사용자는 홈으로 리다이렉트됩니다.
🔍 화면 구성
1. 상단 헤더
- 페이지 제목: "✨ Auto-Discovery: Service Patterns".
- 안내 문구: 발견된 애플리케이션은 실제 인프라의 네트워크/DB 연결에서 왔으며, Enable을 누르면 Normal Service 패턴으로 추가된다는 설명.
2. 명령 바
| 요소 | 설명 |
|---|---|
| 🔄 Refresh 버튼 | 발견 목록을 서버에서 다시 불러옵니다. |
| 검색창 | pattern_value(애플리케이션/프로세스 이름) 기준으로 목록을 실시간 필터링합니다. |
| 📋 Manage Patterns 버튼 | /admin/service-patterns 페이지로 이동해 등록된 패턴을 직접 관리합니다. |
3. 발견 목록 표
| 컬럼 | 설명 |
|---|---|
| Application/Process | 관찰된 프로그램명(program) 또는 프로세스명(process) |
| Type | program(DB 커넥션에서 관찰) 또는 process(netstat에서 관찰) 배지 |
| Seen Count | 관찰된 횟수(occurrence_count) |
| Status | ✅ Pattern(이미 등록됨) 또는 Not enabled(미등록) |
| Action | 미등록이면 Enable, 등록됨이면 Disable 버튼 |
표 하단에 전체 발견 건수와 그중 활성화(등록)된 건수가 표시됩니다.
🛠️ 패턴 활성화/비활성화 방법
- 목록에서 원하는 애플리케이션/프로세스를 찾습니다(검색창으로 좁히기 가능).
- 미등록(Not enabled) 항목이면 Enable 버튼을 클릭합니다 — 현재 프로젝트(csn) 범위의 Normal Service 패턴으로 즉시 추가됩니다.
- 이미 등록됨(✅ Pattern) 항목이면 Disable 버튼을 클릭합니다 — 해당 패턴을 비활성화(soft delete)합니다.
- 처리 중에는 모든 Enable/Disable 버튼이 잠시 비활성화되며, 완료되면 상단에 성공 메시지가 뜨고 목록이 자동으로 새로고침됩니다.
- 조건: Disable은 이 화면에서 등록된(같은 csn 소유) 패턴에만 가능합니다. 글로벌 패턴(csn=0)이나 다른 프로젝트 소유 패턴은 Manage Patterns 페이지의 권한 규칙을 따릅니다.
💡 참고
- 발견 데이터는 최근 30분 이내에 수집된
tKVS(netstat/db_connections) 레코드를 우선 사용합니다. 최근 30분간 수집된 데이터가 전혀 없으면(예: 신규 프로젝트, 에이전트 미설치, 테스트 환경) 시간 제한 없이 가장 최근 50건을 대신 보여줍니다(폴백). - 목록에는
unknown,System,Idle등 의미 없는 값은 제외됩니다. - 발견 목록은 대상 csn에 속한 서버(
tLSvr.CSn)에서 수집된 데이터만 집계합니다. 서버에 giipAgent가 설치되어 netstat/DB 커넥션 텔레메트리를 전송하고 있어야 이 목록에 항목이 나타납니다. - Enable/Disable은 giipfaw(Azure Function) → SQL Server 경유로 즉시 반영되며, 완료 후 목록이 자동 새로고침됩니다.
API 참조
이 페이지는 세 개의 디스패치 커맨드(fetchAzureCommand 경유)로 백엔드와 통신합니다. 별도 API 가이드가 없으므로 핵심을 여기에 기술합니다.
| 커맨드 | 용도 | 주요 파라미터 |
|---|---|---|
Net3dServicePatternDiscovery | tKVS netstat/db_connections에서 발견된 프로그램/프로세스 목록 조회(등록 여부 포함) | csn |
Net3dServicePatternPut | 발견된 항목을 Normal Service 패턴으로 등록(활성화) | csn, nspId(신규는 0), pattern_type, pattern_value, display_name |
Net3dServicePatternDelete | 등록된 패턴을 비활성화(soft delete) | csn, nspId |
- 세 커맨드 모두
RstVal상태 필드를 포함해 응답할 수 있습니다.RstVal = 200은 성공,RstVal = 401은 인증 실패(세션 만료),RstVal = 403은 해당 프로젝트에 대한 권한 없음을 뜻합니다. Net3dServicePatternDiscovery의 정상 응답은pattern_value,pattern_type,occurrence_count,is_registered,nspId필드를 가진 행의 배열입니다. 결과가 1건뿐이면 백엔드(PowerShellConvertTo-Json) 특성상 배열이 아닌 단일 객체로 올 수 있으므로, 클라이언트는 이를 정규화해 처리합니다.
문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| 접속 즉시 홈으로 튕김 | uLevel이 50 미만 | 관리자 계정(레벨 50+)으로 로그인하세요. |
| "Unexpected token '<' ... is not valid JSON" 오류 | (2026-08-07 이전 버전) 프런트가 존재하지 않는 Next.js API 라우트(/api/service-patterns/discovery)를 호출하던 결함 — giip-issue #938에서 fetchAzureCommand 직접 호출로 수정됨 | 최신 배포에서는 발생하지 않습니다. 여전히 보인다면 배포가 최신인지 확인하세요. |
| "Unauthorized" 오류 메시지 | 세션 토큰 만료 또는 없음 | 다시 로그인한 뒤 새로고침을 누르세요. |
| "No applications discovered yet." | 대상 프로젝트(csn) 서버에서 최근 netstat/DB 커넥션 텔레메트리가 수집되지 않음 | 서버에 giipAgent가 설치·실행 중인지 확인하고, 데이터 수집 후 다시 시도하세요. |
| 목록에 새 항목이 안 보임 | 최근 30분 데이터가 없어 폴백(최신 50건)만 표시 중 | 정상 동작입니다. 최근 30분 내 데이터가 쌓이면 그 범위로 전환됩니다. |
| 상단 가이드 버튼(📖)이 안 보임 | 가이드 매핑 누락(구버전 배포) | 이 가이드가 배포·인덱싱되면 표시됩니다. |
버전: 1.0
최종 수정: 2026-08-07
소스 파일: giipv3/public/help/service-patterns-discovery.ko.md