Java 에이전트 성능 영향 옵션 가이드
Java 에이전트(Java 에이전트)는 BCI(바이트코드 인스트루먼테이션) 방식으로 동작한다. 에이전트가 삽입하는 계측 코드는 애플리케이션 성능에 직접 영향을 준다. 이 문서는 고부하 환경이나 부하 테스트 수행 시 에이전트 오버헤드를 최소화하기 위한 옵션을 기술한다.
1. 개요
대상 사용 시나리오
| 시나리오 | 설명 |
|---|---|
| 부하 테스트 (Load Test) | JMeter, Gatling 등으로 TPS 측정 시 에이전트 오버헤드를 제거해 순수 애플리케이션 성능을 측정한다 |
| 고부하 운영 환경 | 피크 트래픽 시 에이전트에 의한 응답 지연 및 CPU 증가를 줄인다 |
| 초기 설치 후 검증 | 에이전트 적용 전/후 성능 비교 측정 시 기준을 맞춘다 |
성능 영향 원리
에이전트가 성능 영향을 주는 경로는 3가지다.
1. BCI 오버헤드
JVM 기동 시 클래스 로딩 단계에서 대상 클래스에 계측 코드를 삽입한다.
hook_method_patterns, hook_service_patterns 대상 클래스 수에 비례한다.
2. 프로파일 데이터 수집 오버헤드
트랜잭션 실행 중 SQL, 메서드 호출 정보를 메모리에 기록한다.
profile_step_max_count 값이 클수록, SQL/메서드 호출 수가 많을수록 증가한다.
3. 네트워크 전송 오버헤드
수집된 프로파일 데이터를 Collect Server로 TCP 전송한다.
xlog_sampling_enabled=false이면 모든 트랜잭션 데이터를 전송한다.
2. 성능 영향 등급
등급 정의
| 등급 | 설명 | 부하 테스트 권장 |
|---|---|---|
| 높음 | 비활성화 시 TPS 5~20% 이상 향상 가능. 계측 오버헤드가 크다 | 비활성화 권장 |
| 중간 | 트래픽 규모와 설정값에 따라 영향도 다름. 상황별 조정 필요 | 상황에 따라 조정 |
| 낮음 | 기본값으로 운영 가능. 변경 시 모니터링 기능이 축소된다 | 기본값 유지 |
3. 옵션별 상세 가이드
3.1 프로파일링 관련
트랜잭션 내 SQL, 메서드 호출 상세 정보를 기록하는 계층이다. 수집 단계에서 메모리 할당과 직렬화가 발생한다.
| 파라미터 | 기본값 | 성능 영향 | 부하 테스트 시 권장값 | 설명 |
|---|---|---|---|---|
profile_method_enabled | true | 높음 | false | 메서드 프로파일 수집 여부. 비활성화하면 hook_method_patterns에 등록된 메서드 계측이 비활성화된다 |
profile_step_max_count | 1024 | 높음 | 128 | 트랜잭션당 프로파일 스텝 최대 수. 줄이면 수집 데이터가 감소하고 메모리 할당도 줄어든다. 최소 128 |
profile_step_max_keep_in_memory_count | 2048 | 중간 | 256 | 메모리 내 유지 스텝 수. profile_step_max_count 이하로 설정하면 의미 없다. 최소 128 |
profile_connection_open_enabled | true | 중간 | false | DB 커넥션 획득 이벤트를 프로파일에 기록한다. 커넥션 풀 환경에서 실질적 영향은 낮다 |
profile_sql_escape_enabled | true | 낮음 | true | SQL 파라미터 리터럴 정규화(이스케이프). CPU 부하는 낮으나 비활성화하면 SQL 통계 정확도가 저하된다 |
profile_sqlmap_name_enabled | true | 낮음 | true | MyBatis SQL Map ID를 프로파일에 기록한다. 비활성화해도 성능 개선은 미미하다 |
profile_http_querystring_enabled | false | 낮음 | false | HTTP 쿼리 스트링을 프로파일에 기록한다. 기본값이 false이므로 부하 테스트에서도 그대로 유지한다 |
profile_http_header_enabled | false | 낮음 | false | HTTP 헤더를 프로파일에 기록한다. 기본값 false 유지 권장 |
3.2 XLog 샘플링 관련
XLog는 트랜잭션 단위 로그이며 Collect Server로 전송된다. 모든 트랜잭션을 전송하면 네트워크 및 서버 처리 부하가 증가한다.
| 파라미터 | 기본값 | 성능 영향 | 부하 테스트 시 권장값 | 설명 |
|---|---|---|---|---|
xlog_sampling_enabled | false | 높음 | true | XLog 소프트 샘플링 활성화. 빠른 트랜잭션의 전송 비율을 낮춰 네트워크/서버 부하를 줄인다 |
xlog_sampling_step1_ms | 100 | 높음 | 100 | 샘플링 1구간 상한(ms). step1(0~100ms)의 트랜잭션은 step1_rate_pct 비율만 전송한다 |
xlog_sampling_step1_rate_pct | 3 | 높음 | 1 | step1 전송 비율(%). 부하 테스트 시 1%로 줄이면 대부분의 빠른 트랜잭션이 샘플링된다 |
xlog_sampling_step2_ms | 1000 | 중간 | 1000 | 샘플링 2구간 상한(ms) |
xlog_sampling_step2_rate_pct | 10 | 중간 | 5 | step2 전송 비율(%). |
xlog_sampling_step3_ms | 3000 | 중간 | 3000 | 샘플링 3구간 상한(ms) |
xlog_sampling_step3_rate_pct | 30 | 중간 | 10 | step3 전송 비율(%) |
xlog_sampling_over_rate_pct | 100 | 중간 | 100 | step3 초과 구간 전송 비율(%). 느린 트랜잭션은 100% 수집 유지 권장 |
xlog_sampling_only_profile | false | 중간 | true | true이면 XLog 메타는 전송하고 프로파일 상세만 샘플링으로 제거한다. 통계 정확도 유지에 유리하다 |
_xlog_hard_sampling_enabled | false | 높음 | 주의 필요 | 하드 샘플링. 비율 초과 트랜잭션은 계측 자체를 건너뛴다. 통계 데이터까지 영향을 주므로 운영 환경에서는 사용에 주의한다 |
_xlog_hard_sampling_rate_pct | 10 | 높음 | - | 하드 샘플링 비율(%). _xlog_hard_sampling_enabled=true 시 적용된다 |
3.3 메서드 후킹 관련
BCI는 JVM 기동 시 1회 적용된다. 그러나 후킹 대상이 많을수록 클래스 변환 시간과 메서드 진입/종료 시 인터셉터 오버헤드가 누적된다.
| 파라미터 | 기본값 | 성능 영향 | 부하 테스트 시 권장값 | 설명 |
|---|---|---|---|---|
hook_method_patterns | "" | 높음 | "" (빈 값) | 커스텀 메서드 후킹 패턴. 지정된 패턴의 모든 메서드에 계측 코드를 삽입한다. 부하 테스트 시 빈 값으로 초기화한다 |
hook_method_access_public_enabled | true | 중간 | false | public 메서드 자동 후킹 여부. hook_method_patterns와 함께 적용된다 |
hook_method_access_private_enabled | false | 낮음 | false | private 메서드 후킹. 기본값 false 유지 |
hook_method_access_protected_enabled | false | 낮음 | false | protected 메서드 후킹. 기본값 false 유지 |
_hook_methods_enabled | true | 높음 | false | 메서드 후킹 전체 활성화 토글. false로 설정하면 hook_method_patterns 후킹이 일괄 비활성화된다 |
hook_method_ignore_prefixes | "get,set" | 낮음 | "get,set" | 후킹 제외 메서드 prefix. getter/setter는 기본 제외되어 있다 |
hook_spring_async_enabled | true | 중간 | false | Spring @Async 메서드 추적 활성화. 비동기 처리가 많은 환경에서 부하 테스트 시 비활성화를 검토한다 |
3.4 외부 연동 후킹 관련
Redis, Kafka, Elasticsearch 등 외부 시스템 호출을 추적하는 후킹이다. 호출 빈도가 높은 환경에서 오버헤드가 누적된다.
| 파라미터 | 기본값 | 성능 영향 | 부하 테스트 시 권장값 | 설명 |
|---|---|---|---|---|
_hook_redis_enabled | true | 중간 | false | Redis 호출 추적. 캐시 호출이 빈번한 환경에서 오버헤드가 존재한다 |
_hook_kafka_enabled | true | 중간 | false | Kafka 프로듀서/컨슈머 추적 |
_hook_elasticsearch_enabled | true | 중간 | false | Elasticsearch 호출 추적 |
hook_mongodb_enabled | false | 낮음 | false | MongoDB 호출 추적. 기본값 false 유지 |
_hook_apicall_enabled | true | 중간 | false | HTTP API 아웃바운드 호출 추적 (RestTemplate, WebClient 등). 마이크로서비스 환경에서 호출이 많은 경우 영향이 크다 |
_hook_socket_enabled | true | 낮음 | true | 소켓 추적. 기본값 유지 권장 |
_hook_dbsql_enabled | true | 낮음 | true | DB SQL 추적. 비활성화하면 SQL 프로파일이 전혀 수집되지 않는다. 부하 테스트 중에도 유지 권장 |
3.5 Auto Dump 관련
Active Thread 임계치 초과 시 스레드 덤프를 자동 생성한다. 덤프 자체는 JVM Thread.getAllStackTraces()를 호출하며 Stop-The-World를 유발할 수 있다.
| 파라미터 | 기본값 | 성능 영향 | 부하 테스트 시 권장값 | 설명 |
|---|---|---|---|---|
autodump_enabled | false | 높음 | false | Auto Dump 활성화. 활성화 상태이면 Active Thread 임계치 초과 시 JVM Thread Dump가 발생한다. 부하 테스트 중에는 반드시 비활성화한다 |
autodump_trigger_active_service_cnt | 10000 | 높음 | - | Auto Dump 트리거 Active Thread 수. autodump_enabled=true 시에만 의미가 있다 |
autodump_cpu_exceeded_enabled | false | 높음 | false | CPU 임계치 초과 시 덤프 생성. 부하 테스트 시 CPU 높은 환경에서 의도치 않은 덤프가 발생할 수 있다 |
autodump_stuck_thread_ms | 0 | 중간 | 0 | 스턱 스레드 감지 후 덤프 시간(ms). 0이면 비활성화. 기본값 유지 |
3.6 카운터 및 Active Service 관련
카운터는 TPS, 응답시간, CPU 등 집계 메트릭을 주기적으로 수집한다. Active Service는 현재 실행 중인 트랜잭션 목록이다.
| 파라미터 | 기본값 | 성능 영향 | 부하 테스트 시 권장값 | 설명 |
|---|---|---|---|---|
counter_enabled | true | 낮음 | true | 카운터 수집 활성화. 비활성화하면 TPS, 응답시간 등 기본 메트릭이 수집되지 않는다. 부하 테스트에서도 유지 권장 |
trace_activeservice_yellow_time | 3000 | 낮음 | 3000 | Active Thread 노란색 기준(ms). 부하 테스트 응답시간이 높으면 알람 레벨을 높인다 |
trace_activeservice_red_time | 8000 | 낮음 | 8000 | Active Thread 빨간색 기준(ms) |
control_reject_service_enabled | false | 낮음 | false | Active Transaction 초과 시 신규 요청 거부. 부하 테스트 시 비활성화 유지 필수. 활성화하면 부하 테스트 결과가 왜곡된다 |
4. 부하 테스트 시 권장 설정
부하 테스트 목적에 따라 두 가지 모드를 제공한다.
모드 A: 에이전트 최소화 (순수 성능 측정)
에이전트 영향을 최소화해 애플리케이션 순수 TPS를 측정할 때 사용한다.
# /opt/flowkat/agent.java/conf/flowkat.conf
# 부하 테스트 모드 A - 에이전트 최소화
# --- 프로파일링 축소 ---
profile_method_enabled=false
profile_step_max_count=128
profile_step_max_keep_in_memory_count=256
profile_connection_open_enabled=false
# --- XLog 샘플링 활성화 ---
xlog_sampling_enabled=true
xlog_sampling_only_profile=true
xlog_sampling_step1_ms=100
xlog_sampling_step1_rate_pct=1
xlog_sampling_step2_ms=1000
xlog_sampling_step2_rate_pct=5
xlog_sampling_step3_ms=3000
xlog_sampling_step3_rate_pct=10
xlog_sampling_over_rate_pct=100
# --- 메서드 후킹 비활성화 ---
_hook_methods_enabled=false
hook_method_patterns=
hook_method_access_public_enabled=false
# --- 외부 연동 추적 비활성화 ---
_hook_redis_enabled=false
_hook_kafka_enabled=false
_hook_elasticsearch_enabled=false
_hook_apicall_enabled=false
hook_spring_async_enabled=false
# --- Auto Dump 비활성화 ---
autodump_enabled=false
autodump_cpu_exceeded_enabled=false
# --- 트래픽 제어 비활성화 (부하 테스트 왜곡 방지) ---
control_reject_service_enabled=false
모드 B: 모니터링 유지 + 오버헤드 최소화
부하 테스트 중에도 TPS, 응답시간 모니터링을 유지하면서 오버헤드를 줄일 때 사용한다.
# /opt/flowkat/agent.java/conf/flowkat.conf
# 부하 테스트 모드 B - 모니터링 유지 + 오버헤드 최소화
# --- 프로파일링 제한 ---
profile_method_enabled=false
profile_step_max_count=256
profile_step_max_keep_in_memory_count=512
# --- XLog 샘플링 (통계는 유지, 상세 프로파일만 샘플링) ---
xlog_sampling_enabled=true
xlog_sampling_only_profile=true
xlog_sampling_step1_rate_pct=3
xlog_sampling_step2_rate_pct=10
xlog_sampling_step3_rate_pct=30
xlog_sampling_over_rate_pct=100
# --- Auto Dump 비활성화 ---
autodump_enabled=false
autodump_cpu_exceeded_enabled=false
# --- 트래픽 제어 비활성화 ---
control_reject_service_enabled=false
# 나머지는 기본값 유지 (SQL 추적, DB 커넥션 추적 등)
5. 고부하 운영 환경 최적화
운영 환경에서 에이전트 오버헤드가 감지되면 아래 순서로 조정한다.
5.1 오버헤드 감지 기준
에이전트 영향이 의심되는 증상이다.
1. 에이전트 적용 후 TPS가 5% 이상 감소하거나 응답시간이 증가한다
2. JVM CPU 사용률이 에이전트 적용 전 대비 3% 이상 증가한다
3. GC 빈도가 증가하고 Old Gen 사용량이 늘어난다 (프로파일 버퍼 누수 의심)
4. Collect Server 전송 큐가 지속적으로 누적된다
5.2 단계별 튜닝 절차
STEP 1: XLog 샘플링 활성화
xlog_sampling_enabled=true
xlog_sampling_only_profile=true
xlog_sampling_step1_rate_pct=3 (0~100ms 구간 3% 전송)
→ 네트워크 전송량 50~70% 감소. 통계 정확도는 유지된다.
STEP 2: 프로파일 스텝 수 축소
profile_step_max_count=512 (기본 1024 → 512)
profile_step_max_keep_in_memory_count=1024
→ 메모리 할당 감소. 복잡한 트랜잭션의 프로파일이 잘릴 수 있다.
STEP 3: 메서드 후킹 패턴 검토
hook_method_patterns 를 확인하여 불필요한 패키지 제거
hook_method_access_public_enabled=false (광범위한 public 후킹 비활성화)
→ BCI 오버헤드 감소. 메서드 프로파일 범위가 좁아진다.
STEP 4: 외부 연동 추적 선택적 비활성화
_hook_redis_enabled=false (Redis 호출이 매우 빈번한 경우)
_hook_apicall_enabled=false (API 아웃바운드 호출이 많은 경우)
→ 각 후킹 포인트 인터셉터 오버헤드 제거. 연동 추적 기능이 비활성화된다.
STEP 5: Auto Dump 임계치 상향
autodump_trigger_active_service_cnt=30000 (기본 10000 → 30000)
→ 과도한 Thread Dump 방지. 실제 장애 감지가 늦어질 수 있다.
5.3 조정 후 검증
# 에이전트 로그에서 전송 건수 확인
tail -f /opt/flowkat/agent.java/logs/flowkat.log | grep "xlog"
# JVM 메모리/GC 확인
jstat -gcutil <PID> 5000
# Collect Server 수신 현황 (서버 측)
tail -f $FLOWKAT_SERVER_HOME/logs/collector.log | grep "recv"
6. 주의사항
6.1 운영 환경에서 비활성화하면 안 되는 옵션
아래 옵션은 비활성화 시 핵심 모니터링 기능이 상실된다.
| 파라미터 | 이유 |
|---|---|
counter_enabled | false로 설정하면 TPS, 응답시간 등 모든 기본 메트릭이 수집되지 않는다. 대시보드 카운터 차트가 공백이 된다 |
_hook_serivce_enabled | false로 설정하면 서비스(HTTP 요청) 추적이 전혀 되지 않는다. XLog, Active Thread, 트랜잭션 정보가 모두 비활성화된다 |
_hook_dbsql_enabled | false로 설정하면 SQL 추적이 비활성화된다. DB 관련 성능 분석이 불가능해진다 |
xlog_sampling_over_rate_pct | 100% 미만으로 설정하면 느린 트랜잭션(장애 가능성 높음)도 샘플링에서 제외된다. 100% 유지 필수 |
6.2 부하 테스트 후 운영 복구 절차
부하 테스트 완료 후 반드시 운영 설정으로 복구한다.
# 1. 부하 테스트 설정 백업 저장
cp /opt/flowkat/agent.java/conf/flowkat.conf \
/opt/flowkat/agent.java/conf/flowkat.conf.loadtest.bak
# 2. 운영 설정으로 복원
cp /opt/flowkat/agent.java/conf/flowkat.conf.prod \
/opt/flowkat/agent.java/conf/flowkat.conf
# 3. ConfObserver 실시간 반영 확인 (재시작 불필요)
# flowkat.conf 변경 후 약 5~10초 내에 자동 반영된다.
# 에이전트 로그에서 "Reloaded" 메시지 확인
tail -f /opt/flowkat/agent.java/logs/flowkat.log | grep -i "reload\|config"
ConfObserver 실시간 반영 주의사항:
- BCI(바이트코드 인스트루먼테이션) 관련 파라미터는 재시작이 필요하다.
해당 파라미터: hook_method_patterns, hook_service_patterns,
hook_jdbc_pstmt_classes, hook_method_access_*_enabled
- 런타임 반영 가능한 파라미터:
profile_step_max_count, xlog_sampling_enabled,
trace_activeservice_yellow_time, trace_activeservice_red_time,
autodump_enabled, counter_enabled 등
- hook_ 계열 패턴 변경 후 즉시 JVM 재시작을 수행한다.
6.3 하드 샘플링 사용 주의
_xlog_hard_sampling_enabled=true는 성능 영향이 가장 크지만 통계 데이터에도 영향을 준다.
소프트 샘플링 (xlog_sampling_enabled=true):
- XLog 전송량만 줄인다.
- TPS, 응답시간 통계는 100% 수집된다.
- 운영 환경 권장 방식이다.
하드 샘플링 (_xlog_hard_sampling_enabled=true):
- 비율 초과 트랜잭션의 계측 자체를 건너뛴다.
- TPS, 사용자 수 등 통계 데이터도 과소 집계된다.
- 순수 성능 측정 목적의 부하 테스트에서만 사용한다.
- 운영 환경에서는 사용을 금지한다.
7. 핵심 파라미터 요약
| 파라미터 | 타입 | 기본값 | conf 키 | 중요도 | 설명 |
|---|---|---|---|---|---|
profile_method_enabled | boolean | true | profile_method_enabled | 필수 | 메서드 프로파일 수집. 부하 테스트 시 false 권장 |
profile_step_max_count | int | 1024 | profile_step_max_count | 핵심 | 트랜잭션당 프로파일 스텝 최대 수 |
xlog_sampling_enabled | boolean | false | _xlog_sampling_enabled | 핵심 | XLog 샘플링 활성화 (히든 파라미터) |
xlog_sampling_rate_pct | int | 100 | _xlog_sampling_rate_pct | 핵심 | XLog 샘플링 비율(%) |
counter_send_interval_ms | int | 5000 | counter_send_interval_ms | 고급 | 카운터 전송 주기(ms). 증가 시 네트워크 부하 감소 |
trace_activeservice_yellow_time | int | 3000 | trace_activeservice_yellow_time | 고급 | 액티브 서비스 옐로 임계값(ms) |
전체 파라미터 상세: 10-1.agent-java-params.md, 10-2.agent-java-params-advanced.md
8. 관련 문서
| 문서 | 설명 |
|---|---|
| 10.agent-java.md | Java Agent 설치 및 P0/P1 핵심 파라미터 |
| 10-1.agent-java-params.md | Java Agent 파라미터 기본편 (P0/P1 상세) |
| 10-2.agent-java-params-advanced.md | Java Agent 파라미터 고급편 (P2/P3) |
| 14.collect-server.md | Collect Server 설정 |
| parameter-inventory.md | 전체 파라미터 인벤토리 |