> For the complete documentation index, see [llms.txt](https://docs.tibero.com/prosync/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tibero.com/prosync/troubleshooting/diagnostic-guide.md). # 진단 가이드 ProSync 운영 중 문제가 발생하면 프로세스 로그, 로그 리더 트레이스, 덤프 파일 등 여러 곳의 진단 정보를 조합해 원인을 분석한다. 본 문서는 증상별로 어떤 진단 도구를 사용해야 하는지, 각 도구의 출력이 어디에 생성되고 어떻게 읽는지를 안내한다. ### 증상별 진단 도구 선택 | 증상 / 목적 | 사용 도구 | 출력 위치 | | ------------------------------ | --------------------------- | -------------------------------- | | 프로세스 오류 메시지, 동작 이상 확인 | 프로세스 로그 (`LOG_LEVEL`) | `var/<인스턴스ID>/log/` | | Redo Log 파싱 문제 (Extract 추출 오류) | 로그 리더 트레이스 (`LR_TRACE_LVL`) | `var/<인스턴스ID>/lr/` | | Apply 적용 지연, 오래 걸리는 SQL 확인 | `MONITOR` 명령 | prs\_adm 화면 | | 프로세스·스레드 상태 확인 | `STATUS` 명령 | prs\_adm 화면 | | DD(테이블 메타데이터) 불일치, 트랜잭션 큐 상태 | `TRACEDUMP` 명령 | `var/<인스턴스ID>/dump/` | | 구간별 성능 통계 (스레드별 처리량·소요시간) | `JCDUMP` 명령 | `var/<인스턴스ID>/jcdump/` | | 메모리 사용량 분석 | `ALLOCDUMP` 명령 | `var/<인스턴스ID>/alloc/` | | 프로세스 크래시 (스레드 비정상 종료) | 콜스택 덤프 파일 | `var/<인스턴스ID>/prosync.out.` | ### 런타임 디렉터리 구조 인스턴스의 모든 진단 정보는 `$PRS_HOME/var/<인스턴스ID>/` 아래에 모인다. Agent 프로세스는 별도로 `$PRS_HOME/var/agent//` 를 사용한다. ``` $PRS_HOME/var/<인스턴스ID>/ ├── log/ # 프로세스 로그 (ext/apply/llob) │ ├── ext_backup/ # ├ 로그 순환 백업 (프로세스별 분리) │ ├── apply_backup/ # │ │ └── llob_backup/ # ┘ ├── lr/ # Extract 로그 리더 작업 디렉터리 (N = Extract 번호) │ ├── *_li.log # ├ 로그 리더 트레이스 (Oracle 소스) │ ├── tli.log # ├ 로그 리더 트레이스 (Tibero 소스) │ └── redo_data_*.olr # ┘ 미커밋 트랜잭션 스냅샷 (Tibero 는 *.tlr) ├── tx/ # Apply 트랜잭션 체크포인트(txh_*.dat, txl_*.dat)·대형 tx 임시파일(part_*.dat) ├── dump/ # TRACEDUMP 출력 ├── jcdump/ # JCDUMP 출력 ├── alloc/ # ALLOCDUMP 출력 ├── path/ # Admin 명령 수신용 FIFO (extd001, applyd001, llobd 형식) ├── prosync.out. # 크래시 시 콜스택 덤프 (크래시가 없으면 존재하지 않음) └── .wallet # DB 접속 비밀번호 지갑 파일 (TDE 사용 시 .wallet_tde 추가) ``` {% hint style="info" %} Apply 의 동기화 체크포인트(TSN)는 디스크가 아니라 **타겟 DB 의 `PRS_LCT` 테이블**에 저장된다. 현재 체크포인트는 타겟 DB 에서 `SELECT TSN FROM PRS_LCT` 로 확인할 수 있으며, Apply 로그에는 `UPDATE LCT SUCCESS (<이전값> -> <새값>)` 형태로 전진 이력이 남는다. 재설치 시 이 테이블이 재생성되므로 동기화 기준점이 리셋된다는 점에 유의한다. {% endhint %} ### 프로세스 로그 #### 위치와 파일명 로그 디렉터리는 각 프로세스 cfg 의 `LOG_DIR` 파라미터가 지정한다. 설치 시 기본값은 `$PRS_HOME/var/<인스턴스ID>/log` (Agent 는 `$PRS_HOME/var/agent//log`) 이다. | 프로세스 | 로그 파일명 | | ------- | ---------------------------------------------- | | Agent | `agent_trace.log` | | Extract | `<인스턴스ID>_ext_trace.log` | | Apply | `<인스턴스ID>_apply_trace.log` | | Llob | `<인스턴스ID>_llob_trace.log` | | Admin | `adm_trace.log` (기본 `$PRS_HOME/var/admin/log`) | 프로세스 기동 시 로그 파일 앞부분에 OS 정보(`uname -a`)와 사용 중인 cfg 파일 전체 내용이 `ProSync configurations` 블록으로 기록된다. 문제 분석 시 실제 적용된 파라미터 값을 이 블록에서 먼저 확인한다. #### 로그 레벨 (LOG\_LEVEL) `LOG_LEVEL` 파라미터(1\~5, 기본값 3)가 기록할 메시지의 상세 수준을 결정한다. 설정한 값 이하 레벨의 메시지만 기록된다. | LOG\_LEVEL | 기록되는 메시지 | 표시 문자 | | ---------- | ------------- | ----------- | | 1 | FATAL + ERROR | `[F]` `[E]` | | 2 | + WARN | `[W]` | | 3 (기본) | + INFO | `[I]` | | 4 | + TRACE | `[T]` | | 5 | + DEBUG | `[D]` | {% hint style="success" %} `LOG_LEVEL` 은 재기동 없이 변경할 수 있다. 문제 재현 시에만 잠시 올렸다가 되돌리는 사용을 권장한다. ``` Admin> ALTER <인스턴스ID> APPLY SET LOG_LEVEL = '5' ``` 변경값은 메모리에만 반영되므로 프로세스를 재기동하면 cfg 값으로 되돌아간다. 자세한 내용은 본 문서 하단의 '런타임 파라미터 변경' 절을 참고한다. {% endhint %} #### 로그 한 줄 읽는 법 ``` [07-21T14:03:22.123456] [REP-12] [W] Failed to update Lowerbound Commit Tsn [prs_apply_replay.c:7912] └─ ① └─ ② └─ ③ └─ ④ └─ ⑤ ``` | 필드 | 의미 | | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | ① 시각 | `월-일T시:분:초.마이크로초` (연도는 기록되지 않음) | | ② 기록 주체 | 스레드 종류 약어 + 스레드 번호. `REA`(read), `CON`(const), `MER`(merge), `REP`(replay), `LLO`(llob), `CTH`/`MTH`/`WTH`(control/monitor/worker), `SAM`, `DMP`(dump) 등 | | ③ 레벨 | `F`/`E`/`W`/`I`/`T`/`D` | | ④ 메시지 | 로그 본문 | | ⑤ 소스 위치 | FATAL/ERROR/WARN 메시지에만 붙는다. 버그 리포트 시 함께 전달한다 | #### 로그 파일 순환 로그 파일이 `LOG_FILE_SIZE`(기본 100MB)를 넘으면 `LOG_BACKUP_DIR` 로 이동되고 새 파일이 열린다. 설치 시 기본 백업 디렉터리는 프로세스별로 분리된다 (Extract `/ext_backup`, Apply `/apply_backup`, Llob `/llob_backup`, Agent `/backup`). 백업 파일명은 원래 이름 뒤에 시각이 붙는다 (예: `agent_trace.log.260721_143000.123456`). 백업 파일들의 총 크기가 `LOG_BACKUP_SIZE` 를 넘으면 가장 오래된 파일부터 삭제되며, 기본값 0 은 **삭제하지 않음(무제한 보관)** 을 뜻하므로 디스크 용량 관리가 필요한 환경에서는 값을 지정한다. #### 컬럼 값 전체 확인 (\_PRS\_FULL\_HEX\_DUMP) {% hint style="warning" %} `LOG_LEVEL=5` 에서 출력되는 컬럼 값 hex dump 는 기본적으로 **첫 16바이트 한 줄만** 출력되며, 잘렸다는 표시가 없다. 값이 짧아 보여도 실제로는 뒷부분이 생략된 것일 수 있다. {% endhint %} 컬럼 값 깨짐을 분석할 때는 히든 파라미터 `_PRS_FULL_HEX_DUMP=Y` 를 cfg 파일에 직접 추가하고 (템플릿에 없는 파라미터다) 프로세스를 재기동한다. `LOG_LEVEL=5` 와 함께 사용하면 값 전체가 16바이트 단위 여러 줄로 출력되고, Apply 의 batch INSERT/UPDATE/DELETE 실행 직전에 바인드 값 전체 덤프(`NEW COLS DUMP`, `OLD COLS DUMP` 등)가 추가로 기록된다. ### 로그 리더 트레이스 (LR\_TRACE\_LVL) {% hint style="warning" %} Redo Log 파싱 과정은 `LOG_LEVEL` 을 올려도 보이지 않는다. 로그 리더는 별도 파라미터 `LR_TRACE_LVL` 과 별도 트레이스 파일을 사용한다. {% endhint %} `LR_TRACE_LVL`(1\~5, 기본값 2) 이 로그 리더 트레이스의 상세 수준을 결정하며, 값이 높을수록 상세하다. 소스 DB 가 Oracle 또는 Tibero 인 Extract 에만 적용되고, PostgreSQL 소스에는 사용되지 않는다. {% tabs %} {% tab title="Oracle 소스" %} 트레이스 파일: `$PRS_HOME/var/<인스턴스ID>/lr/<인스턴스ID>_ext_li.log` 위치는 `LR_LOG_DIR`, 크기·백업은 `LR_LOG_FILE_SIZE` / `LR_LOG_BACKUP_DIR` / `LR_LOG_BACKUP_SIZE` 파라미터로 제어한다. 트레이스 한 줄에는 공통 로그 형식 뒤에 트랜잭션 ID(`[xid]`)와 Redo 레코드 주소(`(0x..)`)가 포함되어 문제 레코드의 위치를 특정할 수 있다. {% endtab %} {% tab title="Tibero 소스" %} 트레이스 파일: `$PRS_HOME/var/<인스턴스ID>/lr/tli.log` {% endtab %} {% endtabs %} 재기동 없이 변경할 수 있다. 파싱 문제 분석 시 레벨을 올려 문제 구간을 재현한 뒤 기본값으로 되돌린다. ``` Admin> ALTER <인스턴스ID> EXT SET LR_TRACE_LVL = '5' ``` {% hint style="info" %} `lr/` 디렉터리의 `redo_data_*.olr` 파일(Tibero 는 `*.tlr`)은 트레이스가 아니라 **미커밋 트랜잭션 스냅샷**이다. Extract 재기동 시 이 파일을 읽어 추출을 재개하므로 임의로 삭제하면 안 된다. 자동 삭제 방식은 `LR_FILE_DELETE_MODE`(`SIZE`|`CNT`|`RETENTION`, 기본값 `CNT`)가 결정하며, 선택된 모드에 해당하는 파라미터(`LR_FILE_TOTAL_SIZE` / `LR_FILE_CNT` / `LR_FILE_RETENTION_DAY`)만 적용된다. 해당 파라미터의 기본값 0 은 자동 삭제를 하지 않는다. {% endhint %} ### Admin 진단 명령 prs\_adm 에서 실행하는 진단 명령 요약이다. 명령어 기본 사용법은 [명령어 목록](/prosync/administration/admin/command/lists.md) 을 참고한다. | 명령 | 용도 | 대상 프로세스 | 출력 | | -------------------------------- | ------------------------- | -------------- | -------------------- | | `STATUS [inst_id]` | 프로세스·스레드 상태 확인 | 전체 | prs\_adm 화면 | | `MON[ITOR] ` | Replay 스레드별 실행 중 SQL·경과시간 | Apply(1번) | prs\_adm 화면 | | `TRACE[DUMP] [종류]` | in-memory DD·트랜잭션 큐 덤프 | Apply | `var//dump/` | | `JC[DUMP] [프로세스] [라벨]` | 성능 통계 스냅샷 | Ext/Apply/Llob | `var//jcdump/` | | `ALLOC[DUMP] [프로세스]` | 메모리 할당 현황 덤프 | Ext/Apply/Llob | `var//alloc/` | #### MONITOR — Apply 지연 분석 Apply 가 느릴 때 어떤 replay 스레드가 어떤 SQL 에서 시간을 쓰고 있는지 확인한다. ``` Admin> MONITOR <인스턴스ID> ========= Thread #0 Applying... 1523(ms) ========= Query: UPDATE "OWNER"."TABLE1" SET ... ========= Thread #1 Completed ========= Query: INSERT INTO "OWNER"."TABLE2" ... ``` `Applying... <경과시간>(ms)` 인 스레드가 현재 SQL 을 적용 중인 것이다. `Completed` 스레드에도 Query 블록이 출력되는데, 이는 현재 실행 중이 아니라 **마지막으로 실행한** SQL 이다. 특정 스레드의 경과시간이 계속 크다면 해당 SQL(대상 테이블의 인덱스 유무, lock 대기 등)을 점검한다. MONITOR 는 인스턴스의 1번 Apply 프로세스를 대상으로 한다. #### TRACEDUMP — DD·트랜잭션 큐 덤프 Apply 가 메모리에 들고 있는 상태를 파일로 남긴다. 소스·타겟 간 DD 불일치나 트랜잭션 대기 상태 분석에 사용한다. ``` TRACE[DUMP] [DD | MER[GE] | QUE[UE] | DEP[ENDENCY]] ``` | 종류 | 내용 | 파일명 (`var//dump/`) | | ------------ | -------------------------------- | ----------------------------------------------------------------------- | | `DD` | 테이블 메타데이터 (const/replay 스레드용 2벌) | `_const_dd__.dump`, `_replay_dd__.dump` | | `MERGE` | 다중 소스 merge 큐의 대기 stmt | `_merge__.dump` | | `QUEUE` | 병렬 replay 의 wait/replay 큐 | `_queue__.dump` | | `DEPENDENCY` | replay 스레드별 트랜잭션 의존성 표 | `_txdep__.dump` | 종류를 생략하면 전체를 덤프한다. 같은 이름의 기존 파일은 덮어쓴다. {% hint style="info" %} `MERGE` 는 소스 DB 가 2개 이상일 때만, `QUEUE` 는 병렬 replay 모드일 때만 내용이 기록된다. 해당 구성이 아니면 내용(큐 항목) 없이 빈 파일 또는 헤더만 있는 파일이 생성되는 것이 정상이다. {% endhint %} #### JCDUMP — 구간 성능 통계 프로세스 내부의 스레드별 성능 카운터(호출 횟수·처리량·소요시간)를 스냅샷으로 남기고, 두 스냅샷의 차이를 리포트로 출력한다. "부하 구간에서 어느 스레드·어느 단계가 병목인가"를 확인하는 도구다. {% stepper %} {% step %} **부하 전 스냅샷** ``` Admin> JCDUMP <인스턴스ID> APPLY before_load ``` `var/<인스턴스ID>/jcdump/jcdump_<시각>_apply_before_load` 파일이 생성된다. 라벨(마지막 인자)은 생략 가능하지만 붙여두면 COMPARE 때 파일을 찾기 쉽다. {% endstep %} {% step %} **부하 후 스냅샷** 분석하려는 구간이 지난 뒤 같은 명령을 라벨만 바꿔 실행한다. ``` Admin> JCDUMP <인스턴스ID> APPLY after_load ``` {% endstep %} {% step %} **차이 리포트 출력** ``` Admin> JCDUMP COMPARE <인스턴스ID> before_load after_load ``` 스레드별로 stat 이름(`JC_*`)·Count·Value·Time·Max 표가 출력된다. 파일 인자는 파일명의 일부만 입력해도 되며, 여러 개가 매칭되면 후보 목록에서 선택한다. 파일 하나만 주면 프로세스 기동 이후의 누적치를 출력한다. {% endstep %} {% endstepper %} {% hint style="warning" %} 스냅샷 원본 파일은 stat 번호와 16진수 카운터라 직접 읽기 어렵다 — 반드시 `JCDUMP COMPARE` 로 리포트를 생성한다. 또한 프로세스가 재기동되면 스냅샷 식별자가 바뀌어 재기동 전후의 파일은 비교할 수 없다 (`id mismatch` 오류). {% endhint %} #### ALLOCDUMP — 메모리 사용 분석 프로세스의 메모리 할당 현황(할당자 계층별 사용량)을 덤프한다. 메모리 사용량이 계속 증가할 때 어느 모듈이 점유 중인지 확인하는 용도다. ``` Admin> ALLOCDUMP <인스턴스ID> APPLY ``` `var/<인스턴스ID>/alloc/` 에 `PROSYNC_DUMP__Apply..<시각>` 파일이 생성된다. 접속 DB 가 Tibero 인 경우 DB 클라이언트 라이브러리 메모리를 담은 `CLI_DUMP_*` 파일이 추가로 생성된다. ### 크래시 진단 {% hint style="danger" %} ProSync 는 크래시 시 OS core 파일을 만들지 않는다. 자체 시그널 핸들러가 콜스택을 파일로 남기고 **문제가 발생한 스레드만 종료**하므로 (단, control 스레드에서 크래시가 나면 프로세스 전체가 종료된다), 프로세스가 `ps` 에 살아 있어도 내부 스레드가 죽어 동기화가 멈춰 있을 수 있다. {% endhint %} #### 크래시 확인 방법 다음 두 가지로 확인한다. 1. **콜스택 덤프 파일 존재 여부** — `$PRS_HOME/var/<인스턴스ID>/prosync.out.` (Agent 는 `var/agent//prosync.out.`). 이 파일은 크래시가 있었을 때만 생성된다. 2. **프로세스 로그의 FATAL 메시지** — 크래시 시 다음 순서로 기록된다. ``` [F] Signal 11 (SIGSEGV) caught (PID = 12345): si_addr = 0x... [F] callstack dumped to /prosync/var/tib2tib/prosync.out.12345 [F] replay thread terminated abnormally. ``` `STATUS <인스턴스ID>` 명령으로도 프로세스 내 스레드별 상태를 확인할 수 있다. #### 콜스택 덤프 파일 (prosync.out) ``` *** 2026/07/21 14:03:22.123 *** [00] 0x004a1b2c:0x7f... = prs_replay_bind_value + 0x01a4 [01] 0x004a0f00:0x7f... = ?????? [02] 0x00401234:0x7f... = start_thread + 0x00d5 ``` 같은 프로세스에서 크래시가 반복되면 한 파일에 누적(append)된다. 함수명은 근사 매칭이므로 오프셋이 실제와 다를 수 있다. 버그 리포트 시 이 파일과 로그의 `Signal ... caught` 메시지를 함께 전달한다. 리포트 항목은 [Bug Report](/prosync/troubleshooting/bug-report.md) 를 참고한다. #### 프로세스 종료와 시그널 ProSync 프로세스는 `SIGTERM`/`SIGINT`/`SIGHUP` 을 무시한다. 일반 `kill` 이나 `Ctrl-C` 로는 종료되지 않으며, 정상 종료 수단은 prs\_adm 의 `SHUTDOWN` 명령이다 (불가피한 경우에만 `kill -9` 를 사용한다). ``` Admin> SHUTDOWN <인스턴스ID> [EXT|APPLY|LLOB] [ABORT] ``` #### gdb 분석 (\_SLEEP\_ON\_SIG) 개발 지원이 필요한 크래시 분석 시, 히든 파라미터 `_SLEEP_ON_SIG=Y` 를 cfg 에 추가하고 재기동하면 크래시 시그널을 받은 스레드가 종료되지 않고 대기 상태로 남아 gdb attach 가 가능하다. {% hint style="warning" %} `_SLEEP_ON_SIG=Y` 상태에서 크래시가 나면 해당 스레드는 gdb 로 개입하기 전까지 무한 대기한다. SIGSEGV 등 일반 크래시에서는 대기가 콜스택 덤프보다 먼저라 개입 전까지 `prosync.out` 파일도 생성되지 않는다 (SIGABRT 는 덤프를 먼저 남긴 뒤 대기한다). 상시 운영 환경에는 설정하지 않는다. {% endhint %} ### 런타임 파라미터 변경 (ALTER ... SET) 진단 관련 파라미터 대부분은 재기동 없이 변경할 수 있다. ``` ALTER [EXT[RACT] | APP[LY] | LLOB] SET <파라미터> = <값> ``` * 프로세스 타입을 생략하면 인스턴스의 모든 프로세스에 전송된다. 파라미터를 지원하지 않는 프로세스는 `not supported.` 로 응답하므로, 대상 프로세스를 명시하는 것을 권장한다. * 변경값은 **메모리에만 반영**된다. 프로세스를 재기동하면 cfg 파일 값으로 되돌아가므로, 영구 변경은 cfg 파일도 함께 수정한다. * 성공 시 `Process Apply(num :'1') changed parameter('LOG_LEVEL' = '5').` 형태로 출력된다. 런타임 변경이 가능한 파라미터는 프로세스별로 다음과 같이 제한되며, 목록에 없는 파라미터는 `not supported.` 오류가 반환된다. | 프로세스 | 런타임 변경 가능 파라미터 | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Extract | `LOG_LEVEL`, `LOG_FILE_SIZE`, `LOG_BACKUP_SIZE`, `LR_TRACE_LVL`, `ENABLE_NETWORK_COMPRESS`, `EXT_TO_SAM`, `SAM_BIND_VALUE`, `SAM_LOG_PREFIX`, `SAM_FILE_SIZE`, `SAM_BACKUP_SIZE`, `LR_FILE_RETENTION_DAY`, `RETENTION_FILE_CLEANUP_INTERVAL` | | Apply |

LOG\_LEVEL, LOG\_FILE\_SIZE,

LOG\_BACKUP\_SIZE, TX\_HASH\_SIZE, APPLY\_TO\_SAM, SAM\_BIND\_VALUE, SAM\_LOG\_PREFIX, SAM\_FILE\_SIZE, SAM\_BACKUP\_SIZE, APPLY\_REPORT\_FILE\_SIZE, APPLY\_REPORT\_BACKUP\_SIZE, DISCARD\_FILE\_YN, DISCARD\_FILE\_SIZE, DISCARD\_BACKUP\_SIZE, TX\_HASH\_FILE\_RETENTION\_DAY, RETENTION\_FILE\_CLEANUP\_INTERVAL,

DISCARD\_DDL\_FILE\_YN , DISCARD\_DDL\_FILE\_SIZE , DISCARD\_DDL\_BACKUP\_SIZE

| | Llob | `LOG_LEVEL`, `LOG_FILE_SIZE`, `LOG_BACKUP_SIZE` | 각 파라미터의 의미와 유효 범위는 [참고자료\_파라미터](/prosync/appendix-parameters.md) 를 참고한다.