Java Agent 파라미터 (기본편)

Java Agent P0/P1 핵심 파라미터 레퍼런스

고급 파라미터는 고급 파라미터 레퍼런스 참조.

---

중요도 기준

등급	의미	잘못 설정 시 영향
필수	필수 설정	에이전트 데이터가 수집 서버에 전송되지 않거나, 대시보드에서 오브젝트를 식별할 수 없다
핵심	운영 핵심	성능 저하, 잘못된 에러 마킹, Active Thread 오분류 등 운영 판단에 영향을 준다
고급	고급 튜닝	특정 환경(대규모 TPS, 분산 트레이싱, 패턴 샘플링 등)에서 조정이 필요하다
참조	참조/기타	기본값으로 충분하며, 특수 상황에서만 변경한다

---

1. 네트워크 (Network)

에이전트와 수집 서버 간 TCP 통신을 제어하는 파라미터이다. V3 프로토콜 기준으로 UDP는 deprecated 되었으며 TCP만 사용한다.

파라미터 테이블

파라미터	타입	기본값	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와 반드시 일치해야 한다.
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	핵심	Exponential backoff 최대 대기(ms). 이 값을 초과하지 않도록 cap된다.
net_collector_tcp_reconnect_max_retry	int	30	net_collector_tcp_reconnect_max_retry	핵심	Exponential backoff 최대 재시도 횟수. 소진 후 주기적(periodic) 재시도로 전환된다.
net_collector_tcp_reconnect_periodic_retry_ms	long	300000	net_collector_tcp_reconnect_periodic_retry_ms	핵심	max_retry 소진 후 주기적 재시도 간격(ms). 기본 5분 간격으로 무기한 재시도한다.
net_tcp_batch_max_bytes	int	60000	net_tcp_batch_max_bytes	핵심	TCP 배치 전송 최대 바이트. 이 크기를 초과하면 즉시 flush한다.
net_tcp_collection_interval_ms	long	100	net_tcp_collection_interval_ms	고급	TCP 수집 데이터 전송 주기(ms). 배치가 max_bytes에 도달하지 않아도 이 간격마다 flush한다.
net_local_udp_ip	String	-	net_local_udp_ip	Deprecated	V3 이전 UDP 로컬 바인딩 IP. V3에서는 사용하지 않는다.
net_local_udp_port	int	-	net_local_udp_port	Deprecated	V3 이전 UDP 로컬 바인딩 포트. V3에서는 사용하지 않는다.
net_collector_udp_port	int	-	net_collector_udp_port	Deprecated	V3 이전 수집 서버 UDP 포트. V3에서는 사용하지 않는다.

동작 원리: TCP 재연결 Exponential Backoff

수집 서버와의 연결이 끊어지면 에이전트는 다음 알고리즘으로 재연결을 시도한다.

[TCP 재연결 알고리즘]

delay = initial_delay_ms                    // 1000ms
retry_count = 0

PHASE 1: Exponential Backoff
  while retry_count < max_retry:            // max_retry = 30
    wait(delay)
    result = try_connect(collector_ip, tcp_port, connection_timeout_ms)
    if result == SUCCESS:
      return CONNECTED
    retry_count++
    delay = min(delay * 2, max_delay_ms)    // cap at 30000ms

PHASE 2: Periodic Retry (무기한)
  loop:
    wait(periodic_retry_ms)                 // 300000ms = 5분
    result = try_connect(collector_ip, tcp_port, connection_timeout_ms)
    if result == SUCCESS:
      return CONNECTED

[Backoff 진행 예시]
  Retry 1:  1초 후 시도
  Retry 2:  2초 후 시도
  Retry 3:  4초 후 시도
  Retry 4:  8초 후 시도
  Retry 5:  16초 후 시도
  Retry 6:  30초 후 시도 (cap)
  Retry 7~30: 30초 간격
  Retry 31+: 5분 간격 (periodic)

연관 관계

net_collector_ip ──┐
net_collector_tcp_port ──┤── 연결 대상 (수집 서버의 net_tcp_listen_port와 일치 필수)
                         │
net_collector_tcp_connection_timeout_ms ── 연결 수립 타임아웃
net_collector_tcp_so_timeout_ms ── 연결 후 읽기 타임아웃
                         │
net_collector_tcp_reconnect_initial_delay_ms ──┐
net_collector_tcp_reconnect_max_delay_ms ──────┤── Backoff 파라미터 그룹
net_collector_tcp_reconnect_max_retry ─────────┤
net_collector_tcp_reconnect_periodic_retry_ms ─┘
                         │
net_collector_tcp_session_count ── 병렬 세션 (독립)
net_tcp_batch_max_bytes ──┐
net_tcp_collection_interval_ms ──┘── 배치 전송 제어 그룹

---

2. 오브젝트 식별 (Object Identity)

대시보드에서 에이전트를 식별하고 분류하는 파라미터이다. 같은 수집 서버에 연결된 에이전트 간에 obj_name이 중복되면 system_on_object_duplicate 알림이 발생한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
obj_name	String	""	obj_name	필수	오브젝트 이름. 수집 서버 내에서 고유해야 한다. 미설정 시 obj_type + 순번으로 자동 생성된다(예: tomcat1).
monitoring_group_type	String	""	monitoring_group_type	필수	모니터링 그룹 타입 (신규 키). 설정 시 obj_type을 오버라이드한다. 대시보드의 오브젝트 분류 기준이 된다.
obj_type	String	""	obj_type	필수	오브젝트 그룹 타입. monitoring_group_type의 deprecated alias이다. 신규 설정에서는 monitoring_group_type을 사용한다.
obj_host_name	String	SysJMX.getHostName()	obj_host_name	필수	호스트 이름. 미설정 시 OS 호스트네임을 자동 감지한다.
obj_host_type	String	""	obj_host_type	고급	호스트 타입. 호스트 분류 용도로 사용한다.
obj_name_auto_pid_enabled	boolean	false	obj_name_auto_pid_enabled	고급	PID를 오브젝트 이름 suffix로 사용한다. 동일 서버에서 다수 인스턴스를 운영할 때 중복 방지에 유용하다.
obj_type_inherit_to_child_enabled	boolean	false	obj_type_inherit_to_child_enabled	참조	DS/RP 하위 오브젝트에 메인 오브젝트 타입을 상속한다.
jmx_counter_enabled	boolean	false	jmx_counter_enabled	참조	JMX를 통해 서브 카운터를 수집한다. 추가적인 JVM 메트릭이 필요할 때 활성화한다.
kube	boolean	자동 감지	kube	고급	K8s 환경 여부. 환경 변수(KUBERNETES_SERVICE_HOST)로 자동 감지되며, 수동 오버라이드도 가능하다.
obj_host_name_follow_host_agent	boolean	true	obj_host_name_follow_host_agent	고급	Host Agent 이름을 따른다. K8s 환경에서 Pod 이름 동기화에 사용된다.

동작 원리: obj_name 자동 생성

obj_name이 빈 문자열이면 에이전트가 기동 시 자동으로 이름을 생성한다.

[obj_name 자동 생성 알고리즘]

if obj_name != "":
  name = obj_name
else:
  if obj_type != "":
    base = obj_type
  else:
    base = detect_was_type()              // tomcat, jboss, weblogic 등 자동 감지
  name = base + sequence_number           // tomcat1, tomcat2, ...

if obj_name_auto_pid_enabled:
  name = name + "_" + PID                 // tomcat1_12345

[monitoring_group_type vs obj_type 우선순위]

effective_type = monitoring_group_type    // 신규 키 우선
if effective_type == "":
  effective_type = obj_type              // deprecated alias 폴백
if effective_type == "":
  effective_type = detect_was_type()     // 자동 감지

[K8s 환경 obj_host_name 동기화]

if kube == true AND obj_host_name_follow_host_agent == true:
  obj_host_name = host_agent_reported_name
  // Pod 이름에서 순차 번호 suffix 자동 추가

연관 관계

monitoring_group_type ──▶ obj_type (deprecated alias, 폴백 관계)
                    │
obj_name ───────────┤── 오브젝트 고유 식별자
obj_name_auto_pid_enabled ──┘── PID suffix 추가 옵션

obj_host_name ──┐
obj_host_name_follow_host_agent ──┤── 호스트 이름 결정 그룹
kube ───────────┘── K8s 자동 감지 시 호스트 이름 동기화

obj_type_inherit_to_child_enabled ── DS/RP 하위 오브젝트 타입 상속
jmx_counter_enabled ── JMX 카운터 수집 (독립)

---

3. 프로파일링 (Profiling) — P0/P1

트랜잭션 내부의 SQL, HTTP, 메서드 호출 등 상세 스텝을 기록하는 파라미터이다. P2/P3 파라미터는 10-2.agent-java-params-advanced.md를 참조한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
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. 이 값을 초과하면 수집 서버로 flush 후 새 버퍼를 할당한다.
profile_force_end_stuck_millis	int	300000	profile_force_end_stuck_millis	핵심	스턱 서비스 강제 종료 시간(ms). 0이면 비활성화. 무한 루프/데드락 방어 용도이다.

동작 원리: 프로파일 버퍼 순환

에이전트는 트랜잭션 진행 중 프로파일 스텝을 메모리 버퍼에 축적하며, 버퍼가 가득 차면 수집 서버로 전송한다.

[프로파일 버퍼 순환 알고리즘]

초기화:
  buffer = new StepBuffer(capacity = profile_step_max_keep_in_memory_count)
  // 최소값 보장: capacity = max(128, capacity)
  total_step_count = 0

트랜잭션 진행 중 스텝 기록:
  function add_step(step):
    total_step_count++

    if total_step_count > profile_step_max_count:
      return SKIP                          // 최대 스텝 초과 시 무시

    buffer.add(step)

    if buffer.size() >= capacity:
      send_to_collector(buffer)            // 수집 서버로 배치 전송
      buffer = new StepBuffer(capacity)    // 새 버퍼 할당

트랜잭션 종료:
  if buffer.size() > 0:
    send_to_collector(buffer)              // 잔여 스텝 전송

[예시: profile_step_max_count=1024, profile_step_max_keep_in_memory_count=2048]
  - 스텝 1~1024: 정상 기록. 2048개 메모리 용량 내이므로 flush 없음
  - 스텝 1025~: SKIP (max_count 초과)
  - 트랜잭션 종료 시 잔여 1024 스텝을 수집 서버로 전송

[예시: profile_step_max_count=4096, profile_step_max_keep_in_memory_count=2048]
  - 스텝 1~2048: 정상 기록. 버퍼 가득 → 수집 서버로 전송, 새 버퍼 할당
  - 스텝 2049~4096: 새 버퍼에 기록. 2048 도달 시 재전송
  - 스텝 4097~: SKIP (max_count 초과)

동작 원리: Stuck 서비스 강제 종료

트랜잭션 경과 시간이 profile_force_end_stuck_millis를 초과하면 에이전트가 해당 트랜잭션을 강제 종료한다.

[Stuck 서비스 강제 종료 알고리즘]

모니터링 스레드 (주기적 체크):
  for each active_transaction in active_list:
    elapsed = now() - active_transaction.start_time

    if profile_force_end_stuck_millis > 0 AND elapsed > profile_force_end_stuck_millis:
      // 1. 트랜잭션 종료 마킹
      active_transaction.mark_as_force_ended()

      // 2. 프로파일 데이터 전송 (수집된 스텝까지)
      send_profile(active_transaction)

      // 3. Alert 전송
      if profile_force_end_stuck_alert:
        send_alert("Stuck service force-ended: " + active_transaction.service_name)

      // 4. 스레드 인터럽트 (선택)
      if profile_force_end_stuck_with_interrupt:
        active_transaction.thread.interrupt()
        // 주의: Thread.interrupt()는 InterruptedException을 발생시킬 수 있으며,
        //        일부 라이브러리에서 예상치 못한 동작을 유발할 수 있다

---

4. 트레이싱 (Tracing) — P0/P1

트랜잭션 추적, 사용자 식별, Active Thread 모니터링을 제어하는 파라미터이다. P2/P3 파라미터는 10-2.agent-java-params-advanced.md를 참조한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
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).
trace_user_mode	int	2	trace_user_mode	핵심	사용자 식별 모드. 0=IP hash, 1=JSESSIONID cookie, 2=FlowKat Cookie, 3=Custom header.

동작 원리: Active Thread 3색 분류

대시보드의 Active Thread 차트는 트랜잭션 경과 시간에 따라 3가지 색상으로 분류한다.

[Active Thread 3색 분류 알고리즘]

for each active_transaction in active_list:
  elapsed = now() - active_transaction.start_time

  if elapsed < trace_activeservice_yellow_time:       // < 3000ms
    color = NORMAL (파란색/초록색)
    // 정상 범위. 대부분의 트랜잭션이 이 범위에 있어야 한다.

  else if elapsed < trace_activeservice_red_time:     // < 8000ms
    color = WARNING (노란색)
    // 경고 범위. 지연 발생 가능성이 있다.

  else:                                               // >= 8000ms
    color = CRITICAL (빨간색)
    // 위험 범위. 즉시 원인 분석이 필요하다.

[운영 환경별 권장 설정]

  일반 웹 서비스:
    yellow_time = 3000ms, red_time = 8000ms (기본값)

  배치/리포트 서비스:
    yellow_time = 10000ms, red_time = 30000ms

  실시간 거래 시스템:
    yellow_time = 1000ms, red_time = 3000ms

  구 키 호환:
    trace_activeserivce_yellow_time (오타 키) → trace_activeservice_yellow_time 으로 폴백
    두 키 모두 설정된 경우 신규 키(trace_activeservice_yellow_time)가 우선한다.

동작 원리: trace_user_mode 4가지 모드

사용자 식별 방식을 결정하는 파라미터이다. 대시보드의 "실시간 사용자 수"와 "사용자별 트랜잭션 조회"에 영향을 준다.

[trace_user_mode 동작]

mode 0: IP Hash
  user_id = hash(client_ip)
  // 장점: 설정 불필요, 모든 환경에서 동작
  // 단점: NAT/프록시 뒤에서 동일 IP로 집계됨
  // 폴백: 없음 (항상 IP 사용)

mode 1: JSESSIONID Cookie
  cookie_name = trace_user_session_key OR "JSESSIONID"
  user_id = hash(request.cookie[cookie_name])
  // 장점: 세션 기반 정확한 사용자 식별
  // 단점: 세션 쿠키 미존재 시 IP 폴백
  // 폴백: cookie 미존재 → mode 0 (IP hash) 동작

mode 2: FlowKat Cookie (기본값)
  cookie_name = "FLOWKAT"
  if request.cookie["FLOWKAT"] 존재:
    user_id = request.cookie["FLOWKAT"]
  else:
    user_id = generate_unique_id()
    response.set_cookie("FLOWKAT", user_id, max_age=trace_flowkat_cookie_max_age, path=trace_user_cookie_path)
  // 장점: 에이전트 자체 쿠키로 세션 독립적 추적
  // 단점: 브라우저 쿠키 비활성화 시 매번 신규 사용자로 집계
  // 폴백: 없음 (항상 쿠키 생성)

mode 3: Custom Header
  header_key = trace_http_client_ip_header_key
  user_id = hash(request.header[header_key])
  // 장점: API Gateway/인증 시스템 연동 가능
  // 단점: 헤더 미존재 시 IP 폴백
  // 폴백: header 미존재 → mode 0 (IP hash) 동작

---

5. XLog 에러 마킹 — P1

XLog(트랜잭션 로그)에 에러를 표시하는 조건을 제어하는 파라미터이다. 대시보드의 XLog 차트에서 에러 트랜잭션이 빨간색 점으로 표시된다. P2 파라미터는 10-2.agent-java-params-advanced.md를 참조한다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
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 실행 시간이 이 값(ms)을 초과하면 XLog에 에러를 마킹한다. 슬로우 쿼리 탐지용이다.

동작 원리

[XLog 에러 마킹 판정 흐름]

트랜잭션 종료 시:
  error = false

  // 1. HTTP 상태 코드 기반 에러
  if http_status >= 400:
    if xlog_error_off_http_status_regex != "" AND match(http_status, regex):
      error = false                        // 제외 패턴 매칭 → 에러 아님
    else:
      error = true

  // 2. 예외 기반 에러
  if exception_occurred:
    if xlog_error_off_message_regex != "" AND match(exception.message, regex):
      error = false                        // 메시지 제외 패턴 → 에러 아님
    else:
      if xlog_error_on_sqlexception_enabled AND exception instanceof SQLException:
        error = true
      if xlog_error_on_apicall_exception_enabled AND exception instanceof ApiCallException:
        error = true
      if xlog_error_on_redis_exception_enabled AND exception instanceof RedisException:
        error = true
      // ... 동일 패턴으로 MongoDB, Elasticsearch

  // 3. 임계치 기반 에러
  if jdbc_fetch_count > xlog_error_jdbc_fetch_max:
    error = true
  if sql_elapsed_ms > xlog_error_sql_time_max_ms:
    error = true

  // 4. UserTransaction 에러
  if xlog_error_check_user_transaction_enabled:
    if user_transaction_error:
      error = true

  xlog.error_flag = error

---

10. 트래픽 제어 (Traffic Control)

Active Transaction 수가 임계치를 초과하면 신규 요청을 거부하여 서버를 보호하는 파라미터이다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
control_reject_service_enabled	boolean	false	control_reject_service_enabled	핵심	트래픽 제어 활성화. 활성화하면 Active Transaction 초과 시 신규 요청을 거부한다.
control_reject_service_max_count	int	10000	control_reject_service_max_count	핵심	거부 기준 Active Transaction 수. 이 값을 초과하면 신규 요청을 차단한다.
control_reject_redirect_url_enabled	boolean	false	control_reject_redirect_url_enabled	고급	거부 시 리다이렉트 사용 여부. false이면 텍스트 응답, true이면 URL 리다이렉트이다.
control_reject_text	String	""	control_reject_text	고급	거부 시 응답 텍스트. control_reject_redirect_url_enabled=false 시 사용한다.
control_reject_redirect_url	String	""	control_reject_redirect_url	고급	거부 시 리다이렉트 URL. control_reject_redirect_url_enabled=true 시 사용한다.

동작 원리: Active Transaction 초과 시 차단

[트래픽 제어 알고리즘]

function on_request_received(request):
  if NOT control_reject_service_enabled:
    return ACCEPT                          // 제어 비활성화

  active_count = get_active_transaction_count()

  if active_count > control_reject_service_max_count:    // > 10000
    // 거부 처리
    if control_reject_redirect_url_enabled:
      response.redirect(control_reject_redirect_url)
    else:
      response.write(control_reject_text)
      response.status = 503

    // XLog에 거부 기록
    xlog.mark_as_rejected()
    return REJECT

  return ACCEPT

[운영 시나리오]

  정상 상태:
    active_count = 50 → ACCEPT (모든 요청 수락)

  부하 증가:
    active_count = 9,999 → ACCEPT (임계치 미만)

  임계치 초과:
    active_count = 10,001 → REJECT (모든 신규 요청 거부)
    // 기존 진행 중인 트랜잭션은 영향 없음
    // active_count가 max_count 이하로 내려가면 자동 복구

[권장 설정]

  일반 웹 서비스: max_count = 10000 (기본값)
  소규모 서비스: max_count = 1000~3000
  대규모 서비스: max_count = 30000~50000
  API Gateway: max_count = 50000~100000

---

12. 알림/로그/카운터 — P1

에이전트 자체의 카운터 수집 파라미터 중 P1 항목이다. P2/P3 항목은 10-2.agent-java-params-advanced.md를 참조한다.

Counter 파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
counter_enabled	boolean	true	counter_enabled	핵심	카운터 수집 활성화. 비활성화하면 TPS, 응답시간 등 기본 메트릭이 수집되지 않는다.

---

13. 디렉토리/기타

에이전트 플러그인 및 Dump 파일 저장 위치를 제어하는 파라미터이다.

파라미터 테이블

파라미터	타입	기본값	conf 키	중요도	설명
plugin_dir	String	$AGENT_HOME/plugin	plugin_dir	참조	플러그인 디렉토리. 에이전트 확장 플러그인(.jar)을 로드하는 경로이다.
dump_dir	String	$AGENT_HOME/dump	dump_dir	참조	Dump 파일 저장 디렉토리. Auto Dump, SFA Dump 결과가 저장되는 경로이다.

---

관련 문서

문서	설명
10.agent-java.md	Java Agent 설치 및 P0/P1 핵심 파라미터 가이드
10-2.agent-java-params-advanced.md	Java Agent 파라미터 고급편 (P2/P3)
14.collect-server.md	수집 서버 설정. net_tcp_listen_port와 에이전트의 net_collector_tcp_port가 일치해야 한다
17.network-ports.md	전체 시스템 네트워크 포트 매핑
parameter-inventory.md	전체 파라미터 인벤토리 (P0~P3 분류)