H20. 에이전트 상태 점검·문제 해결
Diátaxis: How-to(목표별 가이드) · 대상: 관리자 — 에이전트 상태 메뉴는 관리자 권한 계정에만 보입니다 ← 목차로
차트가 비거나 특정 인스턴스만 데이터가 안 들어올 때, 가장 먼저 볼 곳이 에이전트 상태 화면입니다. 에이전트는 각 인스턴스에 붙어 데이터를 수집해 APM 서버로 보내는 수집기이므로, 이게 끊기면 화면도 빕니다.
에이전트·인스턴스 개념은 E2.1을 보세요.
여는 법 — 좌측 메뉴 ▸ 설정 ▸ 에이전트 상태 (/settings/agents, 관리자만 보임)
에이전트 상태 화면 읽기
화면은 WAS · 웹서버 · 시스템 영역으로 나뉘고, 각 영역에 인스턴스들이 카드로 늘어섭니다.
각 영역 헤더 우측의 카운트 배 지(예: 22 / 22)는 연결된 수 / 전체 수입니다.
상태는 인스턴스마다 상태 점(dot)과 색으로 표시합니다.
| 상태 | 의미 |
|---|---|
| RUNNING(정상) | 에이전트가 연결돼 정상 수집 중(점이 살짝 깜빡임) |
| STOPPED(중지) | 연결이 끊겼거나 인스턴스가 내려감 — 데이터 수집 안 됨 |
각 인스턴스의 IP·버전도 함께 표시됩니다. 버전이 다른 인스턴스가 섞여 있으면 에이전트 업데이트 누락을 의심할 수 있습니다.
참고 카운트 배지의 "연결 수 / 전체 수"가 어긋나 있으면(예:
21 / 22) 한 대가 빠진 것입니다. 어느 영역·어느 인스턴스가 STOPPED인지 바로 찾을 수 있습니다.
연결 끊김·무응답 대응
STOPPED이거나 데이터가 안 들어오는 인스턴스를 만나면 다음 순서로 좁힙니다.
- 새로고침으로 최신 상태 확인 — 화면 상단의 그룹 다시읽기(Refresh Groups) / 정보 재 수집(Collect information again), 또는 해당 인스턴스 메뉴의 에이전트 새로고침(Agent Refresh)을 눌러 현재 상태를 다시 받습니다.
- 실제로 내려간 것인지 구분 — 인스턴스(프로세스) 자체가 중지된 것인지, 살아 있는데 에이전트 연결만 끊긴 것인지 확인합니다. 전자는 인스턴스를 다시 띄워야 하고, 후자는 네트워크·에이전트 설정 문제입니다.
- 웹서버 LB 워커는 인스턴스 메뉴에서 시작 / 종료(Start/Stop)로 직접 조작할 수 있습니다.
주의 위 액션들은 누르면 무슨 작업을 하는지 설명하는 확인창이 먼저 뜨고, 예(Yes) 를 눌러야 실행됩니다. 운영 중 영향이 있을 수 있으니 확인창 내용을 읽고 진행하세요.
연결이 끊기면 보통 이벤트로도 알림이 옵니다(에이전트 중지 등). 이벤트별 의미는 R3. 이벤트 종류 레퍼런스를 보세요.
에이전트 중복 감지 대응
같은 식별 정보로 에이전트 두 개가 수집 서버에 접속하면, 수집 서버는 둘 중 하나의 접속을 거부하고
그 사실을 헤더의 알림 종 창에 에이전트 중복 감지 탭으로 알립니다. 이 탭은 거부가 있을 때만
나타납니다. 식별 정보는 WAS 에이전트가 IP + instance.id, SYS 에이전트가 IP 입니다.
탭의 항목을 펼치면 다음이 보입니다.
| 표시 | 뜻 |
|---|---|
WAS · <IP> · <인스턴스> / SYS · <IP> | 부딪힌 에이전트의 종류와 식별 정보 |
PID <새 쪽> ↔ <기존 쪽> | 접속하려던 프로세스와 이미 접속해 있던 프로세스의 PID |
| 호스트 · 최초 충돌 · 최근 충돌 | 호스트 이름, 처음·마지막으로 부딪힌 시각 |
| 누적 N 회 거부 | 지금까지 거부한 횟수 |
| 조치 가이드 | 에이전트 종류에 따라 다른 안내 (아래 표) |
| 에이전트 | 조치 가이드 |
|---|---|
| WAS | ① khan-agent.conf 의 instance.id 변경 ② 해당 에이전트 재기동 |
| SYS | ① 각 서버의 khan-sys-agent.conf 에서 khan.agent.ip 를 확인 ② lo 인터페이스에 /32 로 붙인 가상 IP 가 자기 주소로 보고되는지 확인 ③ 같은 호스트에 에이전트를 두 개 띄웠다면 하나를 중지 |
SYS 에이전트에는 instance.id 설정이 없으므로 WAS 용 안내를 따르지 않습니다. 서로 다른 서버가
같은 IP 를 보고하는 경우와, 한 서버에 SYS 에이전트가 두 개 떠 있는 경우가 대표적입니다.
- 조치한 뒤 거부가 15분 동안 다시 없으면 항목이 자동으로 사라집니다.
- 거부당한 에이전트는 다시 접속을 시도하며, 시도 간격이 점점 길어집니다. 그래서 거부가 몇 분씩 끊겨 보여도 문제가 풀린 것은 아닐 수 있습니다.
참고 SYS 에이전트가 중복되어도 에이전트 상태 화면에서는 두 에이전트가 한 줄로 합쳐져 RUNNING 으로 보일 수 있습니다. 중복 여부는 알림 종의 에이전트 중복 감지 탭에서 확인합니다. 수집 서버가 여러 대(클러스터)면, 거부를 기록한 서버와 다른 서버에 접속한 화면에서는 이 탭이 보이지 않을 수 있습니다.
스레드 덤프·힙덤프 요청
"인스턴스는 살아 있는데 응답이 없다"(무응답·행) 싶을 때는, 멈춘 지점을 보려고 덤프를 요청합니다.
- 스레드 덤프 분석(Thread Dump Analyze) — 지금 스레드들이 무엇을 하다 멈췄는지 봅니다. 데드락·잠금 경합 의심 시 유용합니다.
- 힙 오브젝트 분석(Heap Object Analyze) — 메모리에 무엇이 쌓였는지(누수 후보) 봅니다.
데드락·OOM 이벤트가 나면 덤프가 자동 수집되기도 합니다. 메모리·누수 쪽 진단 절차는 H7. 메모리 누수 의심 시 점검에 자세히 있습니다.
주의 덤프 수집은 그 순간 JVM에 부하를 줍니다. 트래픽이 적은 시간대에, 필요한 인스턴스에만 요청하세요.
잘 안될 때
| 증상 | 점검 |
|---|---|
| 에이전트 상태 메뉴가 안 보임 | 관리자 권한 계정인지 확인 — 에이전트 상태는 관리자에게만 보입니다 |
| 새로고침해도 STOPPED 그대로 | 인스턴스(프로세스)가 실제로 떠 있는지, 호스트·네트워크 상태 확인 |
| 데이터는 오는데 버전이 제각각 | 에이전트 업데이트 누락 — 가이드 & 다운로드에서 최신 에이전트 확인 |
| 차트만 비고 상태는 RUNNING | 셀렉터 대상·기간 문제일 수 있음 → H1 · H2 |
상태는 RUNNING 인데 대시보드 값이 - | 에이전트는 연결돼 있지만 지표 값이 들어오지 않는 상태입니다(에이전트 프로세스가 멈춤, OS 지표 수집 실패, 수집 지연 등). 0 으로 보이면 한가한 서버로 오해할 수 있어 - 로 표시합니다. 해당 호스트에서 에이전트 프로세스 상태와 에이전트 로그를 확인합니다 — 화면별 기준은 R2.4 시스템(서버) 차트 |
| 알림 종에 에이전트 중복 감지 탭이 나타남 | 같은 식별 정보로 에이전트가 두 개 접속하려 함 — 에이전트 중복 감지 대응 |
관련 문서
- E2.1 애플리케이션 그룹·인스턴스·에이전트 — 에이전트 개념
- R3. 이벤트 종류 레퍼런스 — 에이전트 중지·데드락·OOM 이벤트, 에이전트 중복 감지
- H7. 메모리 누수 점검 — 힙·스레드 덤프 활용
- H1. 모니터링 대상 좁히기 — 차트가 비어 보일 때 셀렉터 점검