Java Agent 설치 및 파라미터
Java 8+ 애플리케이션 서버에 설치하는 바이트코드 인스트루먼테이션 에이전트이다. JVM 옵션으로 -javaagent를 추가하여 트랜잭션 추적, SQL 프로파일링, Active Thread 모니터링을 수행한다.
1. 개요
| 항목 | 내용 |
|---|---|
| 배포 위치 | 고객 애플리케이션 서버 (/opt/flowkat/agent.java) |
| 프로세스 형태 | 대상 JVM에 -javaagent로 연결 (별도 프로세스 아님) |
| 의존 모듈 | Collect Server TCP 6100 연결 필요 |
| 로그 위치 | $AGENT_HOME/logs/ |
2. 필수 설정 (P0)
고객 설명 포인트
"고객님, 에이전트 설치는 간단합니다. 파일 복사 후 설정 파일에서 수집 서버 주소와 에이전트 이름 두 가지만 정확히 입력하시면 됩니다. 나머지는 자동 감지됩니다."
P0 파라미터를 잘못 설정하면 에이전트 데이터가 수집 서버에 전송되지 않는다.
| 파라미터 | 타입 | 기본값 | conf 키 | 중요도 | 설명 |
|---|---|---|---|---|---|
net_collector_ip | String | 127.0.0.1 | net_collector_ip | 필수 | 수집 서버 IP. Docker bridge 모드에서는 172.17.0.1, host 모드에서는 127.0.0.1. ConfObserver로 런타임 변경 가능. |
net_collector_tcp_port | int | 6100 | net_collector_tcp_port | 필수 | 수집 서버 TCP 포트. NetConstants.SERVER_TCP_PORT 상수. 수집 서버의 net_tcp_listen_port와 일치해야 한다. |
obj_name | String | "" | obj_name | 필수 | 대시보드 표시 에이전트 이름. 같은 수집 서버에 연결된 에이전트 간 고유해야 한다. 미설정 시 obj_type + "1" (예: tomcat1). |
obj_type | String | "" | obj_type | 필수 | 오브젝트 그룹 타입. monitoring_group_type이 신규 키이며 obj_type은 deprecated alias. 미설정 시 WAS 타입 자동 감지. |
monitoring_group_type | String | "" | monitoring_group_type | 필수 | 모니터링 그룹 타입 (신규 키). 설정 시 obj_type을 오버라이드한다. |
obj_host_name | String | "" | obj_host_name | 필수 | 호스트 이름. 미설정 시 OS 호스트네임 자동 감지. K8s에서는 Host Agent 이름 동기화. |
3. 운영 튜닝 (P1 핵심)
| 파라미터 | 타입 | 기본값 | conf 키 | 중요도 | 설명 |
|---|---|---|---|---|---|
net_collector_tcp_session_count | int | 1 | net_collector_tcp_session_count | 핵심 | 수집 서버 동시 TCP 세션 수. 수천 TPS 이상에서 2~3으로 증가 가능. |
net_collector_tcp_so_timeout_ms | int | 60000 | net_collector_tcp_so_timeout_ms | 핵심 | TCP 소켓 SO_TIMEOUT(ms). |
net_collector_tcp_connection_timeout_ms | int | 3000 | net_collector_tcp_connection_timeout_ms | 핵심 | TCP 연결 수립 타임아웃(ms). 글로벌 IDC 간에서는 5000~10000 고려. |
net_collector_tcp_reconnect_initial_delay_ms | int | 1000 | net_collector_tcp_reconnect_initial_delay_ms | 핵심 | V3 TCP 재연결 첫 재시도 대기(ms). Exponential backoff 시작점. |
net_collector_tcp_reconnect_max_delay_ms | int | 30000 | net_collector_tcp_reconnect_max_delay_ms | 핵심 | 재연결 backoff 최대 대기(ms). |
net_collector_tcp_reconnect_max_retry | int | 30 | net_collector_tcp_reconnect_max_retry | 핵심 | Exponential backoff 최대 횟수. 소진 후 주기적 재시도로 전환. |
net_collector_tcp_reconnect_periodic_retry_ms | long | 300000 | net_collector_tcp_reconnect_periodic_retry_ms | 핵심 | max_retry 소진 후 주기적 재시도 간격(ms). |
net_tcp_batch_max_bytes | int | 60000 | net_tcp_batch_max_bytes | 핵심 | TCP 배치 전송 최대 바이트. |
trace_activeservice_yellow_time | long | 3000 | trace_activeservice_yellow_time | 핵심 | Active Thread 노란색(경고) 기준(ms). 구 키 trace_activeserivce_yellow_time 폴백 지원. |
trace_activeservice_red_time | long | 8000 | trace_activeservice_red_time | 핵심 | Active Thread 빨간색(위험) 기준(ms). |
profile_step_max_count | int | 1024 | profile_step_max_count | 핵심 | 트랜잭션당 프로파일 스텝 최대 수 (최소 128). 복잡한 트랜잭션에서 2048~4096. |
profile_step_max_keep_in_memory_count | int | 2048 | profile_step_max_keep_in_memory_count | 핵심 | 프로파일 메모리 유지 최대 스텝 수 (최소 128). |
xlog_error_jdbc_fetch_max | int | 10000 | xlog_error_jdbc_fetch_max | 핵심 | JDBC fetch 건수 초과 시 XLog 에러 마킹 기준. |
xlog_error_sql_time_max_ms | int | 30000 | xlog_error_sql_time_max_ms | 핵심 | SQL 실행 시간 초과 시 XLog 에러 마킹 기준(ms). |
trace_user_mode | int | 2 | trace_user_mode | 핵심 | 사용자 식별 (0:IP, 1:JSESSIONID, 2:FlowKat Cookie, 3:Header). |
profile_force_end_stuck_millis | int | 300000 | profile_force_end_stuck_millis | 핵심 | 스턱 서비스 강제 종료 시간(ms). 무한 루프/데드락 방어. |
control_reject_service_max_count | int | 10000 | control_reject_service_max_count | 핵심 | Active Service 초과 시 신규 요청 거부 기준. |
전체 145개 파라미터 레퍼런스 (그룹별 동작 원리, 연관 관계 포함): 10-1.agent-java-params.md 파라미터 인벤토리 원본: parameter-inventory.md
4. 설치 절차
현장 체크리스트
- 고객 서버 JDK 버전 확인 (
java -version) — JDK 8 이상이면agent.java, JDK 6/7이면agent.java_6_7 - 수집 서버 IP 및 6100 포트 연결 가능 여부 확인 (
nc -zv <수집서버IP> 6100) - 에이전트 디렉토리 배포 경로 확인 (권장:
/opt/flowkat/agent.java) - WAS 재시작 가능 시간 확인 (고객사 변경 관리 절차 확인)
-
flowkat.conf에 P0 파라미터 4개 설정 완료 (net_collector_ip,net_collector_tcp_port,obj_name,monitoring_group_type) - WAS 재시작 후 대시보드 센트리 화면에서 에이전트 녹색 아이콘 확인
사전 요건
- Java 8 이상 (JDK 6/7은
agent.java_6_7사용) - Collect Server 기동 및 TCP 6100 포트 개방
설치 단계
# 1. 에이전트 디렉토리 복사
cp -r agent.java /opt/flowkat/agent.java
# 2. 설정 파일 수정 (P0 파라미터)
vi /opt/flowkat/agent.java/conf/flowkat.conf
# 3. JVM 옵션에 -javaagent 추가
# Tomcat: catalina.sh 또는 setenv.sh에 추가
export JAVA_OPTS="$JAVA_OPTS -javaagent:/opt/flowkat/agent.java/flowkat.agent.jar"
# 4. 애플리케이션 서버 재시작
./shutdown.sh && ./startup.sh
# 5. 기동 확인
tail -f /opt/flowkat/agent.java/logs/flowkat.log
기동 확인
# 프로세스에 javaagent 옵션 확인
ps -ef | grep javaagent | grep flowkat
# 수집 서버 연결 확인
netstat -tnp | grep 6100
5. 설정 파일 예시
최소 운영 설정 (P0만 변경)
# /opt/flowkat/agent.java/conf/flowkat.conf
# P0: 수집 서버 주소 (필수 변경)
net_collector_ip=192.168.1.100
net_collector_tcp_port=6100
# P0: 에이전트 식별 (필수 변경 - 인스턴스 간 고유)
obj_name=prod-order-api-01
monitoring_group_type=ORDER-API
운영 환경 설정 예시
# P0
net_collector_ip=192.168.1.100
net_collector_tcp_port=6100
obj_name=prod-order-api-01
monitoring_group_type=ORDER-API
# P1: 프로파일 튜닝
profile_step_max_count=2048
trace_activeservice_yellow_time=5000
trace_activeservice_red_time=10000
xlog_error_sql_time_max_ms=60000
6. 주의사항
고객 질문 예시
Q: "에이전트 설치하면 우리 애플리케이션 성능에 영향이 있나요?"
A: "에이전트는 바이트코드 인스트루먼테이션 방식으로 동작하며, CPU 오버헤드는 13% 수준입니다. 메모리는 에이전트 자체가 약 50100MB 정도 추가 사용합니다. 운영 중인 대부분의 고객사에서 체감 성능 차이를 느끼지 못하고 계십니다."
Q: "에이전트 설치 후 WAS를 재시작해야 하나요?"
A: "네, -javaagent 옵션은 JVM 시작 시 적용되므로 WAS 재시작이 필요합니다. 무중단 배포 환경이시라면 롤링 재시작으로 서비스 영향 없이 적용 가능합니다."
| 상황 | 주의 내용 |
|---|---|
| trace_activeservice 하위 호환 | trace_activeservice_yellow_time(정식 키) + trace_activeserivce_yellow_time(구 오타 키 폴백) 양쪽 지원. 신규 설정 시 trace_activeservice_yellow_time 사용 권장. |
| trace_propagete_b3_header | propagete는 오타가 아니라 profile trace 목적의 의도된 키명이다. propagate로 변경하면 적용되지 않는다. |
| obj_name 중복 | 같은 수집 서버에 동일 obj_name 연결 시 system_on_object_duplicate 알림 발생. |
| mgr_purge 연쇄 | 수집 서버의 mgr_purge_profile_keep_days(10일) 기반으로 xlog(x3=30일), counter(x7=70일) 기본값이 연쇄 계산된다. |
| K8s 환경 | obj_host_name_follow_host_agent=true(기본) 시 Host Agent 이름에 자동 동기화. Pod 이름에서 순차 번호 suffix 자동 추가. |
7. 관련 문서
- 전체 파라미터 목록: parameter-inventory.md
- 검증 결과: parameter-inventory-verified.md
- 수집 서버 설정: 14.collect-server.md
- 네트워크/포트: 17.network-ports.md
8. Java 에이전트 사양
Java 에이전트는 대상 JVM에 -javaagent로 연결되므로 독립 프로세스가 없다. 아래 수치는 대상 JVM에 추가되는 오버헤드이다.
| 리소스 | 항목 | 추정값 | 비고 |
|---|---|---|---|
| 메모리 | JVM Metaspace 증가 | +30~50 MB | BCI(바이트코드 변환) 클래스 로딩으로 인한 Metaspace 오버헤드 |
| 메모리 | Heap 증가 | +20~40 MB | 트랜잭션 컨텍스트 버퍼, 프로파일 스텝 큐 (profile_step_max_keep_in_memory_count=2048 기준) |
| CPU | 프로파일링 비활성 | < 0.5% | BCI 후킹만 활성화된 상태 |
| CPU | 프로파일링 활성 | 1~3% | profile_step_max_count 증가 시 상향 가능 |
| 디스크 | 로그 파일 위치 | $AGENT_HOME/logs/flowkat.log | Java 에이전트/conf/flowkat.conf의 log_dir 파라미터로 변경 가능 |
| 디스크 | 일 로그 크기 | ~10~50 MB/일 | TPS·프로파일 수집량에 비례. log_keep_days=7(기본) 기준 최대 350 MB |
| 디스크 | Collect Server 연결 실패 시 로컬 버퍼 | 없음 (메모리 큐) | 연결 끊김 시 메모리 내 큐에 누적. Exponential backoff 재연결(net_collector_tcp_reconnect_max_retry=30) 후 소진 시 데이터 유실 |
| 네트워크 | TCP 6100 대역폭 | 1~10 KB/초 per agent | XLog·Counter 혼합 전송 기준. 고 TPS(1000+) 환경에서 최대 ~50 KB/초 |
| 네트워크 | TCP 세션 수 | 기본 1 (net_collector_tcp_session_count) | 수천 TPS 이상에서 2~3으로 조정 |