에이전트/서버 로그 메시지 코드표
FlowKat의 각 서비스는 고유 코드 접두어를 사용하여 로그를 출력한다. 코드 형식은 [접두어][숫자] 패턴이며, Logger.println(코드, 메시지) 형태로 기록된다. 로그 파일 위치는 각 서비스의 볼륨 마운트 경로 아래 logs/ 디렉토리에 있다.
로그 코드 접두어 체계
| 접두어 | 서비스 | 설명 |
|---|---|---|
A | Java Agent | 에이전트 코어 및 네트워크 I/O 관련 |
S | Collect Server | Scala 기반 수집 서버 내부 이벤트 |
TLV | Java Agent (V3) | TLV Netty TCP 통신 레이어 |
R | Java Agent (Reactive) | Reactor/Coroutine 계측 레이어 |
MTC | Java Agent (MongoDB) | MongoDB 추적 레이어 |
SA | Java Agent (Delayed Svc) | 지연 서비스 파일 로드/처리 |
AG-K8S | Java Agent (K8s) | Kubernetes 환경 호스트명 처리 |
Collect Server 로그 메시지 (수집 서버)
Collect Server의 로그 클래스는 서버 로거이며, 로그 출력 형태로 호출된다. throttle 값(예: 10)이 지정되면 해당 주기(초) 동안 동일 코드의 중복 출력을 억제한다.
| 코드 | 심각도 | 메시지 패턴 | 의미 | 조치 |
|---|---|---|---|---|
S109 | WARN | queue exceeded!! | PerfCountCore 수신 큐 포화 | Collect Server 힙 증가 (-Xmx), 에이전트 수 분산 |
S110 | WARN | queue exceeded!! | ProfileCore 프로파일 큐 포화 | net_collector_tcp_reconnect_max_retry 점검, 서버 리소스 확인 |
S110-0 | WARN | queue exceeded!! | ProfilePreCore 사전처리 큐 포화 | XLog 수집량 급증 징후. 애플리케이션 트랜잭션 부하 점검 |
S111 | WARN | queue exceeded!! | SqlTables SQL 텍스트 큐 포화 | SQL 수집 빈도 조정 (net_collector_tcp_*) |
S112 | ERROR | [sql text]\n[throwable] | SQL 텍스트 파싱 오류 | SQL 데이터 형식 점검, 인코딩 이슈 확인 |
S113 | WARN | queue exceeded!! | StatusCore 상태 큐 포화 | 에이전트 연결 수 점검 |
S114 | ERROR | Thread\n[throwable] | TextCacheReset 스레드 내부 오류 | 스택트레이스 확인 후 서버 재시작 검토 |
S115 | WARN | queue exceeded!! | TextCore 텍스트 큐 포화 | 메서드/SQL 텍스트 수집량 과다. 수집 필터 적용 검토 |
S116-1 | WARN | queue exceeded!! | XLogDelayingsRecoverCore 큐 포화 | XLog 지연 복구 큐 과부하. 지연 서비스 임계값 점검 |
S145 | WARN | GeoIP db file is not readable : [path] | GeoIP DB 파일 읽기 불가 | 파일 경로/권한 확인. 미사용 시 GeoIP 기능 비활성화 |
S146 | INFO | GeoIP db file is loaded : [path] | GeoIP DB 정상 로드 | 정상 동작 |
S148 | INFO | [INFO] RemoteControlManager queue exceeded!command:[cmd] | 원격 제어 커맨드 큐 포화 | 대시보드에서 원격 명령 과다 전송 중. 요청 빈도 조절 |
S150 | WARN | [packet info] | MultiPacketProcessor 알 수 없는 패킷 타입 | 에이전트/서버 버전 불일치 의심. 버전 정합성 확인 |
S158 | WARN | overflow recv queue!! | NetDataProcessor 수신 큐 넘침 | 네트워크 수신 처리 지연. 서버 CPU/스레드 풀 점검 |
S159 | ERROR | invalid data [exception] | 수신 데이터 파싱 실패 | 에이전트 데이터 포맷 불일치. 에이전트 버전 확인 |
S160 | INFO | [debug info string] | NetDataProcessor 디버그 덤프 | 정상 진단 출력. 운영 중 과도 출력 시 로그 레벨 조정 |
S167 | ERROR | tcp port=[port] [throwable] | TCP 서버 바인딩 실패 | 포트 충돌(6100) 또는 권한 부족. ss -tlnp | grep 6100 확인 |
S178 | INFO | Server Shutdown | 서버 정상 종료 시작 | 정상 종료 흐름 |
S179 | INFO | Shutdown [instance] ... | 각 서비스 인스턴스 종료 중 | 정상 종료 흐름 |
S191 | WARN | @startDaemon [NullPointerException] | TextCacheReset 데몬 NPE | 재시작 검토. 동일 오류 반복 시 버그 리포트 |
S192 | WARN | @startDaemon: [throwable] | TextCacheReset 데몬 일반 예외 | 동일 코드 반복 출력 시 Throwable 타입 확인 |
S200 | WARN | Batch queue exceeded!! | BatchCore 배치 큐 포화 | 배치 작업 처리 지연. 서버 힙/스레드 증가 검토 |
S205 | WARN | queue exceeded!! | AlertSummary 알림 요약 큐 포화 | 알람 트리거 빈도 과다. 알람 규칙 임계값 점검 |
S501 | WARN | Cannot find a V3 NIO channel for [objName] | 에이전트 V3 채널 없음 | 에이전트가 아직 연결되지 않았거나 연결 끊김. 에이전트 상태 확인 |
S502 | ERROR | Agent Call error. Object pack is null | AgentCall 오브젝트 팩 null | 내부 오류. 서버 재시작 후 재현 여부 확인 |
S505 | ERROR | Agent CallChunked error. Object pack is null | 청크 호출 팩 null | 위와 동일 |
S506 | WARN | Cannot find a V3 NIO channel for chunked call: [objName] | 청크 호출 채널 없음 | 에이전트 연결 상태 확인 |
S510 | WARN | V3 REQ timeout: [cmd] | 에이전트 REQ 타임아웃 | 에이전트 응답 지연. 에이전트 JVM 상태 (GC, CPU) 점검 |
S510 | WARN | V3 REQ failed: [message] | 에이전트 REQ 실패 | 네트워크 단절 또는 에이전트 오류 |
S511 | WARN | V3 REQ chunked failed: [message] | 청크 REQ 실패 | 대용량 요청(힙 덤프, 스레드 덤프) 실패. 에이전트 상태 확인 |
S520 | WARN | 병렬 에이전트 호출 실패: [message] | ThreadList 병렬 호출 실패 | 멀티 에이전트 조회 중 일부 실패. 개별 에이전트 상태 확인 |
S521 | WARN | 병렬 그룹 에이전트 호출 실패: [message] | 그룹 병렬 호출 실패 | 에이전트 그룹 조회 실패. 그룹 내 에이전트 연결 점검 |
TCP 서버 기동 로그 (정상)
Collect Server 정상 기동 시 다음 패턴이 출력된다.
[timestamp] tcp_port=6100
[timestamp] tcp_mode=NIO (Netty 4.2.10)
[timestamp] V1/V2 deprecated, V3 only
이 패턴이 출력되지 않으면 TCP 서버 바인딩 실패(S167)를 먼저 확인한다.
Java 에이전트 로그 메시지 (Java 에이전트)
Java 에이전트 로그 클래스는 에이전트 로거이며, 에이전트 stdout 및 지정된 로그 파일에 기록된다. 에이전트 로그는 고객 애플리케이션 서버의 표준 출력 또는 conf.log_dir 경로에서 확인한다.
V3 TLV TCP 통신 레이어 (코드: A, TLV)
| 코드 | 심각도 | 메시지 패턴 | 의미 | 조치 |
|---|---|---|---|---|
A80 | INFO | V3 TLV TCP started: [host]:[port] | V3 Netty TCP 연결 시작 | 정상 동작. Collect Server 주소 확인 용도로 활용 |
A81 | INFO | V3 TLV TCP stopped | V3 TCP 연결 종료 | 정상 종료 또는 에이전트 재시작 |
A82 | INFO | Collector address changed: [old] -> [new] | Collect Server 주소 동적 변경 | conf_static 설정 변경 감지 |
A100 | INFO | agent boot seed=[hex32] | 에이전트 부트 시작, 시드 값 | 정상 기동. 시드는 에이전트 식별자 기반 |
A101 | ERROR | Transformer Error : [className] [throwable] | 바이트코드 변환 오류 | 클래스 충돌 또는 계측 실패. trace_exclude_url 등 필터 적용 |
TLV | INFO/WARN | [tlv message] | V3 TLV Netty 내부 이벤트 | 연결/재연결 상세 로그. 재연결 루프 발생 시 Collect Server 상태 점검 |
재연결 메커니즘
에이전트는 Collect Server 연결 실패 시 이중 경로 재연결(dual retry path) 전략을 적용한다. flowkat.net.tlv.TlvClientBootstrap에 구현되어 있다.
- 경로 1 (연결 성공 후 단절):
TlvReconnectHandler.channelInactive()발동 → 지수 백오프 + Jitter(0~30%) 재연결 - 경로 2 (최초 연결 실패):
ChannelFuture실패 리스너에서scheduleRetryAfterFailure()호출 → 동일 백오프 적용
재연결 관련 파라미터 (에이전트 설정):
| 파라미터 | 기본값 | 설명 |
|---|---|---|
net_collector_tcp_connection_timeout_ms | 3000 ms | 연결 시도 타임아웃 |
net_collector_tcp_so_timeout_ms | 60000 ms | 소켓 읽기 타임아웃 |
net_collector_tcp_reconnect_initial_delay_ms | 1000 ms | 첫 재연결 대기 시간 |
net_collector_tcp_reconnect_max_delay_ms | 30000 ms | 최대 재연결 대기 시간 |
net_collector_tcp_reconnect_max_retry | 30 회 | 최대 재시도 횟수 |
net_collector_tcp_reconnect_periodic_retry_ms | 300000 ms | 최대 재시도 후 주기적 재시도 간격 |
에이전트 내부 처리 (코드: A1xx)
| 코드 | 심각도 | 메시지 패턴 | 의미 | 조치 |
|---|---|---|---|---|
A111 | ERROR | [class] [method] [message] [throwable] | Counter 수집기 실행 오류 | 수집 플러그인 충돌 여부 확인 |
A111-1 | ERROR | [class] [method] [throwable] | Counter 수집기 Throwable | 위와 동일 |
A112 | ERROR | [stack trace] | CounterExecutingManager 예외 | 에이전트 재시작 검토 |
A113 | INFO | Counter Collector Started (#[n]) | 카운터 수집기 정상 시작 | 정상 동작 |
A114 | WARN | METER-USERS[throwable] | MeterUsers 활성 사용자 계측 오류 | 웹 세션 계측 충돌. hook_http_session_enabled=false 시도 |
A126 | ERROR | [throwable] | AgentClassHandle 클래스 요청 오류 | 클래스 로딩 실패. JVM 힙 여유 공간 확인 |
A127 | INFO | RequestCmd.OBJECT_SYSTEM_GC | 원격 GC 요청 수신 | 대시보드에서 GC 수행 명령 발생 |
A128 | WARN | [throwable] | AgentThread 스레드 덤프 오류 | 스레드 덤프 수집 실패. JVM 상태 점검 |
A129 | WARN | Warning duplicated Handler key=[key] [old] <-> [new] | 핸들러 키 중복 등록 | 에이전트 플러그인 또는 계측 중복. 플러그인 설정 확인 |
A130 | WARN/ERROR | V3 TCP send failed: not connected or send error | V3 TCP 전송 실패 (미연결) | Collect Server 연결 상태 확인. 재연결 중이면 일시적 현상 |
A130 | WARN | V3 TCP not connected, dropping [n] packs | 연결 미수립으로 패킷 드롭 | 재연결 대기 중 정상 드롭. 반복 시 Collect Server 접근 가능 여부 점검 |
A130 | INFO | TCP unknown cmd=[cmd] | 알 수 없는 TCP 커맨드 수신 | 에이전트/서버 버전 불일치. 버전 정합성 확인 |
A131 | ERROR | sendCounter Exception: [message] | Counter 패킷 전송 예외 | 네트워크 단절 또는 채널 오류 |
A132 | ERROR | sendV3 Exception at index [k]: [message] | V3 배치 전송 예외 | 배치 전송 중 오류. 재연결 후 자동 복구됨 |
A132 | ERROR | REQ processing error: [message] | REQ 처리 오류 | AgentReqHandler 응답 직렬화 오류 |
A133 | ERROR | Chunked download error: [message] | 청크 다운로드 오류 | 힙 덤프 등 대용량 데이터 전송 실패 |
A141 | ERROR | socket trace error [throwable] | 소켓 API 호출 추적 오류 | hook_socket_enabled=false로 회피 가능 |
A142 | ERROR | socket trace close error [throwable] | 소켓 닫기 추적 오류 | 위와 동일 |
A158 | INFO | [AbstractPlugin toString] | 플러그인 로드 완료 | 정상 동작 |
A173–A175 | WARN | [exception] | WrResponseReactive 응답 처리 오류 | Reactive 스트림 응답 래핑 오류. 웹프레임워크 버전 점검 |
Reactive/Coroutine 계측 (코드: R)
| 코드 | 심각도 | 메시지 패턴 | 의미 | 조치 |
|---|---|---|---|---|
R01o2 | ERROR | [message] [throwable] | FlowKatOptimizableOperatorProxy 초기화 오류 | Reactor 내부 API 접근 불가. Reactor 버전 충돌 의심 |
R166 | ERROR | [message] [throwable] | Coroutine onError 처리 오류 | Kotlin Coroutine 추적 오류. hook_reactive_enabled=false 시도 |
R167p | ERROR | [message] [throwable] | Coroutine 컨텍스트 복원 오류 | 위와 동일 |
R201 | ERROR | [message] [throwable] | Coroutine support 초기화 오류 | Coroutine 버전 불일치 |
R1660 | ERROR | [message] [throwable] | Coroutine onError 내부 오류 | R166 발생 시 함께 확인 |
에이전트 부트/설정 (기타)
| 코드 | 심각도 | 메시지 패턴 | 의미 | 조치 |
|---|---|---|---|---|
B101 | ERROR | LambdaFormTransformer Error [throwable] | Lambda 변환 오류 | Java 8+ Lambda 계측 실패. hook_lambda_enabled=false 시도 |
SA-2001 | INFO | Load delayed service configure file : [path] | 지연 서비스 설정 파일 로드 | 정상 동작 |
SA-2002 | ERROR | Load error delayed service property file [throwable] | 지연 서비스 설정 파일 로드 실패 | 파일 경로/형식 확인 |
SA-2003 | INFO | Pass delayed checking... [txid] | 지연 서비스 임계값 미초과 통과 | 정상 동작 |
AG-K8S | INFO | Host agent name updated: [name] | K8s 호스트명 갱신 | 정상 동작 |
AG-K8S | WARN | Failed to check host agent name: [message] | K8s 호스트명 확인 실패 | K8s API 접근 권한 또는 네트워크 점검 |
Dashboard/API Server 로그 메시지 (API 서버)
API Server는 SLF4J 기반 로거(org.slf4j.Logger)를 사용하며, API 서버.framework.client.net 패키지의 Collect Server 연결 관련 로그가 주요 진단 대상이다.
| 코드/패턴 | 심각도 | 메시지 패턴 | 의미 | 조치 |
|---|---|---|---|---|
| - | INFO | Client Timeout Setting [timeout] | TCP 클라이언트 소켓 타임아웃 설정 | 정상 기동 로그 |
| - | INFO | Connected [this] to [ip]:[port] | Collect Server 연결 성공 | 정상 동작 |
| - | ERROR | [message] (ClientTCP) | Collect Server 연결 실패 | Collect Server 기동 상태 확인 |
| - | ERROR | Connection Open Failed for [ip]:[port] - [message] | Netty 연결 열기 실패 | Collect Server 가용성 및 포트 방화벽 확인 |
| - | INFO | Reconnecting TCP client to [ip]:[port] | Collect Server 재연결 시도 | 일시적 단절 후 복구 중. 지속 시 Collect Server 상태 점검 |
| - | INFO | TCP client is null for [ip]:[port], attempting reconnect... | 연결 객체 null로 재연결 시도 | 재연결 메커니즘 정상 동작 |
| - | WARN | Failed to dispose old ConnectionProvider for [ip]:[port]: [message] | 기존 연결 풀 정리 실패 | 리소스 누수 가능성. 로그 반복 시 서버 재시작 검토 |
| - | WARN | [ip]:[port] 연속 실패 [n]회 — Circuit Breaker 임계값([n]) 도달, reconnect 시도 | Circuit Breaker 발동, 재연결 | Collect Server 장애 또는 네트워크 단절. 서버 상태 우선 확인 |
| - | WARN | [ip]:[port] 풀 고활용 경고 — utilization=[n]%, max=[n], active=[n], pending=[n], failureCount=[n] | 연결 풀 고부하 경고 | API Server 동시 요청 과다. connection_pool_max_size 조정 검토 |
| - | ERROR | Connection Failed [throwable] | 연결 완전 실패 | Circuit Breaker 반복 실패 후 최종 실패. 인프라 점검 필요 |
| - | WARN | response message warn: [code]: [description] | 응답 코드 경고 | 서버 응답 코드 확인. 세션 만료 또는 권한 오류 |
| - | WARN | invalid session retry: [n], session: [id], invalidated: [bool] | 세션 무효화 재시도 | 세션 동기화 이슈. 대시보드 재로그인으로 복구 |
| - | ERROR | Handshake error: [message] [throwable] | TCP Handshake 오류 | 프로토콜 버전 불일치 또는 TLS 설정 오류. 버전 정합성 확인 |
| - | WARN | 세션 무효화 — 연결 장애 감지: session=[id], error=[msg] | 장애 감지 후 세션 강제 만료 | 연결 복구 시 자동 재인증 |
| - | WARN | Circuit Breaker 발동 — 연속 실패 [n]회, 풀 재생성 시도 | 연결 풀 재생성 | 반복 발동 시 Collect Server 안정성 점검 |
| - | ERROR | Server Start...Error [throwable] | API Server 기동 실패 | 포트 충돌, JVM 힙 부족, 설정 오류 점검 |
| - | ERROR | Fail to log in to [ip]:[port] | Collect Server 로그인 실패 | 인증 정보 또는 Collect Server 계정 설정 확인 |
| - | ERROR | TextLoader loadAll failed for serverId=[id] | 텍스트 데이터 일괄 로드 실패 | Collect Server 연결 상태 확인 |
| - | ERROR | [WebApplicationException] [status] - [message], [uri] | REST API 미처리 예외 | API 오류 내용 확인. 클라이언트 요청 파라미터 검증 |
| - | ERROR | [ErrorStateException] [status] - [code] - [message], [uri] | 비즈니스 오류 상태 예외 | 에러 코드별 원인 분석 필요 |
| - | ERROR | fetchObjectList error [throwable] | 에이전트 오브젝트 목록 조회 실패 | Collect Server 연결 또는 데이터 조회 오류 |
자주 발생하는 로그 패턴별 진단
Connection Refused / 연결 거부
Connection Open Failed for 172.18.0.x:6100 - Connection refused
원인: Collect Server 미기동 또는 포트 바인딩 실패.
조치:
docker compose ps collect-server상태 확인- Collect Server 로그에서
S167코드 확인 ss -tlnp | grep 6100으로 포트 바인딩 여부 확인
Handshake 오류
Handshake error: [message]
원인: 에이전트와 서버 버전 불일치, 또는 TLV 프레임 협상 실패.
조치:
- 에이전트 설정의 버전 정보와 서버 버전 비교
- 에이전트 재배포 후 재연결 확인
OOM / GC 관련
java.lang.OutOfMemoryError: Java heap space
에이전트 로그 또는 Collect Server 로그에서 OOM이 발생하면 다음을 확인한다:
| 서비스 | 기본 힙 (prod) | 조정 파라미터 |
|---|---|---|
| collect-server | -Xmx2g -Xms2g | .env의 COLLECT_JVM_OPTS |
| api-server | -Xmx1g -Xms1g | .env의 API_JVM_OPTS |
Queue Exceeded (큐 포화)
S109, S110, S111, S113, S115 등 queue exceeded 계열 로그가 반복되면 수집 서버의 처리 속도가 에이전트 전송 속도를 따라가지 못하는 상태다.
단기 조치: Collect Server JVM 힙 증가 중기 조치: 에이전트 수집 주기 조정 (counter_send_interval_ms), 불필요한 수집 항목 비활성화
TCP Timeout
V3 REQ timeout: [cmd]
net_collector_tcp_so_timeout_ms: 60000
에이전트 REQ 명령(스레드 덤프, 힙 덤프 등)이 60초 내에 응답하지 않으면 타임아웃이 발생한다. 에이전트 JVM의 Full GC 또는 CPU 과부하 상태일 때 주로 나타난다.
관련 문서
- 로그 수집 설정: 31.log-collection.md
- 장애 대응 흐름: 30.troubleshooting-flow.md
- Collect Server 상세: 14.collect-server.md
- Java 에이전트 상세: 10.agent-java.md