Java Agent 파라미터 (고급편)

Java Agent P2/P3 고급 파라미터 레퍼런스

기본 파라미터(P0/P1)는 10-1.agent-java-params.md 참조.

---

3. 프로파일링 고급 (Profiling Advanced)

트랜잭션 내부의 SQL, HTTP, 메서드 호출 등 상세 스텝을 기록하는 고급 파라미터이다. 버퍼 순환 및 Stuck 강제 종료 동작 원리는 10-1.agent-java-params.md를 참조한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
profile_http_header_enabled	boolean	false	profile_http_header_enabled	고급	HTTP 요청 헤더를 프로파일에 기록한다.
profile_http_header_url_prefix	String	""	profile_http_header_url_prefix	고급	특정 URL prefix에만 HTTP 헤더를 기록한다. 빈 값이면 전체 URL 대상이다.
profile_http_parameter_enabled	boolean	false	profile_http_parameter_enabled	고급	HTTP 요청 파라미터를 프로파일에 기록한다. 민감 데이터 노출에 주의한다.
profile_http_querystring_enabled	boolean	false	profile_http_querystring_enabled	고급	HTTP 쿼리 스트링을 프로파일에 기록한다.
profile_connection_open_enabled	boolean	true	profile_connection_open_enabled	고급	JDBC Connection open 이벤트를 프로파일에 기록한다.
profile_connection_close_enabled	boolean	false	profile_connection_close_enabled	참조	JDBC Connection close 이벤트를 프로파일에 기록한다.
profile_connection_autocommit_status_enabled	boolean	false	profile_connection_autocommit_status_enabled	참조	JDBC Connection autocommit 상태를 프로파일에 기록한다.
profile_method_enabled	boolean	true	profile_method_enabled	고급	메서드 프로파일링 활성화. hook_method_patterns와 함께 동작한다.
profile_sql_escape_enabled	boolean	true	profile_sql_escape_enabled	고급	SQL 파라미터 바인딩 시 이스케이프 처리를 수행한다. XSS 방지 목적이다.
profile_fullstack_enabled	boolean	false	profile_fullstack_enabled	고급	전체 스택 트레이스를 프로파일에 포함한다. 디버깅 시 일시적으로 활성화한다.
profile_fullstack_max_lines	int	0	profile_fullstack_max_lines	참조	전체 스택 트레이스 최대 라인 수. 0이면 제한 없음이다.
profile_fullstack_hooked_exception_enabled	boolean	false	profile_fullstack_hooked_exception_enabled	참조	Hook된 예외에 대해 전체 스택 트레이스를 기록한다.
profile_fullstack_rs_leak_enabled	boolean	false	profile_fullstack_rs_leak_enabled	참조	ResultSet 누수 감지 시 전체 스택 트레이스를 기록한다.
profile_fullstack_stmt_leak_enabled	boolean	false	profile_fullstack_stmt_leak_enabled	참조	Statement 누수 감지 시 전체 스택 트레이스를 기록한다.
profile_force_end_stuck_alert	boolean	true	profile_force_end_stuck_alert	고급	스턱 서비스 강제 종료 시 Alert을 전송한다.
profile_force_end_stuck_with_interrupt	boolean	false	profile_force_end_stuck_with_interrupt	고급	스턱 서비스 강제 종료 시 Thread.interrupt()를 호출한다. 부작용에 주의한다.
profile_elasticsearch_enabled	boolean	true	profile_elasticsearch_enabled	고급	Elasticsearch 호출을 프로파일에 기록한다.
profile_reactor_first_backpressure_enabled	boolean	true	profile_reactor_first_backpressure_enabled	참조	Reactor 첫 번째 backpressure 이벤트를 프로파일에 기록한다.
profile_redis_enabled	boolean	true	profile_redis_enabled	고급	Redis 호출을 프로파일에 기록한다.
profile_connection_open_fullstack_enabled	boolean	false	profile_connection_open_fullstack_enabled	참조	Connection open 시 전체 스택 트레이스를 기록한다. Connection Pool 문제 진단에 사용한다.
profile_connection_open_fullstack_trim_enabled	boolean	true	profile_connection_open_fullstack_trim_enabled	참조	Connection open 스택 트레이스에서 프레임워크 내부 프레임을 생략한다.
profile_sql_param_length	int	40	profile_sql_param_length	고급	SQL 바인드 파라미터 최대 표시 길이. 긴 파라미터는 잘린다.
profile_method_time_threshold_ms	int	0	profile_method_time_threshold_ms	고급	메서드 프로파일링 최소 실행 시간(ms). 이 값 미만이면 프로파일에서 제외한다. 0이면 전체 기록이다.
profile_http_header_keys	String	""	profile_http_header_keys	고급	프로파일에 기록할 HTTP 헤더 키 목록 (콤마 구분). 빈 값이면 전체 헤더를 기록한다.
profile_http_parameter_url_prefix	String	""	profile_http_parameter_url_prefix	참조	특정 URL prefix에만 HTTP 파라미터를 기록한다.
profile_dbc_close_enabled	boolean	false	profile_dbc_close_enabled	참조	DB Connection close 이벤트 프로파일링 활성화이다.
profile_rs_leak_enabled	boolean	false	profile_rs_leak_enabled	참조	ResultSet 누수 감지를 활성화한다.
profile_stmt_leak_enabled	boolean	false	profile_stmt_leak_enabled	참조	Statement 누수 감지를 활성화한다.
profile_thread_cputime_enabled	boolean	false	profile_thread_cputime_enabled	고급	스레드 CPU 시간을 프로파일에 기록한다. 약간의 오버헤드가 있다.
profile_block_servlet_enabled	boolean	false	profile_block_servlet_enabled	참조	특정 서블릿에 대한 블록 프로파일링을 활성화한다.
profile_spring_controller_method_parameter_enabled	boolean	false	profile_spring_controller_method_parameter_enabled	고급	Spring Controller 메서드 파라미터를 프로파일에 기록한다.
profile_resultset_fetch_enabled	boolean	false	profile_resultset_fetch_enabled	참조	ResultSet fetch 이벤트를 프로파일에 기록한다.
profile_api_call_header_enabled	boolean	false	profile_api_call_header_enabled	참조	API 호출 시 HTTP 헤더를 프로파일에 기록한다.

연관 관계

profile_http_header_enabled ──┐
profile_http_header_url_prefix ──┤── HTTP 헤더 프로파일링 그룹
profile_http_header_keys ────────┘

profile_http_parameter_enabled ──┐
profile_http_parameter_url_prefix ──┘── HTTP 파라미터 프로파일링 그룹

profile_connection_open_enabled ──┐
profile_connection_open_fullstack_enabled ──┤── Connection 프로파일링 그룹
profile_connection_open_fullstack_trim_enabled ──┤
profile_connection_close_enabled ──┤
profile_connection_autocommit_status_enabled ──┘

profile_force_end_stuck_alert ──┐
profile_force_end_stuck_with_interrupt ──┘── Stuck 서비스 제어 그룹 (P1 profile_force_end_stuck_millis와 연동)

profile_fullstack_enabled ──┐
profile_fullstack_max_lines ──┤── 전체 스택 트레이스 그룹
profile_fullstack_hooked_exception_enabled ──┤
profile_fullstack_rs_leak_enabled ──┤
profile_fullstack_stmt_leak_enabled ──┘

profile_method_enabled ──┐
profile_method_time_threshold_ms ──┘── 메서드 프로파일링 그룹 (hook_method_patterns 연동)

---

4. 트레이싱 고급 (Tracing Advanced)

분산 트레이싱, 사용자 식별 세부, URL 정규화 등 고급 트레이싱 파라미터이다. Active Thread 3색 분류 및 trace_user_mode 동작 원리는 10-1.agent-java-params.md를 참조한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
trace_user_session_key	String	""	trace_user_session_key	고급	trace_user_mode=1 시 사용할 세션 쿠키 이름. 빈 값이면 JSESSIONID를 사용한다.
trace_user_cookie_path	String	"/"	trace_user_cookie_path	참조	trace_user_mode=2 시 FlowKat 쿠키의 Path 속성이다.
trace_flowkat_cookie_max_age	int	Integer.MAX_VALUE	trace_flowkat_cookie_max_age	참조	trace_user_mode=2 시 FlowKat 쿠키 Max-Age(초). 기본 Integer.MAX_VALUE(사실상 무기한)이다.
trace_interservice_enabled	boolean	true	trace_interservice_enabled	고급	인터서비스 트레이싱 활성화. 서비스 간 호출 연결 추적에 사용한다.
trace_propagete_b3_header	boolean	true	trace_propagete_b3_header	고급	B3 헤더 전파 활성화. 주의: **propagete**는 의도된 키명이다. **propagate**로 변경하면 적용되지 않는다.
trace_http_client_ip_header_key	String	""	trace_http_client_ip_header_key	고급	클라이언트 IP 추출에 사용할 HTTP 헤더 키. 프록시/LB 환경에서 X-Forwarded-For 등을 지정한다.
trace_service_name_header_key	String	""	trace_service_name_header_key	고급	서비스 이름을 HTTP 헤더에서 추출한다. API Gateway 환경에서 유용하다.
trace_service_name_get_key	String	""	trace_service_name_get_key	참조	서비스 이름을 GET 파라미터에서 추출한다.
trace_service_name_post_key	String	""	trace_service_name_post_key	참조	서비스 이름을 POST 파라미터에서 추출한다.
trace_request_queuing_enabled	boolean	false	trace_request_queuing_enabled	고급	Request Queuing 시간 추적 활성화. LB/Proxy 대기 시간을 측정한다.
trace_request_queuing_start_host_header	String	""	trace_request_queuing_start_host_header	참조	Request Queuing 시작 시점을 담은 호스트 헤더 키이다.
trace_background_socket_enabled	boolean	true	trace_background_socket_enabled	고급	백그라운드 소켓 트레이싱 활성화이다.
trace_db2_enabled	boolean	false	trace_db2_enabled	참조	DB2 전용 트레이싱 활성화이다.
trace_sql_parameter_max_length	int	40	trace_sql_parameter_max_length	고급	SQL 바인드 파라미터 최대 표시 길이이다.
trace_interservice_caller_header_enabled	boolean	true	trace_interservice_caller_header_enabled	참조	인터서비스 호출 시 caller 헤더 전송을 활성화한다.
trace_interservice_callee_header_enabled	boolean	true	trace_interservice_callee_header_enabled	참조	인터서비스 호출 시 callee 헤더 수신을 활성화한다.
trace_response_gxid_enabled	boolean	false	trace_response_gxid_enabled	참조	응답 헤더에 GXID(글로벌 트랜잭션 ID)를 포함한다.
trace_normalize_enabled	boolean	true	trace_normalize_enabled	고급	URL 정규화 활성화. RESTful URL의 가변 경로를 *로 치환한다.
trace_normalize_urls	String	""	trace_normalize_urls	고급	수동 정규화 URL 패턴 목록 (콤마 구분)이다.

연관 관계

trace_user_session_key ──┐
trace_user_cookie_path ──┤── 사용자 식별 세부 그룹 (P1 trace_user_mode와 연동)
trace_flowkat_cookie_max_age ──┤
trace_http_client_ip_header_key ──┘

trace_interservice_enabled ──┐
trace_interservice_caller_header_enabled ──┤── 분산 트레이싱 그룹
trace_interservice_callee_header_enabled ──┤
trace_propagete_b3_header ──┤
trace_response_gxid_enabled ──┘

trace_service_name_header_key ──┐
trace_service_name_get_key ─────┤── 서비스 이름 추출 그룹
trace_service_name_post_key ────┘

trace_request_queuing_enabled ──┐
trace_request_queuing_start_host_header ──┘── Request Queuing 그룹

---

5. XLog 에러 마킹 고급

XLog 에러 마킹의 P2 파라미터이다. P1 파라미터 및 동작 원리는 10-1.agent-java-params.md를 참조한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
xlog_error_check_user_transaction_enabled	boolean	true	xlog_error_check_user_transaction_enabled	고급	사용자 트랜잭션(UserTransaction)에서 발생한 에러도 XLog에 마킹한다.
xlog_error_on_sqlexception_enabled	boolean	true	xlog_error_on_sqlexception_enabled	고급	SQLException 발생 시 XLog에 에러를 마킹한다.
xlog_error_on_apicall_exception_enabled	boolean	true	xlog_error_on_apicall_exception_enabled	고급	API 호출 예외 시 XLog에 에러를 마킹한다.
xlog_error_on_redis_exception_enabled	boolean	true	xlog_error_on_redis_exception_enabled	고급	Redis 예외 시 XLog에 에러를 마킹한다.
xlog_error_on_mongodb_exception_enabled	boolean	true	xlog_error_on_mongodb_exception_enabled	고급	MongoDB 예외 시 XLog에 에러를 마킹한다.
xlog_error_on_elasticsearch_exception_enabled	boolean	true	xlog_error_on_elasticsearch_exception_enabled	고급	Elasticsearch 예외 시 XLog에 에러를 마킹한다.
xlog_error_off_http_status_regex	String	""	xlog_error_off_http_status_regex	고급	이 정규식에 매칭되는 HTTP 상태 코드는 에러로 마킹하지 않는다. 예: `"404
xlog_error_off_message_regex	String	""	xlog_error_off_message_regex	고급	이 정규식에 매칭되는 에러 메시지는 에러로 마킹하지 않는다. 비즈니스 예외 제외 시 사용한다.

---

6. XLog 샘플링 (Global)

고트래픽 환경에서 XLog 데이터량을 제어하기 위한 글로벌 샘플링 파라미터이다. 응답 시간 구간별로 샘플링 비율을 차등 적용하여, 빠른 트랜잭션은 일부만 수집하고 느린 트랜잭션은 전량 수집하는 전략이다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
xlog_sampling_enabled	boolean	false	xlog_sampling_enabled	고급	XLog 샘플링 활성화. 비활성화 시 전량 수집한다.
xlog_sampling_rate_precision	int	1	xlog_sampling_rate_precision	참조	샘플링 비율 정밀도. 1=1% 단위, 10=0.1% 단위, 100=0.01% 단위이다.
xlog_sampling_only_profile	boolean	false	xlog_sampling_only_profile	고급	true이면 프로파일 데이터만 샘플링하고, XLog 자체(TPS/요약)는 전량 유지한다.
xlog_sampling_step1_ms	int	100	xlog_sampling_step1_ms	고급	1단계 응답시간 기준(ms). 이 값 미만인 트랜잭션에 step1_rate_pct를 적용한다.
xlog_sampling_step1_rate_pct	int	3	xlog_sampling_step1_rate_pct	고급	1단계 샘플링 비율(%). 기본 3% — 100ms 미만 빠른 트랜잭션의 3%만 수집한다.
xlog_sampling_step2_ms	int	1000	xlog_sampling_step2_ms	고급	2단계 응답시간 기준(ms).
xlog_sampling_step2_rate_pct	int	10	xlog_sampling_step2_rate_pct	고급	2단계 샘플링 비율(%).
xlog_sampling_step3_ms	int	3000	xlog_sampling_step3_ms	고급	3단계 응답시간 기준(ms).
xlog_sampling_step3_rate_pct	int	30	xlog_sampling_step3_rate_pct	고급	3단계 샘플링 비율(%).
xlog_sampling_over_rate_pct	int	100	xlog_sampling_over_rate_pct	고급	4단계(step3 초과) 샘플링 비율(%). 기본 100% — 느린 트랜잭션 전량 수집이다.
xlog_sampling_exclude_patterns	String	""	xlog_sampling_exclude_patterns	고급	샘플링에서 제외할 서비스 패턴 (콤마 구분). 매칭되는 서비스는 항상 전량 수집한다.
ignore_global_consequent_sampling	boolean	false	ignore_global_consequent_sampling	참조	글로벌 연쇄 샘플링을 무시한다. 인터서비스 호출 시 caller의 샘플링 결정을 callee가 따르지 않는다.
xlog_consequent_sampling_ignore_patterns	String	""	xlog_consequent_sampling_ignore_patterns	참조	연쇄 샘플링 무시 패턴. 특정 서비스에서만 연쇄 샘플링을 무시한다.

동작 원리: 4단계 응답시간 기반 샘플링

[4단계 응답시간 기반 샘플링 알고리즘]

function should_sample(elapsed_ms):
  if NOT xlog_sampling_enabled:
    return KEEP                            // 샘플링 비활성화 → 전량 수집

  // 1. 응답시간 구간별 샘플링 비율 결정
  if elapsed_ms < xlog_sampling_step1_ms:          // < 100ms
    rate_pct = xlog_sampling_step1_rate_pct        // 3%
  else if elapsed_ms < xlog_sampling_step2_ms:     // < 1000ms
    rate_pct = xlog_sampling_step2_rate_pct        // 10%
  else if elapsed_ms < xlog_sampling_step3_ms:     // < 3000ms
    rate_pct = xlog_sampling_step3_rate_pct        // 30%
  else:                                            // >= 3000ms
    rate_pct = xlog_sampling_over_rate_pct         // 100%

  // 2. 제외 패턴 체크
  if service_name matches xlog_sampling_exclude_patterns:
    return KEEP                            // 패턴 매칭 → 항상 수집

  // 3. 랜덤 결정
  precision = xlog_sampling_rate_precision         // 1
  random_value = random() % (100 * precision)      // 0 ~ 99
  threshold = rate_pct                             // 3

  if random_value >= threshold:
    return DISCARD                         // 버림
  else:
    return KEEP                            // 수집

  // 4. xlog_sampling_only_profile == true 인 경우
  //    DISCARD된 트랜잭션도 XLog 요약(TPS, 응답시간)은 유지하고
  //    프로파일 데이터(SQL, 메서드 스텝)만 버린다

[기본값 적용 시 샘플링 비율 요약]

  응답 시간          | 샘플링 비율 | 수집 비율
  < 100ms           | 3%         | 100건 중 3건 수집
  100ms ~ 1s        | 10%        | 100건 중 10건 수집
  1s ~ 3s           | 30%        | 100건 중 30건 수집
  >= 3s             | 100%       | 전량 수집

[정밀도 예시: rate_precision=10]

  rate_pct=3 → random % 1000 >= 3 이면 DISCARD → 실제 수집률 0.3%
  rate_pct=30 → random % 1000 >= 30 이면 DISCARD → 실제 수집률 3.0%

설정 예시

# 시나리오 1: 기본 샘플링 (고트래픽 웹 서비스)
xlog_sampling_enabled=true
# 기본값 사용: step1=100ms/3%, step2=1s/10%, step3=3s/30%, over=100%

# 시나리오 2: 공격적 샘플링 (초대용량 트래픽, 10만 TPS 이상)
xlog_sampling_enabled=true
xlog_sampling_step1_rate_pct=1
xlog_sampling_step2_rate_pct=5
xlog_sampling_step3_rate_pct=20
xlog_sampling_over_rate_pct=100
xlog_sampling_only_profile=true

# 시나리오 3: 특정 서비스 제외 (헬스체크는 항상 수집)
xlog_sampling_enabled=true
xlog_sampling_exclude_patterns=/health*,/actuator*

# 시나리오 4: 0.1% 정밀도 샘플링
xlog_sampling_enabled=true
xlog_sampling_rate_precision=10
xlog_sampling_step1_rate_pct=5             # 실제 0.5% 수집

---

7. XLog 패턴 샘플링 (Groups 1-5)

서비스 이름 패턴별로 개별 샘플링 비율을 적용하는 파라미터이다. 5개 그룹을 지원하며, 그룹 1부터 5까지 순서대로 평가하여 첫 번째 매칭 그룹의 설정을 적용한다. 어떤 그룹에도 매칭되지 않으면 글로벌 샘플링(섹션 6)으로 폴백한다.

파라미터 테이블 (그룹 1 대표)

그룹 2~5는 접두사만 다르며 동일한 구조이다: xlog_patterned2_sampling_*, xlog_patterned3_sampling_*, xlog_patterned4_sampling_*, xlog_patterned5_sampling_*

파라미터	타입	기본값	conf 키	중요도	설명
xlog_patterned_sampling_enabled	boolean	false	xlog_patterned_sampling_enabled	고급	그룹 1 패턴 샘플링 활성화이다.
xlog_patterned_sampling_service_patterns	String	""	xlog_patterned_sampling_service_patterns	고급	그룹 1 매칭 서비스 패턴 (콤마 구분). 와일드카드 * 지원한다.
xlog_patterned_sampling_rate_precision	int	1	xlog_patterned_sampling_rate_precision	참조	그룹 1 샘플링 정밀도이다.
xlog_patterned_sampling_only_profile	boolean	false	xlog_patterned_sampling_only_profile	참조	그룹 1 프로파일만 샘플링이다.
xlog_patterned_sampling_step1_ms	int	100	xlog_patterned_sampling_step1_ms	고급	그룹 1 1단계 응답시간 기준(ms)이다.
xlog_patterned_sampling_step1_rate_pct	int	3	xlog_patterned_sampling_step1_rate_pct	고급	그룹 1 1단계 샘플링 비율(%)이다.
xlog_patterned_sampling_step2_ms	int	1000	xlog_patterned_sampling_step2_ms	고급	그룹 1 2단계 응답시간 기준(ms)이다.
xlog_patterned_sampling_step2_rate_pct	int	10	xlog_patterned_sampling_step2_rate_pct	고급	그룹 1 2단계 샘플링 비율(%)이다.
xlog_patterned_sampling_step3_ms	int	3000	xlog_patterned_sampling_step3_ms	고급	그룹 1 3단계 응답시간 기준(ms)이다.
xlog_patterned_sampling_step3_rate_pct	int	30	xlog_patterned_sampling_step3_rate_pct	고급	그룹 1 3단계 샘플링 비율(%)이다.
xlog_patterned_sampling_over_rate_pct	int	100	xlog_patterned_sampling_over_rate_pct	고급	그룹 1 4단계(step3 초과) 샘플링 비율(%)이다.

그룹 2~5 접두사 매핑:

그룹	conf 키 접두사	예시
그룹 1	xlog_patterned_sampling_	xlog_patterned_sampling_enabled
그룹 2	xlog_patterned2_sampling_	xlog_patterned2_sampling_enabled
그룹 3	xlog_patterned3_sampling_	xlog_patterned3_sampling_enabled
그룹 4	xlog_patterned4_sampling_	xlog_patterned4_sampling_enabled
그룹 5	xlog_patterned5_sampling_	xlog_patterned5_sampling_enabled

동작 원리: 패턴 매칭 우선순위

[패턴 샘플링 평가 알고리즘]

function evaluate_sampling(service_name, elapsed_ms):

  // 1. 패턴 그룹 순차 평가 (1 → 2 → 3 → 4 → 5)
  for group_id in [1, 2, 3, 4, 5]:
    config = get_patterned_config(group_id)

    if NOT config.enabled:
      continue                             // 비활성화 그룹 건너뜀

    if match(service_name, config.service_patterns):
      // 첫 번째 매칭 그룹의 설정으로 샘플링 결정
      return apply_sampling(elapsed_ms, config)

  // 2. 어떤 그룹에도 매칭되지 않으면 글로벌 샘플링 적용
  return apply_global_sampling(elapsed_ms)

[패턴 매칭 규칙]
  - 와일드카드 `*` 지원: `/api/order*` → `/api/order`, `/api/order/detail` 모두 매칭
  - 콤마로 다중 패턴: `/api/order*,/api/payment*`
  - 대소문자 구분함
  - 첫 번째 매칭 그룹에서 결정 → 나머지 그룹은 평가하지 않음

[우선순위 활용 예시]
  그룹 1: /health*,/actuator* → 0% 수집 (완전 제외)
  그룹 2: /api/batch* → step1=1s/1%, step2=5s/10%, step3=10s/50%
  그룹 3: /api/realtime* → 전량 수집 (100%)
  나머지: 글로벌 샘플링 기본값 적용

설정 예시

# 그룹 1: 헬스체크/액추에이터 — 완전 제외
xlog_patterned_sampling_enabled=true
xlog_patterned_sampling_service_patterns=/health*,/actuator*,/favicon.ico
xlog_patterned_sampling_step1_rate_pct=0
xlog_patterned_sampling_step2_rate_pct=0
xlog_patterned_sampling_step3_rate_pct=0
xlog_patterned_sampling_over_rate_pct=0

# 그룹 2: 배치 API — 느슨한 기준
xlog_patterned2_sampling_enabled=true
xlog_patterned2_sampling_service_patterns=/api/batch*,/api/report*
xlog_patterned2_sampling_step1_ms=1000
xlog_patterned2_sampling_step1_rate_pct=1
xlog_patterned2_sampling_step2_ms=5000
xlog_patterned2_sampling_step2_rate_pct=10
xlog_patterned2_sampling_step3_ms=10000
xlog_patterned2_sampling_step3_rate_pct=50
xlog_patterned2_sampling_over_rate_pct=100

# 그룹 3: 핵심 거래 API — 전량 수집
xlog_patterned3_sampling_enabled=true
xlog_patterned3_sampling_service_patterns=/api/payment*,/api/order*
xlog_patterned3_sampling_step1_rate_pct=100
xlog_patterned3_sampling_step2_rate_pct=100
xlog_patterned3_sampling_step3_rate_pct=100
xlog_patterned3_sampling_over_rate_pct=100

# 글로벌 샘플링 (그룹 미매칭 트랜잭션에 적용)
xlog_sampling_enabled=true

---

8. XLog 디스카드

특정 서비스의 XLog를 완전히 버리는 파라미터이다. 샘플링과 달리 비율이 아닌 패턴 매칭으로 동작하며, 매칭된 서비스의 데이터를 전량 제거한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
xlog_discard_service_patterns	String	""	xlog_discard_service_patterns	고급	부분 디스카드 패턴 (콤마 구분). 매칭 서비스의 XLog와 프로파일은 버리지만, TPS/응답시간 요약 데이터는 유지한다.
xlog_fully_discard_service_patterns	String	""	xlog_fully_discard_service_patterns	고급	완전 디스카드 패턴 (콤마 구분). 매칭 서비스의 모든 데이터(XLog, 프로파일, TPS, 요약)를 완전히 제거한다.
xlog_discard_service_show_error	boolean	true	xlog_discard_service_show_error	참조	디스카드 대상이라도 에러 트랜잭션은 XLog에 표시한다. xlog_discard_service_patterns에만 적용된다.

동작 원리

[XLog 디스카드 판정 흐름]

function check_discard(service_name, is_error):

  // 1. 완전 디스카드 (최우선)
  if match(service_name, xlog_fully_discard_service_patterns):
    return FULLY_DISCARD
    // XLog: 버림
    // Profile: 버림
    // TPS/Summary: 버림 (카운터에서 완전 제외)

  // 2. 부분 디스카드
  if match(service_name, xlog_discard_service_patterns):
    if is_error AND xlog_discard_service_show_error:
      return KEEP                          // 에러 트랜잭션은 유지
    return PARTIAL_DISCARD
    // XLog: 버림
    // Profile: 버림
    // TPS/Summary: 유지 (카운터에는 포함)

  // 3. 디스카드 대상 아님
  return KEEP

[디스카드 vs 샘플링 비교]

  | 구분 | 디스카드 | 샘플링 |
  |------|---------|--------|
  | 대상 선정 | 패턴 매칭 (전량) | 응답시간 + 확률 |
  | TPS 영향 | partial=유지, full=제거 | 항상 유지 |
  | 에러 보존 | partial=가능, full=불가 | 불가 |
  | 용도 | 불필요한 서비스 제거 | 데이터량 조절 |

[평가 순서]
  fully_discard → discard → patterned sampling (1~5) → global sampling

---

9. Hook/계측 (Instrumentation)

바이트코드 위빙을 통해 대상 클래스/메서드를 계측하는 파라미터이다. Hook 패턴 변경 후에는 JVM 재시작이 필요하다. P1 파라미터 hook_method_patterns는 10-1.agent-java-params.md를 참조한다.

파라미터 테이블 (사용자 설정 가능 항목만)

파라미터	타입	기본값	conf 키	중요도	설명
hook_method_ignore_prefixes	String	""	hook_method_ignore_prefixes	고급	Hook 제외 메서드 접두사. 프레임워크 내부 메서드 제외에 사용한다.
hook_method_ignore_classes	String	""	hook_method_ignore_classes	고급	Hook 제외 클래스. 프록시/자동생성 클래스 제외에 사용한다.
hook_method_access_public_enabled	boolean	true	hook_method_access_public_enabled	고급	public 메서드 Hook 활성화이다.
hook_method_access_private_enabled	boolean	false	hook_method_access_private_enabled	참조	private 메서드 Hook 활성화이다.
hook_method_access_protected_enabled	boolean	false	hook_method_access_protected_enabled	참조	protected 메서드 Hook 활성화이다.
hook_method_access_none_enabled	boolean	false	hook_method_access_none_enabled	참조	package-private 메서드 Hook 활성화이다.
hook_method_lambda_enable	boolean	true	hook_method_lambda_enable	고급	Lambda 표현식 Hook 활성화이다.
hook_method_anonymous_enable	boolean	true	hook_method_anonymous_enable	고급	익명 클래스 메서드 Hook 활성화이다.
hook_service_patterns	String	""	hook_service_patterns	고급	서비스 진입점 Hook 패턴. Servlet 외 진입점을 지정한다.
hook_apicall_patterns	String	""	hook_apicall_patterns	고급	API 호출 Hook 패턴. HttpClient, RestTemplate 등 외부 호출을 추적한다.
hook_apicall_info_patterns	String	""	hook_apicall_info_patterns	참조	API 호출 정보 Hook 패턴. 호출 URL/파라미터를 추출한다.
hook_jsp_patterns	String	""	hook_jsp_patterns	참조	JSP Hook 패턴이다.
hook_servlet_class	String	""	hook_servlet_class	고급	서블릿 클래스 직접 지정. 자동 감지가 안 되는 환경에서 사용한다.
hook_args_patterns	String	""	hook_args_patterns	고급	메서드 인자를 프로파일에 기록할 패턴이다.
hook_return_patterns	String	""	hook_return_patterns	고급	메서드 리턴값을 프로파일에 기록할 패턴이다.
hook_constructor_patterns	String	""	hook_constructor_patterns	참조	생성자 Hook 패턴이다.
hook_connection_open_patterns	String	""	hook_connection_open_patterns	고급	JDBC Connection open Hook 패턴이다.
hook_get_connection_patterns	String	""	hook_get_connection_patterns	고급	DataSource.getConnection() Hook 패턴이다.
hook_jdbc_pstmt_classes	String	""	hook_jdbc_pstmt_classes	고급	JDBC PreparedStatement 구현 클래스 직접 지정이다.
hook_jdbc_stmt_classes	String	""	hook_jdbc_stmt_classes	고급	JDBC Statement 구현 클래스 직접 지정이다.
hook_jdbc_rs_classes	String	""	hook_jdbc_rs_classes	고급	JDBC ResultSet 구현 클래스 직접 지정이다.
hook_jdbc_wrapping_driver_patterns	String	""	hook_jdbc_wrapping_driver_patterns	참조	JDBC Driver 래핑 패턴이다.
hook_jdbc_oracle_cstat_capture_enabled	boolean	false	hook_jdbc_oracle_cstat_capture_enabled	참조	Oracle CallableStatement 캡처 활성화이다.
hook_exception_class_patterns	String	""	hook_exception_class_patterns	고급	예외 Hook 클래스 패턴이다.
hook_exception_exclude_class_patterns	String	""	hook_exception_exclude_class_patterns	고급	예외 Hook 제외 클래스 패턴이다.
hook_exception_handler_method_patterns	String	""	hook_exception_handler_method_patterns	참조	예외 핸들러 메서드 Hook 패턴이다.
hook_exception_handler_exclude_class_patterns	String	""	hook_exception_handler_exclude_class_patterns	참조	예외 핸들러 제외 클래스 패턴이다.
hook_async_callrunnable_enabled	boolean	true	hook_async_callrunnable_enabled	고급	비동기 Callable/Runnable Hook 활성화이다.
hook_async_callrunnable_scan_package_prefixes	String	""	hook_async_callrunnable_scan_package_prefixes	고급	비동기 Hook 스캔 대상 패키지 접두사이다.
hook_async_thread_pool_executor_enabled	boolean	false	hook_async_thread_pool_executor_enabled	참조	ThreadPoolExecutor Hook 활성화이다.
hook_spring_async_enabled	boolean	false	hook_spring_async_enabled	고급	Spring @Async Hook 활성화이다.
hook_spring_async_submit_patterns	String	""	hook_spring_async_submit_patterns	참조	Spring Async submit 메서드 패턴이다.
hook_hystrix_enabled	boolean	false	hook_hystrix_enabled	참조	Hystrix Command Hook 활성화이다.
hook_scouter_weaver_enabled	boolean	true	hook_scouter_weaver_enabled	참조	Scouter Weaver 플러그인 Hook 활성화이다.
hook_mongodb_enabled	boolean	true	hook_mongodb_enabled	고급	MongoDB 드라이버 Hook 활성화이다.

동작 원리: 바이트코드 위빙

[바이트코드 위빙 메커니즘]

JVM 기동 시:
  1. -javaagent 옵션으로 에이전트 로드
  2. ClassFileTransformer 등록
  3. 설정 파일에서 hook_*_patterns 읽기
  4. 패턴별 XOR 기반 시그니처 핑거프린트 생성

클래스 로딩 시:
  function transform(class_name, bytecode):
    // 패턴 매칭 (XOR 시그니처 기반 빠른 비교)
    for each pattern in hook_patterns:
      if match(class_name + method_name, pattern):
        // 접근 제어자 필터
        if method.access == PUBLIC AND NOT hook_method_access_public_enabled:
          continue
        if method.access == PRIVATE AND NOT hook_method_access_private_enabled:
          continue
        // ... protected, none 동일

        // 제외 필터
        if match(method_name, hook_method_ignore_prefixes):
          continue
        if match(class_name, hook_method_ignore_classes):
          continue

        // 바이트코드 수정: 진입/퇴출 지점에 추적 코드 삽입
        bytecode = weave_entry(bytecode, method)    // 시작 시간 기록
        bytecode = weave_exit(bytecode, method)     // 종료 시간 기록, 프로파일 스텝 추가

    return bytecode

[시그니처 핑거프린트]
  fingerprint = XOR(hash(pattern_1), hash(pattern_2), ...)
  // 런타임에 패턴 변경 감지 → 변경 시 경고 로그 출력
  // 실제 반영은 JVM 재시작 필요

주의사항: JVM 재시작 필요

[Hook 패턴 변경 시 동작]

  ConfObserver가 hook_*_patterns 변경 감지
    → 시그니처 핑거프린트 비교
    → 불일치 시 경고 로그: "Hook pattern changed, JVM restart required"
    → 이미 로드된 클래스의 바이트코드는 변경되지 않음
    → JVM 재시작 전까지 이전 패턴으로 동작

[런타임 변경 가능 vs JVM 재시작 필요]

  런타임 변경 가능:
    - hook_method_access_*_enabled (접근 제어자 필터)
    - hook_async_callrunnable_enabled
    - hook_mongodb_enabled
    - 대부분의 boolean on/off 토글

  JVM 재시작 필요:
    - hook_method_patterns (패턴 문자열 변경)
    - hook_service_patterns
    - hook_apicall_patterns
    - hook_connection_open_patterns
    - 모든 *_patterns 문자열 파라미터

---

11. Auto Dump

시스템 이상 상황을 자동 감지하여 ThreadDump/ActiveService 정보를 파일로 저장하는 파라미터이다. 2가지 트리거 모드를 지원한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
autodump_enabled	boolean	false	autodump_enabled	고급	Active Service 기반 Auto Dump 활성화이다.
autodump_trigger_active_service_cnt	int	10000	autodump_trigger_active_service_cnt	고급	Auto Dump 트리거 Active Service 건수이다.
autodump_interval_ms	int	30000	autodump_interval_ms	고급	Auto Dump 실행 간격(ms). 최소 5000ms이다.
autodump_level	int	1	autodump_level	고급	Dump 수준. 1=ThreadDump, 2=ActiveService 목록, 3=ThreadList이다.
autodump_stuck_thread_ms	int	0	autodump_stuck_thread_ms	참조	Stuck 스레드 감지 기준(ms). 0이면 비활성화이다.
autodump_stuck_check_interval_ms	int	10000	autodump_stuck_check_interval_ms	참조	Stuck 스레드 감지 주기(ms)이다.
autodump_cpu_exceeded_enabled	boolean	false	autodump_cpu_exceeded_enabled	고급	CPU 과부하 기반 Auto Dump 활성화이다.
autodump_cpu_exceeded_threshold_pct	int	90	autodump_cpu_exceeded_threshold_pct	고급	CPU 과부하 기준 백분율이다.
autodump_cpu_exceeded_duration_ms	int	30000	autodump_cpu_exceeded_duration_ms	고급	CPU 과부하 지속 시간(ms). 이 기간 동안 지속되어야 트리거된다.
autodump_cpu_exceeded_dump_interval_ms	int	3000	autodump_cpu_exceeded_dump_interval_ms	참조	CPU 과부하 시 Dump 수집 간격(ms)이다.
autodump_cpu_exceeded_dump_cnt	int	3	autodump_cpu_exceeded_dump_cnt	참조	CPU 과부하 시 Dump 수집 횟수이다.

동작 원리: 2가지 트리거 모드

[트리거 모드 1: Active Service 수 기반]

조건: autodump_enabled == true

모니터링 루프:
  every autodump_interval_ms (최소 5000ms):
    active_count = get_active_transaction_count()

    if active_count > autodump_trigger_active_service_cnt:
      // Dump 실행
      switch autodump_level:
        case 1:
          dump = capture_thread_dump()       // 전체 스레드 덤프
        case 2:
          dump = capture_active_services()   // Active Service 목록만
        case 3:
          dump = capture_thread_list()       // 스레드 이름 목록

      write_to_file(dump_dir + "/autodump_" + timestamp)

      // Stuck 스레드 감지 (옵션)
      if autodump_stuck_thread_ms > 0:
        for each thread in active_threads:
          if thread.elapsed > autodump_stuck_thread_ms:
            mark_as_stuck(thread)
            capture_thread_stack(thread)


[트리거 모드 2: CPU 사용률 기반]

조건: autodump_cpu_exceeded_enabled == true

모니터링 루프:
  cpu_exceeded_start = null

  every 1 second:
    cpu_usage = get_process_cpu_usage()

    if cpu_usage > autodump_cpu_exceeded_threshold_pct:       // > 90%
      if cpu_exceeded_start == null:
        cpu_exceeded_start = now()

      if now() - cpu_exceeded_start > autodump_cpu_exceeded_duration_ms:  // 30초 지속
        // 연속 Dump 수집
        for i in range(autodump_cpu_exceeded_dump_cnt):       // 3회
          dump = capture_thread_dump()
          write_to_file(dump_dir + "/cpu_dump_" + timestamp + "_" + i)
          wait(autodump_cpu_exceeded_dump_interval_ms)        // 3초 간격

        cpu_exceeded_start = null           // 리셋 (다음 초과 시 재트리거)

    else:
      cpu_exceeded_start = null             // CPU 정상 복귀 → 리셋

[Dump 파일 저장 위치]
  dump_dir 파라미터 (기본: $AGENT_HOME/dump)

---

12. 알림/로그/카운터/요약 — P2/P3

에이전트 자체의 알림 전송, 로그 관리, 카운터 수집, 요약 통계 파라미터 중 P2/P3 항목이다. P1 항목은 10-1.agent-java-params.md를 참조한다.

Alert 파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
alert_message_length	int	3000	alert_message_length	참조	Alert 메시지 최대 길이(문자)이다.
alert_send_interval_ms	int	10000	alert_send_interval_ms	고급	Alert 전송 최소 간격(ms). 동일 Alert의 중복 전송을 방지한다.
alert_perm_warning_pct	int	90	alert_perm_warning_pct	고급	PermGen/Metaspace 사용률 경고 기준(%). 이 값을 초과하면 Alert을 전송한다.

Log 파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
log_enabled	boolean	false	log_enabled	고급	에이전트 로그 파일 기록 활성화이다.
log_dir	String	$AGENT_HOME/logs	log_dir	고급	로그 파일 저장 디렉토리이다.
log_rotation_enabled	boolean	true	log_rotation_enabled	참조	로그 파일 일별 로테이션 활성화이다.
log_keep_days	int	7	log_keep_days	참조	로그 파일 보관 일수. 이 기간 초과 로그는 자동 삭제된다.

Counter 파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
counter_recentuser_valid_ms	long	300000	counter_recentuser_valid_ms	고급	최근 사용자 유효 기간(ms). 기본 5분이다. 이 기간 내 활동 사용자를 "최근 사용자"로 집계한다.
counter_object_registry_path	String	""	counter_object_registry_path	참조	오브젝트 레지스트리 파일 경로. 에이전트 식별 정보를 파일로 저장한다.
counter_custom_jmx_enabled	boolean	false	counter_custom_jmx_enabled	참조	JMX 커스텀 카운터 수집 활성화이다.
counter_interaction_enabled	boolean	false	counter_interaction_enabled	참조	인터랙션 카운터 활성화. 서비스 간 호출 빈도를 측정한다.

Summary 파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
summary_enabled	boolean	true	summary_enabled	고급	요약 통계 수집 활성화. 서비스별 TPS, 평균 응답시간 등 5분 단위 요약 데이터를 생성한다.

SFA/PSTS Stack Dump 파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
sfa_dump_enabled	boolean	false	sfa_dump_enabled	참조	SFA(Stack Frequency Analysis) Dump 활성화. Active Thread의 스택 빈도 분석 데이터를 수집한다.
sfa_dump_interval_ms	int	10000	sfa_dump_interval_ms	참조	SFA Dump 수집 간격(ms)이다.
enduser_trace_endpoint_url	String	""	enduser_trace_endpoint_url	참조	엔드유저 트레이스 엔드포인트 URL. 프론트엔드 성능 데이터를 수신할 URL을 지정한다.

---

관련 문서

문서	설명
10-1.agent-java-params.md	Java Agent 파라미터 기본편 (P0/P1)
10.agent-java.md	Java Agent 설치 및 핵심 파라미터 가이드
14.collect-server.md	수집 서버 설정
parameter-inventory.md	전체 파라미터 인벤토리 (P0~P3 분류)