4.2. 애플리케이션

모니터링 중인 애플리케이션의 전체 목록을 조회하고, 개별 애플리케이션의 상세 관측 데이터를 분석합니다.

개요

애플리케이션 메뉴는 OPENMARU Observability가 모니터링하는 모든 애플리케이션(Application)을 한눈에 보여주는 화면입니다. 애플리케이션은 모니터링의 기본 단위로, Kubernetes 환경에서는 Deployment, StatefulSet, DaemonSet 등의 워크로드가 이에 해당합니다.

각 애플리케이션의 현재 상태와 주요 지표를 빠르게 파악하고, 특정 애플리케이션을 클릭하면 SLO(Service Level Objective, 서비스 수준 목표), CPU, 메모리, 로그(Log), 분산추적, 프로파일링(Profiling) 등 다양한 상세 리포트를 확인할 수 있습니다.

좌측 사이드바에서 애플리케이션 메뉴를 클릭하면 이 화면으로 이동합니다.

---

애플리케이션 목록

화면 구성

목록 화면 상단에는 필터와 뷰 전환 버튼, 상태 범례가 있으며, 아래에 애플리케이션 목록이 표시됩니다.

영역	설명
상단 헤더	페이지 제목, 애플리케이션 필터(네임스페이스, 카테고리, 검색)
뷰 전환 토글	리스트 뷰(List View)와 카드 뷰(Card View) 전환
상태 범례	상태별 애플리케이션 수 표시 및 필터
목록 영역	리스트 뷰: 테이블 형태 / 카드 뷰: 카드 그리드 형태
페이지네이션	페이지당 표시 개수(10, 20, 50, 100, All)와 페이지 이동

상태 범례

화면 상단 툴바의 상태 범례에서는 전체 애플리케이션을 상태별로 요약해 보여줍니다.

상태	의미
SLO 위반	SLO 임계값(Threshold)을 초과한 애플리케이션. 즉각 조치가 필요합니다.
경고	주의가 필요한 경고(Warning) 상태의 애플리케이션
로그에 오류	로그에 오류 패턴이 감지된 애플리케이션
보안 위협	보안 공격 패턴이 탐지된 애플리케이션
통합 필요	에이전트 연결이 되지 않아 데이터가 수집되지 않는 애플리케이션
OK	정상 동작 중인 애플리케이션

상태 범례의 항목을 클릭하면 해당 상태의 애플리케이션만 필터링하여 볼 수 있습니다. 여러 상태를 동시에 선택할 수도 있으며, 선택된 항목은 강조 표시되고 나머지는 흐리게 표시됩니다. 다시 클릭하면 필터가 해제됩니다.

팁: SLO 위반이나 경고 상태의 애플리케이션 수를 먼저 확인하고, 해당 상태를 클릭해 문제가 있는 애플리케이션만 집중적으로 살펴보세요.

---

주요 기능

필터

화면 우측 상단의 필터를 사용해 네임스페이스(Namespace), 카테고리, 애플리케이션 이름으로 목록을 좁힐 수 있습니다. 여러 조건을 조합하여 원하는 애플리케이션만 표시할 수 있습니다.

애플리케이션 숨기기

오설정으로 잠깐 생겼다가 사라진 임시 앱(예: unknown_service)이나 더 이상 보고 싶지 않은 애플리케이션을 전역에서 숨겨(soft hide) 목록·토폴로지 맵의 노이즈를 정리할 수 있습니다. 숨긴 애플리케이션은 삭제되는 것이 아니라 숨긴 애플리케이션 화면에 모여 있으며, 언제든 다시 표시할 수 있습니다.

PM2 로 실행한 Node.js 앱(호스트 모드)

VM 에서 PM2 로 실행한 Node.js 앱은 PM2 앱마다 별도의 애플리케이션으로 나옵니다. PM2 데몬 하나가 여러 앱을 실행해도 앱별로 나뉩니다.

• 애플리케이션 이름은 <systemd 유닛>-<PM2 앱 이름> 형식입니다. 예: pm2-ginet-cu119NEXT
• CPU·메모리 한도는 앱별로 나오지 않습니다. 이 값은 systemd 유닛 단위이므로 PM2 데몬 애플리케이션에만 나옵니다.
• 노드 에이전트 환경 변수 TRACK_PM2_APPS 로 이 기능을 켜고 끕니다. 기본값 auto 는 VM 에서 켜고 Kubernetes 파드에서 끕니다. true·false 로 직접 정할 수도 있습니다.
• 특정 systemd 유닛을 앱별 분리에서 빼려면 PM2_SPLIT_DENYLIST 에 유닛 이름을 넣습니다. 여러 개는 쉼표로 구분합니다. 예: pm2-ginet.service

리스트 뷰

툴바 좌측의 뷰 전환 버튼에서 리스트 아이콘을 클릭하면 리스트 뷰로 전환됩니다. 리스트 뷰는 많은 애플리케이션을 한 번에 비교하기에 적합합니다.

각 열 헤더를 클릭하여 원하는 기준으로 정렬할 수 있으며, 여러 열을 순차적으로 클릭하여 다중 정렬도 가능합니다.

리스트 뷰의 주요 컬럼은 다음과 같습니다.

컬럼	설명
애플리케이션	이름과 네임스페이스. 클릭하면 상세 페이지로 이동합니다.
종류(Kind)	Kubernetes 워크로드 종류 (Deployment, StatefulSet, DaemonSet 등)
유형	애플리케이션 기술 스택 (Java, Python, Redis, Kafka, vLLM 등)
오류	SLO 기준 오류율
응답 시간	SLO 기준 응답 시간. vLLM 애플리케이션은 첫 토큰 시간(TTFT) 기준이며, 셀에 마우스를 올리면 "첫 토큰 시간(TTFT) p95 기준" 툴팁이 나옵니다
업스트림	이 애플리케이션이 호출하는 업스트림(Upstream) 서비스 수
인스턴스	실행 중인 인스턴스(Instance) 수
재시작	인스턴스 재시작 횟수
CPU	CPU 사용률
메모리	메모리 사용량
I/O부하	디스크 I/O 부하
Disk용량	디스크 사용량
네트워크	네트워크 상태
DNS	DNS 쿼리 상태
보안 위협	지금 탐지되고 있는 공격 유형(SQLi·XSS 등)의 수. 방패 아이콘과 함께 표시되고, 클릭하면 상세 화면의 보안 탭으로 이동합니다. 탐지가 없으면 – 로 표시됩니다
로그패턴	최근 로그 오류 패턴 수와 추이 차트

참고: 오류, 응답 시간 등 지표가 빨간색 또는 주황색으로 강조된 경우, 해당 항목이 검사(Inspection) 임계값을 초과했음을 나타냅니다. 해당 값을 클릭하면 관련 상세 탭으로 바로 이동합니다.

카드 뷰

뷰 전환 버튼에서 그리드 아이콘을 클릭하면 카드 뷰로 전환됩니다. 카드 뷰는 각 애플리케이션의 상태와 주요 지표를 카드 형태로 보여줍니다. 각 카드에는 애플리케이션 이름, 상태 아이콘, 주요 메트릭(Metric) 스파크 차트가 표시되며, 카드를 클릭하면 상세 페이지로 이동합니다.

선택한 뷰 방식은 기억되어 다음 방문 시에도 유지됩니다.

카드 뷰에서는 정렬 기준을 선택할 수 있습니다.

정렬 기준	설명
상태	심각 → 경고 → 로그 오류 → 통합 필요 → 정상 순
애플리케이션	이름 알파벳 순
오류	오류 건수 내림차순
응답 시간	응답 시간 내림차순
재시작	재시작 횟수 내림차순
CPU	CPU 사용률 내림차순
메모리	메모리 사용량 내림차순
로그패턴	로그 오류 수 내림차순

카드 뷰 하단에는 페이지 이동 버튼과 페이지당 표시 수 설정(10 / 20 / 50 / 100 / 전체)이 있습니다.

팁: 정렬 기준을 상태로 선택하면 문제가 있는 애플리케이션이 상단에 표시되어 한눈에 파악할 수 있습니다.

---

애플리케이션 상세

목록에서 애플리케이션 이름을 클릭하면 해당 애플리케이션의 상세 페이지로 이동합니다.

화면 구성

상세 페이지는 다음과 같은 영역으로 구성됩니다.

영역	설명
상단 헤더	애플리케이션명, 네임스페이스, 종류(kind), 토폴로지 맵 이동 링크
시간 범위 표시	현재 조회 중인 시간 범위 (최대 3일)
의존성 맵(AppMap)	애플리케이션과 연결된 서비스의 의존성 시각화
리포트 탭	SLO, 인스턴스, CPU, 메모리, 로그 등 탭별 상세 정보
검사 상태	각 리포트별 검사(Inspection) 조건 충족 여부
차트 대시보드	선택한 탭의 메트릭 차트 위젯

상단 헤더에는 다음 정보와 기능이 제공됩니다.

• 애플리케이션 이름: 모니터링 대상의 이름
• ns: 소속 네임스페이스
• kind: Kubernetes 워크로드 종류(kind)
• 토폴로지 맵에서 열기 버튼: 클릭하면 이 애플리케이션이 강조 표시된 토폴로지 맵 화면으로 이동합니다.
• COP Console 에서 열기 버튼(Kubernetes 아이콘): Kubernetes 리소스를 COP Console에서 직접 확인할 수 있는 외부 링크입니다. 이 버튼은 COP Console 주소가 설정되어 있고 종류(kind)가 Deployment·StatefulSet·DaemonSet·Job·CronJob·Pod·ReplicaSet 중 하나일 때만 나옵니다. SystemdService·ExternalService 같은 그 밖의 종류에는 버튼이 없습니다.
• 뒤로 돌아가기: 이전 애플리케이션 목록 화면으로 돌아갑니다.

조회 시간 범위

상세 화면 상단에는 현재 조회 중인 시간 범위가 표시됩니다. 시간 범위가 3일을 초과하면 3일 제한 배지가 표시되며, 자동으로 최근 3일 데이터만 표시됩니다. 배지 위에 마우스를 올리면 실제 조회되는 시간 범위를 확인할 수 있습니다.

선택한 시간 범위 내에 데이터가 없는 경우 안내 다이얼로그가 표시되며, 최근 1시간으로 이동 버튼을 클릭하여 최신 데이터를 확인하거나, 애플리케이션 목록으로 이동 버튼으로 목록 화면으로 돌아갈 수 있습니다.

참고: 상단 바의 시간 선택기에서 전역 시간 범위를 변경하면 상세 페이지의 데이터도 함께 업데이트됩니다.

의존성 맵(AppMap)

상세 화면 상단의 맵 보기 / 맵 숨김 버튼으로 의존성 맵을 켜고 끌 수 있습니다. 의존성 맵은 현재 애플리케이션과 연결된 서비스들의 관계를 시각적으로 보여줍니다.

• 업스트림(Upstream): 현재 애플리케이션이 호출하는 서비스
• 다운스트림(Downstream): 현재 애플리케이션을 호출하는 서비스

의존성 맵의 서비스 노드를 클릭하면 해당 서비스의 상세 정보를 확인하거나 토폴로지 맵에서 볼 수 있습니다.

---

리포트 탭

상세 페이지에서는 여러 리포트 탭이 제공됩니다. 탭 목록은 에이전트가 수집한 데이터 종류에 따라 동적으로 구성됩니다. 각 탭 이름 앞에 표시되는 상태 표시등(LED)으로 해당 리포트의 현재 상태를 빠르게 파악할 수 있습니다.

• 녹색: 정상 상태
• 주황색: 경고 수준의 이상 감지
• 빨간색: 심각한 문제 감지
• 회색: 데이터 없음 또는 미설정

SLO 탭

SLO 탭은 SLO 데이터가 있으면 상세 페이지 진입 시 기본으로 선택되는 탭입니다(요청이 없는 앱 등 SLO 상태를 알 수 없는 경우에는 다른 탭이 기본으로 선택될 수 있습니다). 가용성(Availability)과 응답 시간 목표 대비 현재 성능을 차트로 보여줍니다.

지표	설명
가용성 SLO(Availability)	오류 없이 처리된 요청의 비율과 목표값
응답 시간 SLO(Latency)	목표 응답 시간 이내로 처리된 요청의 비율
오류 예산(Error Budget)	SLO 목표를 유지하면서 허용되는 오류의 한도
오류율 (%) 차트	초당 오류횟수 차트 아래에 오류율(%) 추이가 함께 표시됩니다(오류가 없는 구간은 0% 라인으로 나타납니다)

설정된 임계값(Threshold) 대비 현재 상태를 확인하고, SLO 위반 여부를 파악할 수 있습니다.

응답 시간 히트맵:

SLO 탭의 히트맵은 이 애플리케이션이 받은 요청만 그립니다. SLO 수치와 같은 데이터입니다. 이 애플리케이션이 보낸 호출(DB 쿼리 등)은 분산추적 탭의 발신 요청만 필터로 확인합니다.

칸 하나의 시간 크기는 조회 기간에 따라 정해집니다.

조회 기간	칸 크기
1시간 이하	15초
1시간 초과	1분
6시간 초과	5분
12시간 초과	10분
1일 초과	15분

히트맵에서 영역을 드래그하면 트랜잭션 조회 창이 수신 방향으로 열립니다. 선택 범위는 첫 칸의 시작부터 마지막 칸의 끝까지입니다. 보낸 호출을 보려면 창 위쪽의 발신 버튼을 클릭합니다.

vLLM 애플리케이션의 응답 시간 SLO:

vLLM 추론 서버 애플리케이션은 응답 시간 SLO 를 HTTP 응답 시간이 아니라 첫 토큰 시간(TTFT, Time To First Token) 으로 판정합니다. LLM 요청의 HTTP 응답 시간은 생성한 답의 길이에 따라 길어지기 때문입니다.

• 기본 목표는 "TTFT 2.5초 이하 요청 95%" 입니다. 사용자가 저장한 목표가 있으면 그 값을 씁니다.
• SLO 탭의 응답 시간 차트와 검사 문구는 TTFT 기준임을 표시합니다.
• 조회 구간의 일부만 TTFT 데이터가 있으면 "TTFT 기준 시작: <시각>" 이 나옵니다. 이때도 구간 전체를 TTFT 로 판정합니다.
• SLO 설정 창에서 고를 수 있는 목표 시간은 0.1·0.25·0.5·0.75·1·2.5·5·7.5·10·20초입니다.
• 가용성 SLO 는 다른 애플리케이션과 같이 HTTP 오류(5xx) 비율로 판정합니다.

참고: APM 대시보드는 HTTP 응답 시간을 그대로 씁니다. 그래서 vLLM 애플리케이션이 APM 대시보드에서는 느린 애플리케이션으로 보일 수 있습니다.

인스턴스 탭

이 애플리케이션을 구성하는 개별 인스턴스(Instance=Pod) 목록과 인스턴스 수·재시작 추이를 보여줍니다.

항목	설명
검사	인스턴스 가용성(가용 인스턴스 수 부족), 재시작(컨테이너 재시작 발생) 조건 충족 여부
인스턴스 목록	각 인스턴스(Pod)의 상태(실행/대기 등), 재시작 횟수, IP 주소, 배치된 노드
인스턴스 개수 차트	실제(up)·목표(desired) 인스턴스 수 추이
재시작 횟수 차트	인스턴스별 컨테이너 재시작 누적 횟수

인스턴스 개수 차트에는 배포(Deployment) 마크(세로 점선)가 표시됩니다. 새 버전이 배포되거나 재배포(rollout)되면 해당 시점에 마크가 찍히며, 마크에 마우스를 올리면 배포 유형, 애플리케이션·버전(ReplicaSet·이미지 태그), 배포 시각을 툴팁으로 확인할 수 있습니다. 배포 시점을 인스턴스 수·성능 변화와 나란히 놓고 보면, 특정 배포가 문제를 유발했는지 즉시 판단할 수 있습니다.

또한 인스턴스 개수 차트에는 HPA·CronHPA에 의한 스케일 증가(↑)·감소(↓) 이벤트가 마크로 표시되며, 증감 원인(CPU·메모리 목표 초과 또는 스케줄)을 함께 보여줍니다. 인스턴스 수 변화가 오토스케일링 때문인지, 수동 스케일·재배포 때문인지 구분해 자동 확장 동작을 추적할 수 있습니다.

CPU 탭

애플리케이션의 CPU 사용 패턴을 여러 차트로 제공합니다.

지표	설명
CPU 사용량 (코어)	컨테이너별·인스턴스별 CPU 사용량(코어 단위) 시계열
CPU 대기 시간	실행 준비 상태에서 CPU를 배정받기까지 대기한 시간 — 노드 CPU 경합의 지표
CPU 속도 제한(Throttled) 시간	CPU 상한(limit)에 걸려 실행이 제한된 시간. 값이 크면 CPU limit 상향을 검토
노드 CPU 사용량	이 애플리케이션이 실행되는 노드 전체의 CPU 사용률

검사: 노드 CPU 과부하, 컨테이너 CPU 사용률이 임계값을 초과하면 경고합니다.

메모리 탭

애플리케이션의 메모리 사용 패턴을 여러 차트로 제공합니다.

지표	설명
메모리 사용량(RSS)	컨테이너별 실제 물리 메모리 사용량(RSS) 시계열
노드 메모리 사용량(재확보 불가능:unreclaimable)	실행 노드 전체의 메모리 사용률(재확보 불가 영역 포함)
메모리 점유 프로세스	노드에서 메모리를 많이 사용하는 프로세스 구성(누적 영역 차트)
메모리 부족 이벤트	메모리 부족으로 컨테이너가 강제 종료(OOM Kill)된 횟수

검사: 메모리 부족으로 인한 컨테이너 종료(OOM), 시간당 메모리 사용량 증가율(누수 의심)이 임계값을 초과하면 경고합니다.

로그 탭

이 애플리케이션에서 발생한 로그를 조회합니다.

주요 기능:

• 소스 선택: 로그 수집 소스(컨테이너 로그 / OpenTelemetry 로그 사용)를 선택하여 각 소스별 로그를 확인할 수 있습니다.
• 키워드 검색: 검색 필드에 키워드를 입력하고 조회 버튼을 클릭하여 특정 로그를 찾을 수 있습니다.
• 심각도 필터: Error, Warning, Info 등의 로그 레벨 체크박스로 원하는 심각도의 로그만 표시합니다.
• 로그 패턴 뷰: 유사한 구조의 로그 메시지를 자동으로 그룹화한 로그 패턴(Log Pattern)을 확인할 수 있습니다. 반복되는 오류 패턴을 한눈에 파악하는 데 유용합니다.
• 전체 로그 뷰: 로그 패턴 뷰에서 전체 뷰로 전환하면 개별 로그 메시지를 시간순으로 확인할 수 있습니다.
• 정렬: 최신 순 또는 오래된 순으로 로그 정렬 방식을 전환할 수 있습니다.

CogentAI를 활용한 로그 AI 분석

로그 탭에서는 CogentAI AI 분석 기능을 사용하여 로그 메시지의 의미를 자동으로 분석하고, 오류에 대한 원인 진단 및 해결 방안을 제안받을 수 있습니다.

로그 목록에서 AI 분석 요청하기:

1. 로그 목록에서 분석하려는 로그 행 옆의 CogentAI 아이콘(AI 모양 아이콘)을 클릭합니다.
2. 화면 우측 하단에 CogentAI 위젯이 자동으로 열리며, 해당 로그 메시지가 AI에게 분석 요청으로 전달됩니다.
3. AI가 로그의 의미, 발생 원인, 권장 조치 등을 분석하여 결과를 표시합니다.

로그 상세 다이얼로그에서 AI 분석 요청하기:

1. 로그 목록에서 로그 행을 클릭하여 상세 다이얼로그를 엽니다.
2. 다이얼로그 상단의 CogentAI 인사이트 버튼을 클릭합니다.
3. CogentAI 위젯에서 해당 로그에 대한 더 상세한 분석 결과를 확인할 수 있습니다.

로그 패턴에서 AI 분석 요청하기:

1. 로그 패턴 뷰에서 특정 패턴 카드의 CogentAI 아이콘을 클릭하거나, 패턴 상세 다이얼로그의 CogentAI 인사이트 버튼을 클릭합니다.
2. 해당 로그 패턴에 대한 AI 분석 결과가 위젯에 표시됩니다.

팁: WARN이나 ERROR 레벨의 로그를 CogentAI로 분석하면 문제 해결 절차와 관련 명령어를 포함한 구체적인 안내를 받을 수 있습니다.

CogentAI를 활용한 차트 AI 분석

각 메트릭(Metric) 차트의 우측 상단에도 CogentAI 인사이트 아이콘이 있습니다. 이 아이콘을 클릭하면 해당 차트의 데이터를 AI가 분석하여 이상 패턴 설명, 추세 해석, 권장 조치 등의 인사이트를 제공합니다.

1. 분석하려는 메트릭 차트 우측 상단의 CogentAI 인사이트 아이콘(AI 모양 아이콘)을 클릭합니다.
2. CogentAI 위젯이 열리며, 해당 차트의 메트릭 데이터가 분석 요청으로 전달됩니다.
3. AI가 차트 데이터를 해석하여 인사이트를 제공합니다.
4. 위젯에서 후속 질문을 입력하여 추가 분석을 요청할 수 있습니다.

참고: CogentAI 기능은 관리자가 CogentAI 위젯을 활성화한 경우에만 사용할 수 있습니다.

배포 탭

이 애플리케이션의 배포(Deployment) 이력을 표로 보여줍니다. 각 배포 시점 전후의 메트릭 변화를 자동으로 요약하여, 어떤 배포가 성능·안정성에 영향을 줬는지 한눈에 파악할 수 있습니다.

표는 다음 컬럼으로 구성됩니다.

컬럼	설명
배포명	배포된 버전(ReplicaSet 해시·이미지 태그)과 해당 버전의 수명(다음 배포까지 유지된 시간)
배포 시간	배포가 감지된 시각
배포된 시간	현재로부터 경과한 시간(예: "3시간 전")
요약	이전 배포 대비 가용성·CPU·메모리·로그 오류 등의 변화율을 자동 요약. 개선은 초록색, 악화는 빨간색으로 표시

검사: 롤아웃 진행 시간이 임계값을 초과하면(배포가 오래 완료되지 않으면) 경고합니다.

팁: 요약의 각 항목 옆 아이콘을 클릭하면 해당 지표의 배포 전후 차트로 이동해 상세 변화를 확인할 수 있습니다. 예를 들어 "CPU 사용량: 이전 배포에 비해 8.3% 달라짐"은 이번 배포로 CPU 사용량이 증가했음을 뜻합니다.

프로파일링 탭

프로파일링 탭에서는 애플리케이션의 CPU 및 메모리 사용 패턴을 플레임 그래프(Flame Graph)로 시각화합니다. 플레임 그래프는 함수 호출 스택과 소요 시간을 시각화하는 차트입니다.

주요 기능:

• 상태 표시: 프로파일링 데이터 수집 상태가 상단에 OK / WARN / CRIT로 표시됩니다.
• 프로파일 타입 선택: CPU 또는 메모리 등 분석하려는 프로파일 타입 버튼을 클릭하여 전환합니다.
• 시계열 차트: 시간별 프로파일 데이터 추이를 표시합니다. 차트에서 특정 시간 영역을 드래그하여 선택하면 해당 구간의 플레임 그래프가 표시되며, 이전 기간과 비교할 수 있습니다.
• 플레임 그래프: 블록의 너비가 넓을수록 해당 함수가 더 많은 리소스를 사용하고 있음을 의미합니다. 블록을 클릭하면 확대하여 하위 호출 스택을 상세히 확인할 수 있습니다.
• 인스턴스 선택: 특정 인스턴스의 프로파일만 선택하여 비교할 수 있습니다.

팁: 프로파일 차트에서 시간 구간을 드래그하여 선택하면 해당 구간의 플레임 그래프를 확인할 수 있을 뿐만 아니라, 이전 동일 길이 기간과의 비교 분석도 가능합니다.

Go 애플리케이션 프로파일링 연동 (pprof)

프로파일링 데이터는 두 경로로 수집됩니다.

• eBPF 연속 프로파일링(자동): 노드 에이전트가 코드 수정 없이 CPU 프로파일을 상시 수집합니다(유형 선택기의 CPU (eBPF)).
• pprof 스크레이프(Go, 어노테이션): Go 애플리케이션이 노출하는 /debug/pprof 를 클러스터 에이전트가 수집합니다. CPU뿐 아니라 메모리(heap)·고루틴·mutex·block 프로파일까지 제공합니다.

Go 애플리케이션에 pprof 프로파일링을 연동하려면, 앱이 net/http/pprof 를 노출한 상태에서 Pod 에 아래 어노테이션을 추가합니다.

# Pod 템플릿(spec.template.metadata.annotations)
openmaru.io/profile-scrape: "true"   # 프로파일 수집 활성화(별칭 pyroscope.io/scrape)
openmaru.io/profile-port: "6060"     # pprof 가 리스닝하는 포트(별칭 pyroscope.io/port)

클러스터 에이전트가 /debug/pprof/ 에서 다음 5종을 수집합니다.

유형	pprof 경로	내용
CPU	profile	CPU 사용 프로파일
메모리	heap	힙 할당(alloc)·사용중(inuse) 객체·크기
고루틴	goroutine	고루틴 스택
Mutex	mutex	락 경합
Block	block	블로킹 지점

참고: mutex·block 프로파일은 Go 기본값이 비활성이라, 앱에서 runtime.SetMutexProfileFraction(n>0)·runtime.SetBlockProfileRate(n>0) 로 켜야 수집됩니다. pprof 를 노출하지 않는 앱(예: 기본 otel-demo Go 서비스)은 이 방식으로 수집되지 않습니다. 5종을 모두 방출하는 예제는 test/go-pprof-demo/ 샘플을 참고하세요.

---

분산추적 탭

분산추적 탭에서는 이 애플리케이션과 관련된 추적(Trace) 데이터를 히트맵(Heatmap)과 추적 목록으로 분석합니다. 추적(Trace)은 분산 시스템에서 하나의 요청이 여러 서비스를 거치는 경로를 기록한 데이터입니다. 히트맵에서 관심 영역을 선택하고, 추적 목록에서 개별 추적을 확인한 뒤, 스팬(Span) 폭포수 차트로 상세 호출 흐름까지 드릴다운하는 전체 워크플로를 제공합니다.

1단계: 추적 상태 확인 및 소스 선택

분산추적 탭에 진입하면 상단에 추적 데이터의 수집 상태가 표시됩니다.

• 상태 표시: OK(정상 수집), WARN(경고), CRIT(심각) 중 하나가 배지로 표시되며, 상태 메시지로 현재 상황을 파악할 수 있습니다.
• 소스 전환: 에이전트가 여러 소스를 지원하는 경우, 소스 전환 버튼이 표시됩니다.
  • agent: eBPF 기반 자동 추적 데이터. 코드 수정 없이 자동으로 수집됩니다.
  • otel: OpenTelemetry SDK 기반 추적 데이터. 더 세밀한 스팬(Span) 정보를 제공합니다.
• 연결 설정: 상태 영역의 설정(톱니바퀴) 아이콘을 클릭하면 이 애플리케이션과 OpenTelemetry 서비스를 연결하는 설정 다이얼로그가 열립니다.

2단계: 필터로 추적 범위 좁히기

히트맵 위에 필터 토글 버튼이 두 묶음 있습니다. 첫째 묶음은 추적의 종류를 고릅니다.

필터	설명
오류 추적 보기	오류가 발생한 추적만 히트맵에 표시합니다
응답 시간 SLO 위반 보기	응답 시간 SLO 임계값을 초과한 추적만 표시합니다
모든 추적 보기	전체 추적 데이터를 표시합니다

필터 버튼을 클릭하면 활성화되며, 히트맵과 하단의 추적 목록이 해당 조건에 맞게 갱신됩니다.

둘째 묶음은 요청의 방향을 고릅니다. 방향 필터는 첫째 묶음의 필터와 함께 적용됩니다.

필터	설명
수신·발신 전체	수신 요청과 발신 요청을 모두 표시합니다. 기본 상태입니다
수신 요청만	이 애플리케이션으로 들어오는 요청의 추적만 표시합니다
발신 요청만	이 애플리케이션에서 다른 서비스로 나가는 요청의 추적만 표시합니다

선택된 수신 요청만 또는 발신 요청만을 다시 클릭하면 수신·발신 전체로 돌아갑니다. 그 방향의 추적이 없으면 버튼이 비활성화되고, 마우스를 올리면 "이 애플리케이션의 수신 요청 추적이 없습니다" 같은 툴팁이 나옵니다.

팁: 오류가 급증한 시점을 분석할 때는 먼저 오류 추적 보기 필터를 활성화하면, 오류와 관련된 추적만 집중적으로 확인할 수 있습니다.

3단계: 히트맵에서 관심 영역 선택

히트맵은 시간(X축)과 응답 시간(Y축)의 분포를 색상 밀도로 시각화합니다. 색상이 진할수록 해당 시간대에 해당 응답 시간 범위의 요청이 많이 발생했음을 의미합니다.

히트맵에서 영역을 선택하는 방법:

1. 히트맵에서 조사하려는 영역을 마우스로 클릭한 채로 드래그합니다.
2. 트랜잭션 조회 창이 열립니다. 창 위쪽 목록에 선택한 시간 범위와 응답 시간 범위의 요청이 나옵니다. 방향은 2단계에서 고른 방향 필터를 따릅니다.
3. 목록에서 행을 클릭합니다. 창 아래쪽에 그 요청의 스팬 트리가 나옵니다.
4. 다른 영역을 보려면 창을 닫고 다른 영역을 드래그합니다.

드래그해도 하단의 추적 목록은 바뀌지 않습니다. 추적 목록의 범위는 2단계의 필터 버튼으로 정합니다.

히트맵 읽는 법:

• 점이 위쪽에 집중되어 있으면, 응답 시간이 긴 요청이 많다는 뜻입니다.
• 특정 시간대에 붉은 점이 나타나면, 그 시점에 오류가 발생했음을 나타냅니다.
• 정상적인 상태에서는 대부분의 점이 **아래쪽(낮은 응답 시간)**에 집중됩니다.

팁: 응답 시간이 갑자기 높아진 영역(히트맵 상단에 점이 집중된 구간)을 드래그하면, 트랜잭션 조회 창에서 그 구간의 요청만 확인할 수 있습니다.

4단계: 추적 목록에서 개별 추적 확인

히트맵 아래에 추적 목록이 테이블로 표시됩니다. 히트맵에서 영역을 선택했다면 해당 범위의 추적만 표시됩니다.

컬럼	설명
추적 ID	추적의 고유 식별자 (앞 8자리 표시). 클릭하면 스팬 상세 다이얼로그가 열립니다.
시작 시간	추적이 시작된 시각
방향	인바운드(외부에서 이 애플리케이션으로 들어오는 요청) 또는 아웃바운드(이 애플리케이션에서 외부로 나가는 요청)
클라이언트	요청을 보낸 서비스 이름
상태	정상(OK) 또는 오류(Error) 상태와 상태 메시지
응답시간	추적의 전체 소요 시간 (밀리초)
HTTP 메소드	요청의 HTTP 메소드 또는 오퍼레이션 이름. 클릭하면 스팬 상세 다이얼로그가 열립니다.
상세정보	요청 URL이나 쿼리 등 상세 내용. 복사 버튼으로 클립보드에 복사할 수 있습니다.

테이블의 각 열 헤더를 클릭하여 정렬할 수 있으며, 다중 정렬도 지원됩니다. 테이블 하단에서 페이지당 표시 건수를 조절할 수 있습니다.

참고: 조회 결과가 많을 경우 최대 건수 제한 안내 메시지가 표시될 수 있습니다. 히트맵에서 좀 더 좁은 범위를 선택하거나 필터를 추가하여 범위를 줄이세요.

5단계: 스팬 폭포수 차트로 상세 흐름 분석

추적 목록에서 추적 ID 또는 HTTP 메소드를 클릭하면 해당 추적의 스팬 폭포수 차트가 다이얼로그로 열립니다. 스팬(Span)은 분산추적에서 단일 작업 단위를 나타냅니다.

다이얼로그 상단 정보:

다이얼로그 상단에는 다음 정보가 표시됩니다.

• 추적: 전체 추적 ID와 복사 버튼
• 클라이언트: 요청을 보낸 서비스 이름
• 상태: 상태 메시지 배지. 정상이면 녹색 체크 아이콘, 오류이면 빨간색 경고 아이콘과 함께 OK, HTTP-500, ERROR 같은 메시지가 표시됩니다
• 응답 시간: 전체 추적의 소요 시간 (밀리초)

스팬 폭포수 차트 읽는 법:

스팬 폭포수 차트는 요청이 각 서비스를 거치는 순서와 소요 시간을 시각적으로 보여줍니다.

• 가로 막대의 시작 위치는 스팬이 시작된 시점, 길이는 해당 스팬의 소요 시간을 나타냅니다.
• 각 스팬의 서비스 이름은 고유한 색상으로 구분됩니다.
• 자식 스팬은 들여쓰기로 계층 구조를 표현합니다. 상위 스팬의 이름을 클릭하면 하위 스팬을 접거나 펼칠 수 있습니다.
• 오류가 발생한 스팬에는 오류 아이콘이 표시됩니다.
• 분산추적 탭에서 연 추적은 클릭한 스팬부터 보여 줍니다. 그 스팬이 루트가 아니면 상위 추적 보기 버튼으로 전체 추적을 봅니다. 다시 선택한 스팬부터 보기 버튼을 클릭하면 처음 화면으로 돌아갑니다.
• 루트 스팬부터 연 추적에는 주요 단계만 보기 버튼이 있습니다. 이 버튼은 루트 바로 아래 단계만 남기고 그 아래 스팬을 접습니다. 모두 펴기 버튼을 클릭하면 모든 스팬을 다시 펼칩니다. 자식이 있는 스팬이 없으면 이 버튼은 나오지 않습니다.

스팬 상세 정보:

스팬을 클릭하면 해당 스팬의 상세 정보가 표시됩니다.

항목	설명
이름	스팬의 오퍼레이션 이름
서비스	스팬이 속한 서비스 이름
시작 시간	스팬 시작 시각
응답시간	스팬 소요 시간 (밀리초)
상태	정상(OK) 또는 오류(Error) 및 메시지
스팬 ID	스팬의 고유 식별자 (복사 가능)
속성	스팬에 첨부된 속성 목록 (HTTP URL, DB 쿼리 등)
이벤트	스팬 실행 중 발생한 이벤트 (예: 예외 스택 정보)

스팬 유형은 배지로 표시됩니다. (HTTP, gRPC, Kafka, Redis, MongoDB, PostgreSQL, MySQL 등)

분산추적 활용 시나리오

다음은 분산추적 탭을 활용하여 문제를 분석하는 대표적인 시나리오입니다.

느린 요청 찾기:

1. 오류 추적 보기 필터를 끄고 모든 추적 보기를 활성화합니다.
2. 히트맵에서 응답 시간이 높은 영역(상단 부분)을 드래그합니다. 트랜잭션 조회 창이 열립니다.
3. 창의 목록은 처음에 응답 시간이 긴 순서로 나옵니다. 다른 순서로 바꾸었으면 응답시간 열 머리글을 클릭하여 다시 정렬합니다.
4. 응답 시간이 가장 긴 행을 클릭하여 창 아래쪽의 스팬 트리를 확인합니다.
5. 가장 긴 가로 막대를 가진 스팬을 클릭하여 어떤 서비스, 어떤 작업에서 병목이 발생했는지 확인합니다.

오류 추적 분석:

1. 오류 추적 보기 필터를 활성화합니다.
2. 히트맵에서 오류가 집중된 시간대를 드래그합니다. 트랜잭션 조회 창이 열립니다.
3. 창 위쪽의 오류만 버튼을 클릭하고, 오류 상태의 행을 클릭합니다.
4. 창 아래쪽 스팬 트리에서 오류 아이콘이 표시된 스팬을 찾아 클릭합니다.
5. 스팬 상세의 이벤트 항목에서 예외 스택 정보를 확인하여 오류 원인을 파악합니다.

분산추적 전체 분석 흐름 요약

다음은 애플리케이션 상세의 분산추적 탭에서 문제를 분석하는 전체 흐름입니다.

1. 상태 확인: 상단의 상태 배지에서 추적 데이터 수집 상태를 확인합니다.
2. 소스 선택: agent(eBPF) 또는 otel(OpenTelemetry) 중 분석할 소스를 선택합니다.
3. 필터 적용: 오류 추적, SLO 위반 등 필요한 필터를 활성화하여 범위를 좁힙니다.
4. 히트맵 영역 선택: 히트맵에서 응답 시간이 높거나 오류가 발생한 영역을 드래그합니다. 트랜잭션 조회 창이 열립니다.
5. 요청 목록 확인: 창의 목록에서 응답 시간이 긴 요청이나 오류 상태의 요청을 찾습니다.
6. 스팬 트리 분석: 행을 클릭하여 창 아래쪽 스팬 트리에서 어느 서비스, 어느 스팬에서 시간이 많이 소요되었는지 또는 오류가 발생했는지 확인합니다.
7. 스팬 상세 확인: 문제가 되는 스팬을 클릭하여 HTTP URL, DB 쿼리, 오류 메시지 등 상세 속성을 확인합니다.

팁: 전체 분산추적을 분석하려면 사이드바의 분산추적 메뉴를 이용하세요. 애플리케이션 상세의 분산추적 탭은 해당 애플리케이션에 관련된 추적만 표시합니다.

---

도메인네임 탭

이 애플리케이션이 발생시킨 DNS 조회 지표를 제공합니다.

지표	설명
DNS 응답 시간 (초)	도메인 조회에 걸린 평균 응답 시간
DNS 오류 (초당)	실패(NXDOMAIN·SERVFAIL 등)한 초당 조회 수
DNS 요청 유형별 (초당)·도메인 표	조회한 레코드 유형(A/AAAA/CNAME 등)과 대상 도메인별 요청량

DNS 지연·오류는 외부 서비스 연동 지연이나 서비스 디스커버리 장애의 조기 신호가 됩니다.

네트워크 탭

이 애플리케이션의 업스트림·다운스트림 연결에 대한 L4(TCP) 네트워크 지표를 제공합니다.

지표	설명
네트워크 라운드트립 시간(RTT)	상대 서비스와의 왕복 지연 시간
TCP 연결 대기 시간	새 TCP 연결 수립에 걸린 시간
활성 TCP 연결수	현재 유지 중인 연결 수
TCP 연결 시도 횟수 (초당) / 실패한 TCP 연결수 (초당)	초당 연결 시도 수와 실패한 연결 수 — 실패 급증은 대상 서비스 장애 신호
트래픽	수신(inbound)·송신(outbound) 대역폭
TCP 재전송 (세그먼트/초)	패킷 손실로 인한 재전송량 — 네트워크 품질 저하 지표
DB 연결 사용률	DB 목적지마다 '동시에 처리 중인 평균 질의 수 ÷ 열린 TCP 연결 수' 입니다. 제목 옆 선택 메뉴에서 사용률, 동시 질의 수, 열린 연결 수 를 고릅니다. DB 목적지가 있는 앱에서만 나옵니다

DB 연결 사용률 읽는 방법:

동시 질의 수는 질의 처리 시간 합의 초당 증가율입니다(초당 질의 수 × 평균 처리 시간). 서버가 이미 가진 값으로 계산하므로 앱과 node-agent 를 바꾸지 않습니다. 대상 프로토콜은 PostgreSQL, MySQL, MongoDB, Redis, Memcached, Kafka, Cassandra, ClickHouse, ZooKeeper 입니다.

• PostgreSQL·MySQL 처럼 한 연결에서 질의를 하나씩 처리하는 프로토콜은 값이 1 에 가까우면 연결이 모자랄 수 있습니다.
• Redis·MongoDB·Kafka 처럼 한 연결에 여러 요청을 함께 보내는 프로토콜은 값이 1 을 넘을 수 있습니다. 이때 1 초과는 연결 부족을 뜻하지 않습니다.
• 열린 연결 수에는 연결 풀 밖의 연결과, 같은 앱이 그 목적지의 다른 포트로 연 연결도 들어갑니다.
• TLS 로 암호화된 연결은 질의 처리 시간을 읽지 못해 값이 없을 수 있습니다.
• 열린 연결이 0 인 구간은 값을 비웁니다.
• 연결 풀의 최대 크기와 연결을 기다린 시간은 앱 안에서만 보입니다. 이 차트로는 알 수 없습니다.

DB 연결 사용률 검사:

PostgreSQL·MySQL 목적지가 있는 앱에는 DB 연결 사용률 검사가 나옵니다. 목적지마다 사용률의 마지막 값이 기준값(기본 90%)을 넘으면 경고합니다. 기본 알림 규칙 DB 연결 사용률 높음 이 이 검사를 씁니다.

• Redis 처럼 한 연결에 여러 요청을 보내는 프로토콜은 검사에 넣지 않습니다. 차트에는 그대로 나옵니다.
• 이 검사는 앱 쪽에서 본 연결 사용률입니다. PostgreSQL·MySQL 탭의 연결 수 검사는 DB 서버 쪽 연결 수를 max_connections 와 비교합니다. 두 검사는 서로 다른 값을 봅니다.
• 최근 1시간에 PostgreSQL·MySQL 사용률 값이 없으면 검사가 나오지 않습니다.

연결에 실패한 대상 확인:

TCP 연결 검사가 경고 상태이면, 검사 상태 영역에 연결에 실패한 대상이 한 줄로 나옵니다. 대상 이름을 3개까지 보여 주고, 나머지는 "외 N개" 로 표시합니다. 예: rke2-canal, cloud-controller-manager, etcd 외 3개

대상의 실제 주소는 실패한 TCP 연결수 (초당) 차트의 범례에서 확인합니다. 이 주소는 이 차트의 범례에만 나옵니다.

실패한 연결이 모두 IPv6 루프백 주소([::1])이고 같은 포트의 IPv4 연결은 성공했다면, 정보 아이콘과 함께 다음 안내가 나옵니다.

실패한 연결이 모두 IPv6 루프백 주소이고, 같은 포트의 IPv4 로는 성공했습니다. localhost 가 IPv6 로 먼저 해석돼 생기는 이름 해석 순서 문제이며 장애가 아닐 가능성이 높습니다.

이 안내는 검사 상태를 바꾸지 않습니다. 검사는 경고 상태로 남으므로, 안내를 읽고 장애인지 직접 판단합니다.

보안 탭

이 애플리케이션을 대상으로 탐지된 HTTP 침입·공격 시도를 보여줍니다. 노드 에이전트가 eBPF L7 트래픽에서 SQL 인젝션·XSS·경로 순회(Path Traversal)·원격 코드 실행(RCE)·스캐너 등 공격 패턴을 탐지하여, 공격 유형·심각도·출처(IP)와 함께 표시합니다.

항목	설명
검사	트래픽 급증(요청률이 평소의 N배), 브루트포스(401/403 응답 비율), 에러율 급증(5xx), 보안 패턴 탐지(공격 이벤트 수)
보안 이벤트 (초당)	유형별(SQLi·XSS·RCE·경로 순회 등) 초당 탐지 건수 — 위 예시는 공격이 없는 정상 상태로, 공격이 탐지되면 유형별 색상으로 채워집니다
요청률 (초당)	초당 전체 요청 수(total)와 초당 실패한 요청 수(errors)
인증 실패 비율 (401/403)	전체 요청 중 401·403 응답의 비율(%). 브루트포스 검사를 판단할 때 함께 봅니다

이 탭은 개별 애플리케이션 관점의 보안 이벤트를 보여줍니다. 전체 클러스터 관점의 실시간 위협 현황, 공격 출처 국가별 분포, 보안위협 보고서는 보안공격 탐지 화면을 참고하세요.

데이터베이스 / 미들웨어 탭

데이터베이스·캐시 유형이 감지되면 전용 리포트 탭이 추가됩니다. eBPF L7 트래픽으로 수집되는 기본 지표(쿼리 응답시간·처리량·에러율)는 설치만으로 표시되며, 뒤의 데이터베이스 모니터링 연동 추가 설정을 마치면 아래의 DB 내부 지표까지 함께 표시됩니다.

PostgreSQL 탭

지표	설명
Postgres 평균 쿼리 응답시간	평균 쿼리 응답 시간
초당 쿼리수	처리량
Postgres 연결수	상태별 연결 수
유휴 트랜잭션	열린 채 유휴 상태인 트랜잭션 수
잠긴 쿼리	잠금 대기 중인 쿼리
대기 쿼리 수별 차단 쿼리	다른 쿼리를 대기시키는 쿼리(대기 쿼리 수 기준 정렬)
총 소요시간별 쿼리	누적 실행 시간이 큰 쿼리
I/O 시간별 쿼리	디스크 I/O 시간이 큰 쿼리
복제 지연 (바이트)	복제본과의 지연(바이트)

검사: 가용성 · 쿼리 지연 · 복제 지연 · 연결 수 임계값 초과 시 경고합니다.

MySQL 탭

지표	설명
쿼리수 (초당)	처리량
평균 응답시간	평균 쿼리 응답 시간
총 소요시간별 쿼리	누적 실행 시간이 큰 쿼리
테이블별 I/O 시간	테이블별 디스크 I/O 소요 시간
트래픽	초당 송신/수신 바이트(read/write)
초당 슬로우 쿼리수	초당 슬로우 쿼리 수
연결수	상태별 연결 수
초당 신규 연결수	초당 새로 생성된 연결 수
복제 지연 (초)	복제본과의 지연(초)

MariaDB 등 MySQL 호환 데이터베이스에도 동일하게 적용됩니다.

검사: 가용성 · 복제 상태 · 복제 지연 · 연결 수 임계값 초과 시 경고합니다.

Redis 탭

지표	설명
Redis 평균 응답 시간	평균 명령 응답 시간
Redis 쿼리수	명령(GET·SET 등) 유형별 초당 처리량

KeyDB·Valkey·Dragonfly 등 Redis 호환 캐시에도 동일하게 적용됩니다.

검사: 가용성 · 지연시간 임계값 초과 시 경고합니다.

MongoDB 탭

지표	설명
쿼리수 (초당)	처리량
평균 응답시간	평균 쿼리 응답 시간
복제 지연 (초)	복제본(replica set)과의 지연(초)

검사: 가용성 · 복제 지연 임계값 초과 시 경고합니다.

Memcached 탭

지표	설명
Memcached 명령수	명령(get·set 등) 유형별 초당 처리량
적중률 (%)	캐시 조회 성공 비율(%)
제거된 항목 (초당)	메모리 부족으로 축출(evict)된 초당 항목 수

검사: 가용성 이상 시 경고합니다.

참고: 전용 데이터베이스 탭은 PostgreSQL·MySQL·Redis·MongoDB·Memcached 유형에만 생성됩니다. Cassandra·Elasticsearch·Kafka 등 그 외 데이터스토어는 별도 전용 탭이 만들어지지 않으며, eBPF L7 트래픽 기반 지표(응답시간·처리량·에러)는 SLO 탭 등 일반 요청 차트에서 확인할 수 있습니다.

런타임 탭

애플리케이션의 기술 스택(런타임)이 감지되면 런타임 전용 리포트 탭이 추가되어 런타임 내부 지표를 보여줍니다. 이 탭은 에이전트의 런타임 자동 감지 또는 OpenTelemetry 계측으로 활성화됩니다.

JVM 탭 — Java 애플리케이션

지표	설명
힙 메모리 크기	힙 메모리 사용량(used)과 상한(total). used가 total에 근접하면 OutOfMemory 위험
가비지 컬렉션 시간	가비지 컬렉션 소비 시간(초/초). GC 유형별로 구분
JVM 중단 시간	모든 스레드를 멈추는 세이프포인트 시간. 길면 애플리케이션 정지(STW) 지연 발생
메타스페이스	클래스 메타데이터 영역 크기
활성 스레드	live · daemon · peak 스레드 수
시작된 스레드	초당 새로 생성된 스레드 수
락 경합	초당 스레드 락 경합 횟수
로딩된 클래스	로드된 클래스 수

검사: JVM 가용성 · 세이프포인트 시간이 임계값을 초과하면 경고합니다.

.NET 탭

지표	설명
힙 메모리 크기	세대(Gen)별 힙 크기(누적)
가비지 컬렉션(GC)	초당 가비지 컬렉션 횟수
메모리 할당률	메모리 할당량
예외 발생 횟수	초당 예외 발생 수
힙 조각화	힙 단편화 비율(%)
스레드 풀 큐 크기	스레드풀 대기 큐 크기
스레드 풀 크기	스레드풀 스레드 수
스레드 풀 완료 작업 수	초당 처리 완료된 작업 항목 수
모니터 잠금 경합	모니터 락 경합 횟수

검사: .NET 가용성을 확인합니다.

파이썬 탭

지표	설명
GIL 대기 시간	Python 스레드가 GIL(Global Interpreter Lock)을 얻으려고 기다린 시간의 합(초/초)입니다. 메인 인터프리터의 GIL 만 잽니다. 스레드별 대기를 더하므로 GIL 을 다투는 스레드가 많으면 1초/초를 넘을 수 있습니다. 값이 높으면 CPU 를 쓰는 스레드끼리 GIL 을 다투고 있어 병렬 처리 성능이 떨어집니다
Python 프로세스 수	컨테이너 안 Python 프로세스 수입니다. 마스터·워커와 multiprocessing 보조 프로세스(resource_tracker 등)를 모두 셉니다. 평소보다 줄었으면 워커가 죽은 채 다시 뜨지 않은 것입니다
Python 프로세스 종료 (60초 이상 산 것, 분당)	60초 넘게 실행되던 Python 프로세스가 끝난 횟수(분당)입니다. 헬스체크처럼 수 초 사는 프로세스는 세지 않습니다. gunicorn max_requests 의 주기적 워커 교체, 재배포, 컨테이너 재시작으로도 늘어납니다
Python 스레드 수	Python 프로세스의 스레드 수 합입니다. 부하가 일정한데 계속 늘면 스레드 누수를 의심합니다. torch·CUDA 같은 네이티브 라이브러리의 스레드도 포함됩니다
Python 열린 파일 수(fd)	Python 프로세스가 연 파일 디스크립터(파일·소켓·파이프) 수의 합입니다. 부하가 일정한데 계속 늘면 파일·연결을 닫지 않는 누수를 의심합니다
Python GC 실행 횟수 (초당)	Python GC(가비지 컬렉션)가 초당 실행된 횟수입니다. 객체를 많이 만들고 버리는 앱은 초당 수백 번 실행될 수 있습니다. 횟수만으로 판단하지 말고 멈춤 시간을 함께 봅니다
Python GC 멈춤 시간 (초/초)	GC 실행 시간의 합(초/초)입니다. 0.01 은 1초 가운데 10ms 동안 GC 가 실행되었다는 뜻입니다. 컨테이너 안 프로세스의 값을 더하므로 1 을 넘을 수 있습니다
Python 가장 긴 GC 멈춤 (초)	가장 오래 걸린 GC 한 번의 실행 시간입니다. 이 값이 요청 응답 시간 목표에 가까우면 GC 가 응답 지연의 원인일 수 있습니다
Python 이벤트 루프 최장 실행 시간 (초)	asyncio·uvloop 같은 이벤트 루프가 쉬지 않고 콜백을 실행한 가장 긴 시간입니다. 그동안 다른 요청은 처리되지 않습니다. 값이 요청 응답 시간 목표에 가까우면 루프를 막는 코드(동기 I/O, 긴 계산)를 의심합니다

검사: GIL 대기 시간이 임계값을 초과하면 경고합니다. 이벤트 루프·GC 값이 있으면 아래 검사 3개도 나옵니다.

검사 항목	조건(기본 기준값)	기본 알림 규칙
Python 이벤트 루프 막힘	최근 5분 이벤트 루프 최장 실행 시간의 최댓값 > 2초	Python 이벤트 루프 오래 막힘 (경보 대기 1분)
Python GC 최장 멈춤	최근 5분 가장 긴 GC 멈춤의 최댓값 > 0.5초	Python GC 오래 멈춤 (경보 대기 1분)
Python GC 시간 비율	최근 5분 동안 프로세스당 GC 시간 비율의 평균 > 5%	Python GC 시간 비율 높음 (경보 대기 5분)

• 이벤트 루프와 가장 긴 GC 멈춤은 최근 5분의 최댓값으로 판정합니다. 그래서 한 번의 긴 막힘도 알립니다. 막힘이 없어지고 5분이 지나면 검사는 정상으로 돌아갑니다.
• GC 시간 비율은 점마다 GC 멈춤 시간(초/초)을 Python 프로세스 수로 나눈 값입니다. 워커 하나만 GC 시간이 길면 평균에 묻힐 수 있습니다. 예를 들어 워커 8개 가운데 1개만 20% 이면 평균은 2.5% 입니다.
• 이벤트 루프 경고 문구에는 같은 5분의 가장 긴 GC 멈춤 값을 함께 적습니다. 예: (GC 최장 멈춤 1.10초). 두 값이 같으면 GC 가 루프를 막았다고 볼 수 있습니다.
• 이벤트 루프를 쓰지 않는 앱에서 이벤트 루프 경고가 나면, 그 앱의 검사 기준값을 크게 올려 경고를 끕니다. 검사 항목의 톱니바퀴 아이콘을 클릭하면 애플리케이션 수준 기준값을 바꿀 수 있습니다.
• 최근 1시간에 값이 없으면 그 검사는 나오지 않습니다. 이벤트 루프 지표가 없는 앱에는 이벤트 루프 검사가 나오지 않습니다.

참고: 프로세스 수·종료·스레드·열린 파일 수와 Python 버전은 앱을 고치지 않고 node-agent 가 /proc 과 실행 파일에서 읽습니다. 스레드·열린 파일 수는 15초마다 갱신됩니다. 60초 넘게 산 Python 프로세스가 있는 앱에서만 표시됩니다. 버전은 Python 3.11 이상이면 3.12.3 처럼, 3.10 이하이면 3.10 처럼 표시됩니다. 이 지표에는 검사(경고)가 없습니다.

참고: Python 의 GC 는 GIL 을 가진 채로 실행됩니다. 그래서 GC 가 도는 동안 같은 프로세스의 다른 Python 스레드는 멈춥니다. node-agent 는 앱을 고치지 않고 eBPF 로 GC 를 잽니다. 배포판 Python(Ubuntu·Debian 패키지)과 공식 Python full 이미지(python:3.12 등)에서 잴 수 있습니다. 공식 slim 이미지(python:3.12-slim 등)에는 잴 수 있는 지점이 없어 GC 차트가 나오지 않습니다. Python GC 측정 방법 표에 측정 중인 인스턴스와 방법(usdt 또는 symbol)이 나옵니다. 세대(0·1·2)는 구분하지 않습니다.

참고: 이벤트 루프 최장 실행 시간은 node-agent 가 eBPF 로 프로세스 메인 스레드의 epoll_pwait 호출 간격을 재서 냅니다. 앱은 고치지 않습니다. 이벤트 루프를 메인 스레드가 아닌 스레드에서 돌리는 앱은 값이 없거나 틀릴 수 있습니다. 이벤트 루프를 쓰지 않는 앱이라도 메인 스레드가 epoll 을 쓰면 값이 나올 수 있습니다. 이때 값은 루프 막힘을 뜻하지 않습니다. 측정 창보다 오래 이어지는 막힘은 막힘이 끝난 뒤에 보입니다. 값은 최근 수집 주기에 15초를 더한 시간 동안의 최댓값이라 같은 큰 값이 연이은 두 점에 나올 수 있습니다. 조회 범위가 길어도 차트의 각 점은 그 점 간격 안의 가장 큰 값입니다.

참고: 런타임 탭은 해당 런타임이 감지된 애플리케이션에서만 표시됩니다(에이전트의 런타임 감지 또는 OpenTelemetry 계측). OpenTelemetry 연동 방법은 분산추적 문서를 참고하세요.

스토리지(Storage) 탭

영구 볼륨(PV/PVC 등)을 사용하는 애플리케이션에서 조건부로 표시됩니다. 볼륨 사용량·I/O 처리량·I/O 지연 등 스토리지 메트릭을 확인할 수 있습니다.

볼륨(마운트) 단위로 다음 지표를 제공합니다.

지표	설명
디스크 공간	볼륨별 사용량(used)과 전체 용량(total). 사용률(%)이 임계값을 넘으면 경고합니다
IOPS	볼륨별 초당 읽기/쓰기 작업 수
대역폭	볼륨별 초당 읽기/쓰기 처리량(bytes/s)
평균 I/O 대기 시간	볼륨별 평균 I/O 완료 대기 시간(await)
I/O 부하 (총 대기 시간)	볼륨의 총 I/O 지연(초/초). 값이 높을수록 디스크가 포화 상태에 가깝습니다
I/O 사용률	디스크가 I/O 처리로 바쁜 시간의 비율(%)

볼륨 목록 표에는 볼륨별 지연(Latency)·I/O 부하·공간(Space)·디바이스(Device)가 요약됩니다.

검사: 디스크 공간 사용률(기본 80% 초과)과 디스크 I/O 부하가 임계값을 초과하면 경고합니다.

NFS 볼륨 표시 방식(중요): NFS(및 CephFS 등 네트워크 파일시스템) 볼륨은 디스크 공간(용량·사용량)만 표시되고, 블록 디바이스별 I/O 처리량 지표는 제공되지 않습니다(네트워크 볼륨은 로컬 블록 디바이스가 없기 때문입니다). 또한 표시되는 용량과 사용량은 개별 PVC의 크기가 아니라 NFS 서버 export(공유 스토리지) 전체 기준입니다. 예를 들어 1Gi로 요청한 PVC라도 차트에는 NFS export 전체 용량(예: 536GB)과 그 export에 저장된 전체 사용량이 표시됩니다. 이는 NFS 하위 디렉터리 방식 프로비저너(nfs-client 등)가 PVC별 용량 쿼터를 적용하지 않아, 운영체제가 마운트에 대해 공유 export의 통계만 조회할 수 있기 때문이며, kubelet 등 다른 도구도 동일하게 동작합니다. 블록 디바이스 기반 PVC(로컬 볼륨, 대부분의 CSI 스토리지)는 마운트가 곧 해당 PVC이므로 용량·사용량이 정확하게 표시됩니다.

참고: 스토리지 탭은 영구 볼륨을 사용하는 애플리케이션에서만 나타납니다. 해당 리소스를 사용하지 않는 앱에서는 탭이 표시되지 않습니다.

GPU 탭

GPU를 사용하는 애플리케이션에서 조건부로 표시됩니다. GPU 사용률·GPU 메모리 사용량 등 GPU 메트릭을 확인할 수 있습니다.

상단 표에는 애플리케이션이 사용하는 GPU 목록(GPU · 이름 · vRAM · 노드 · 인스턴스)이 표시되고, 다음 지표를 제공합니다.

지표	설명
GPU 사용률 (%) : '<앱 이름>'	애플리케이션이 점유한 GPU 연산 사용률(%)
GPU 메모리 사용량 (바이트) : '<앱 이름>'	애플리케이션이 차지한 GPU 메모리 크기(바이트)
GPU 사용률 — 평균/피크	여러 GPU·인스턴스에 걸친 GPU 사용률의 평균과 피크(최대)
GPU 메모리 점유율 (%)	GPU 메모리 중 사용 중인 비율. 사용 바이트 ÷ 전체 크기
GPU 점유 프로세스	같은 GPU를 사용하는 컨테이너별 사용률 비중(누적)
GPU 메모리 점유 프로세스	같은 GPU의 메모리를 사용하는 컨테이너별 사용량(바이트, 누적)
GPU 온도 (℃) · GPU 전력 (W)	GPU별 온도와 소비 전력
GPU 메모리 대역폭 사용률 — 평균/피크	GPU 메모리 대역폭을 사용한 시간의 비율. 점유율과 다른 값이며, 탭 맨 뒤에 보조 차트로 나옵니다

GPU 메모리 점유율은 GPU 메모리를 얼마나 차지했는지를 보여 줍니다. 메모리 대역폭을 얼마나 바쁘게 썼는지는 GPU 메모리 대역폭 사용률 차트에서 확인합니다.

NVIDIA GB10 처럼 CPU와 GPU가 메모리를 함께 쓰는 통합 메모리 장치는 다음과 같이 표시됩니다.

• GPU 표의 vRAM 칸에 "(통합)" 이 붙습니다. 크기는 노드 메모리 전체입니다.
• GPU 메모리 점유율은 노드 메모리 전체를 분모로 계산합니다. CPU 사용분도 분모에 들어가므로 점유율이 낮게 보일 수 있습니다.
• 메모리 대역폭 차트가 나오지 않습니다. 그 대신 GPU UUID·메모리 대역폭 열이 있는 표가 나오고, 메모리 대역폭 칸에 "이 장치는 지원하지 않음" 이 나옵니다.

참고: GPU 탭은 GPU를 사용하는 애플리케이션에서만 나타납니다. 해당 리소스를 사용하지 않는 앱에서는 탭이 표시되지 않습니다.

vLLM 탭

애플리케이션이 vLLM 추론 서버이면 vLLM 탭이 나옵니다. 노드 에이전트가 vLLM 이 제공하는 /metrics 지표를 자동으로 수집합니다. 별도 설정은 필요하지 않습니다. 애플리케이션 목록의 유형 열에는 vLLM 으로 표시됩니다.

이 탭에서 다음 세 가지를 확인합니다.

• 요청이 밀리고 있는가? (실행 중·대기 요청 수, KV 캐시 사용률)
• 얼마나 처리하고 있는가? (토큰 처리량, 완료·실패 요청)
• 사용자가 느끼는 속도는 어떤가? (첫 토큰 시간, 전체 응답 시간)

탭 맨 위의 표는 vLLM 인스턴스의 구성을 보여 줍니다.

열	설명
인스턴스	vLLM 이 실행 중인 인스턴스
모델	vLLM 이 서비스하는 모델 이름. vLLM 실행 인자 --served-model-name 의 값입니다
유형	generate(텍스트 생성) 또는 pooling(임베딩·리랭크)
KV 캐시 용량 (토큰)	인스턴스가 확보한 KV 캐시 크기(토큰 수). pooling 인스턴스는 None 입니다

표 아래에 다음 차트 6개가 나옵니다. 모든 차트는 인스턴스별 시리즈로 그립니다.

차트	설명
실행 중·대기 요청 수	지금 처리 중인 요청 수와 대기열에 있는 요청 수. 대기 요청이 계속 0 보다 크면 처리 용량이 부족합니다
KV 캐시 사용률 (%)	KV 캐시 중 사용 중인 비율. 100% 에 가까우면 vLLM 이 실행 중인 요청을 대기열로 되돌립니다(선점)
토큰 처리량 (토큰/초)	초당 처리한 입력 토큰과 생성 토큰. 처리량이 줄고 대기 요청이 늘면 인스턴스가 느려진 것입니다
완료·실패 요청 (초당)	정상으로 끝난 요청과 실패(중단·오류)한 요청의 초당 수
첫 토큰 시간(TTFT) 평균 (초)	요청을 받은 뒤 첫 토큰을 내보내기까지 걸린 평균 시간. 사용자가 느끼는 응답 시작 지연입니다
전체 응답 시간(E2E) 평균 (초)	요청을 받은 뒤 응답을 끝내기까지 걸린 평균 시간. 생성 길이에 따라 크게 달라지므로 TTFT 와 함께 봅니다

유형이 pooling(임베딩·리랭크)인 인스턴스는 KV 캐시와 생성 토큰을 쓰지 않습니다. 그래서 pooling 인스턴스는 다음과 같이 표시됩니다.

• KV 캐시 사용률 차트와 첫 토큰 시간(TTFT) 차트에 나오지 않습니다. 애플리케이션의 인스턴스가 모두 pooling 이면 이 두 차트가 없습니다.
• 토큰 처리량 차트에는 입력 토큰만 나옵니다.

다음 경우에는 차트에 값이 없습니다.

• vLLM 이 multiprocess 지표 모드(PROMETHEUS_MULTIPROC_DIR 설정)로 실행되면, 요청을 한 번도 받지 않은 인스턴스는 실행 중·대기 요청 수와 KV 캐시 사용률 값을 내보내지 않습니다. 이 값은 0 이 아니라 빈 상태로 있다가, 인스턴스가 첫 요청을 받은 뒤부터 나옵니다. vLLM 의 동작이며 수집 오류가 아닙니다.
• 조회 구간에 요청이 없으면 평균 차트(TTFT·E2E)를 계산할 수 없습니다. 값이 없는 차트는 탭에 나오지 않습니다.

탭 상단의 검사 상태에는 vLLM 요청 오류, vLLM KV 캐시 사용률, vLLM 대기 요청 검사가 나옵니다. 애플리케이션의 인스턴스가 모두 pooling 이면 vLLM KV 캐시 사용률 검사는 나오지 않습니다. 이 검사와 연결된 알림 규칙은 인시던트 장의 알림 규칙 탭을 참고하세요.

참고: vLLM 탭은 노드 에이전트가 설치된 환경에서만 나옵니다. vLLM 을 --disable-log-stats 옵션으로 실행하면 지표를 내보내지 않으므로 탭이 나오지 않습니다. 노드 에이전트 환경 변수 SCRAPE_VLLM_METRICS 를 false 로 두어도 수집하지 않습니다(기본값 true). 애플리케이션 안에 vLLM 을 라이브러리로 넣어 실행한 경우와 vLLM 이 아닌 추론 서버(Hugging Face TEI 등)는 대상이 아닙니다.

검사 상태

각 리포트 탭의 상단에는 해당 영역의 검사(Inspection) 조건 충족 여부가 표시됩니다. 임계값을 초과한 항목이 있으면 경고 또는 심각 상태로 표시되며, 검사 조건의 세부 내용을 확인하거나 설정을 조정할 수 있습니다.

• 초록색 좌측 테두리: 검사 기준을 충족한 정상 상태 (OK)
• 노란색 좌측 테두리: 경고 수준의 임계값 초과 (Warning)
• 빨간색 좌측 테두리: 심각 수준의 임계값 초과 (Critical)

데이터베이스 모니터링 연동 추가(계측)

PostgreSQL·MySQL·Redis·MongoDB·Memcached 같은 데이터베이스는 eBPF 기반 L7 트래픽(쿼리 응답시간·에러율)은 설치만으로 자동 수집되지만, DB 내부 지표(연결 수, 활성 쿼리, 캐시 적중률, 복제 지연, 슬로우 쿼리 등)까지 수집하려면 데이터베이스 접속 정보를 알려주는 계측(Instrumentation) 설정이 필요합니다.

애플리케이션이 데이터베이스 유형으로 감지되면 상세 화면의 검사 상태 영역에 계측 안내가 표시되며, 연결 설정 을 클릭하면 아래 두 방식을 제공하는 설정 대화상자가 열립니다.

사전 조건 — 모니터링 전용 계정

데이터베이스에 모니터링 권한을 가진 계정을 먼저 준비합니다.

• PostgreSQL: pg_monitor 역할과 pg_stat_statements 확장이 필요합니다(확장은 shared_preload_libraries 서버 설정으로 로드되어 있어야 함).

  create role openmaru with login password '<PASSWORD>';
  grant pg_monitor to openmaru;
  create extension pg_stat_statements;

• MySQL: 다음 권한을 가진 계정이 필요합니다.

  GRANT SELECT, PROCESS, REPLICATION CLIENT ON *.* TO 'openmaru'@'%';

• Redis / MongoDB / Memcached: 읽기 권한을 가진 접속 계정(또는 비밀번호)을 준비합니다.

방법 1 — Kubernetes Pod 어노테이션 (권장)

openmaru-observ-cluster-agent는 openmaru.io/<type>-scrape: "true" 어노테이션이 붙은 Pod를 자동으로 발견하여 지표를 수집합니다. 어노테이션은 Deployment·StatefulSet 같은 상위 객체가 아니라 Pod 템플릿(spec.template.metadata.annotations)에 직접 지정해야 합니다.

PostgreSQL 예시:

openmaru.io/postgres-scrape: "true"
openmaru.io/postgres-scrape-port: "5432"
# 자격증명 — (A) 직접 입력
openmaru.io/postgres-scrape-credentials-username: "openmaru"
openmaru.io/postgres-scrape-credentials-password: "<PASSWORD>"
# 자격증명 — (B) Kubernetes Secret 참조 (A 대신 사용 가능)
openmaru.io/postgres-scrape-credentials-secret-name: "postgres-secret"
openmaru.io/postgres-scrape-credentials-secret-username-key: "username"
openmaru.io/postgres-scrape-credentials-secret-password-key: "password"
openmaru.io/postgres-scrape-param-sslmode: "disable"

다른 데이터베이스는 접두어와 기본 포트만 다르며 나머지 키(-credentials-*, -secret-*)는 동일한 규칙을 따릅니다.

유형	scrape 어노테이션	기본 포트	추가 파라미터
PostgreSQL	openmaru.io/postgres-scrape	5432	-param-sslmode(예: disable)
MySQL	openmaru.io/mysql-scrape	3306	-param-tls(true/false/skip-verify/preferred)
Redis	openmaru.io/redis-scrape	6379	사용자명은 선택(ACL 사용 시 -credentials-username 지정 가능), 비밀번호
MongoDB	openmaru.io/mongodb-scrape	27017	—
Memcached	openmaru.io/memcached-scrape	11211	—

방법 2 — 수동 설정 (UI)

Kubernetes 어노테이션을 사용할 수 없거나 클러스터 외부 데이터베이스인 경우, 연결 설정 대화상자의 수동설정 탭에서 포트·사용자 이름·비밀번호(PostgreSQL은 sslmode, MySQL은 tls 옵션 포함)를 직접 입력하고 저장합니다.

참고: 설정을 마친 뒤 데이터베이스 전용 지표가 화면에 나타나기까지 수 분이 걸릴 수 있습니다. cluster-agent는 Pod 어노테이션만 확인하므로 상위 객체(Deployment/StatefulSet)에 붙인 어노테이션은 인식하지 않습니다.

---

관련 문서

• 토폴로지 맵 -- 서비스 간 의존성을 시각적으로 파악합니다.
• 인시던트 -- SLO 위반으로 발생한 인시던트 목록을 확인합니다.
• 분산추적 -- 전체 추적 데이터를 탐색합니다.
• 로그 뷰어 -- 전체 로그를 통합 검색합니다.
• 배포 -- 배포 이력을 확인합니다.
• 차트 사용법 -- 차트 읽는 법, 확대, 오버레이 등 공통 차트 기능을 확인합니다.
• 설정 -- 검사 조건 설정, 애플리케이션 카테고리 관리