서비스 패턴 자동 발견 가이드

네트워크/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 버튼

표 하단에 전체 발견 건수와 그중 활성화(등록)된 건수가 표시됩니다.

🛠️ 패턴 활성화/비활성화 방법

1. 목록에서 원하는 애플리케이션/프로세스를 찾습니다(검색창으로 좁히기 가능).
2. 미등록(Not enabled) 항목이면 Enable 버튼을 클릭합니다 — 현재 프로젝트(csn) 범위의 Normal Service 패턴으로 즉시 추가됩니다.
3. 이미 등록됨(✅ Pattern) 항목이면 Disable 버튼을 클릭합니다 — 해당 패턴을 비활성화(soft delete)합니다.
4. 처리 중에는 모든 Enable/Disable 버튼이 잠시 비활성화되며, 완료되면 상단에 성공 메시지가 뜨고 목록이 자동으로 새로고침됩니다.
5. 조건: 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건뿐이면 백엔드(PowerShell ConvertTo-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