에이전트 연결 관련 문의 대응
고객 설명 포인트
"고객님, 에이전트 연결 문제는 대부분 네트워크 설정(방화벽, IP 주소)이나 설정 파일 오류에서 발생합니다. 지금부터 단계적으로 확인해보겠습니다. 5~10분 정도 소요됩니다."
고객이 에이전트 연결 관련 문제를 신고할 때의 대응 가이드다. UI 화면 기준 증상 → 기술 원인 → 해결 경로 순으로 진행한다.
1. 증상 목록
| # | 고객이 말하는 증상 (UI 기준) | 섹션 |
|---|---|---|
| S-1 | "에이전트가 연결되지 않습니다 (빨간 아이콘)" | 2.1 |
| S-2 | "에이전트가 간헐적으로 끊깁니다" | 2.2 |
| S-3 | "데이터가 누락됩니다 / 메트릭이 0으로 보입니다" | 2.3 |
2. 증상별 대응 가이드
2.1 S-1: 에이전트가 연결되지 않는다
증상: FlowKat 대시보드(센트리 > 에이전트 목록)에서 에이전트가 빨간 아이콘으로 표시되거나 목록에 나타나지 않는다. 에이전트 로그에 Connection refused 메시지가 반복된다.
고객에게 확인
- 에이전트가 설치된 서버에서 에이전트 프로세스가 실행 중인가?
flowkat.conf의 Collector 주소(net_collector_ip,net_collector_tcp_port)는 올바른가?- 에이전트 서버 → Collector 서버 간 6100 포트 연결이 가능한가?
- 에이전트 로그에 어떤 메시지가 반복되는가?
확인 경로: 센트리 > 에이전트 목록
확인 항목: 에이전트 상태 아이콘 (녹색: 정상, 빨간: 미연결)
기술지원 확인
- 에이전트 프로세스 확인:
ps -ef | grep flowkat
# flowkat 프로세스가 보여야 정상
- Collector 포트 연결 테스트:
nc -zv {collector_ip} 6100
# Connection succeeded 응답 확인
- 에이전트 로그에서 연결 오류 확인:
tail -100 $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log | grep -i "refused\|error\|reconnect"
- Collector 로그 확인:
tail -100 $COLLECTOR_HOME/logs/server-$(date +%Y%m%d).log | grep -i "handshake\|connect\|error"
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| 에이전트 프로세스 | PID 존재 | 프로세스 없음 |
| TCP 6100 | Connection succeeded | Connection refused |
| 에이전트 로그 | Handshake OK, Object registered | Connection refused 반복 |
| Collector 로그 | 연결 수락 메시지 | 연결 없음 |
벤더 에스컬레이션 시 전달 정보
- 에이전트 로그:
$FLOWKAT_HOME/logs/(최소 1시간치) - Collector 서버 로그:
$COLLECTOR_HOME/logs/(최소 1시간치) - 설정 파일:
$FLOWKAT_HOME/conf/flowkat.conf(IP/Port 부분) - 에이전트 버전:
cat $FLOWKAT_HOME/VERSION - OS, Java 버전:
java -version - 방화벽 규칙:
iptables -L INPUT -n | grep 6100 - 증상 발생 시각 및 환경 정보
2.2 S-2: 에이전트가 간헐적으로 끊긴다
증상: 평소에는 연결되어 있다가 특정 시간대에 또는 불규칙하게 에이전트가 빨간 아이콘으로 바뀐다.
고객에게 확인
- 끊기는 시간대 패턴이 있는가? (새벽, 업무 피크 시간대 등)
- 끊기는 빈도는 어느 정도인가? (분당 1회, 하루 1회 등)
- Kubernetes 또는 컨테이너 환경인가?
- 에이전트 서버의 메모리/CPU 사용량이 높은가?
기술지원 확인
# 에이전트 로그에서 재연결 패턴 확인
grep -i "reconnect\|disconnect\|timeout" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log
# 컨테이너 환경: Pod 재시작 이력 확인
kubectl get events -n {namespace} | grep -i "restart\|kill"
# OOM 여부 확인
dmesg | grep -i "oom\|killed" | tail -20
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
| 재연결 간격 | 없음 | 주기적 Scheduling reconnect |
| Pod 재시작 | 0회 | 재시작 이력 있음 |
| 메모리 사용 | JVM 힙 여유 충분 | OOM Killer 감지 |
벤더 에스컬레이션 시 전달 정보
- 에이전트 로그 (끊김 발생 전후 30분)
- 시스템 메모리/CPU 통계 (
top또는vmstat출력) - 컨테이너 환경인 경우
kubectl describe pod {pod-name}출력 - 끊김 발생 시각 목록
2.3 S-3: 메트릭 데이터가 누락된다
증상: 에이전트 연결은 녹색(정상)이나, 대시보드에서 CPU, Memory 등 특정 메트릭이 0 또는 빈 값으로 표시된다.
고객에게 확인
- 어떤 메트릭이 0으로 보이는가? (CPU, 메모리, 디스크 I/O 중)
- 컨테이너 환경인가, 물리 서버/VM 환경인가?
- 에이전트 모듈이 Host 에이전트인가, 컨테이너 에이전트인가?
기술지원 확인
# 에이전트 배치 전송 확인 (1초마다 출력)
grep -i "sendBatch\|batch" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log | head -20
# 정상: [DataProxy] sendBatch: count=4, bytes=1240
# OSHI 권한 오류 확인 (컨테이너 환경)
grep -i "oshi\|proc\|permission\|denied" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log
# 오브젝트 등록 확인
grep -i "object registered\|objHash" $FLOWKAT_HOME/logs/agent-$(date +%Y%m%d).log
확인 포인트:
| 확인 항목 | 정상 상태 | 비정상 상태 |
|---|---|---|
sendBatch 로그 | 1초마다 출력 | 없음 또는 오류 |
| OSHI 권한 | 오류 없음 | Permission denied /proc |
| Object 등록 | Object registered 로그 | 없음 |
벤더 에스컬레이션 시 전달 정보
- 에이전트 로그 (1시간치)
- 컨테이너 환경인 경우 securityContext 설정 (
kubectl get pod -o yaml출력) - 에이전트 모듈명 및 버전 (Host 에이전트 vs 컨테이너 에이전트)
- 미수집 메트릭 항목 목록
3. 관련 문서
| 모듈 | 관련 trouble-shooting | 핵심 이슈 |
|---|---|---|
| 컨테이너 에이전트 | 161-agent-host-container | K8s 연결, OSHI 권한, Pod 이름 |
| Kubernetes Pod 이름 | 162-kubernetes-pod-seq-name | Pod 이름 파싱 |
| TCP 연결 풀 | 146-protocol-tcpip-connection-pool-fix | 연결 풀 오류 |