PostgreSQL 로그 설정 가이드: 슬로우 쿼리, 잠금 대기, 감사
PostgreSQL의 stderr, CSV, JSON 출력부터 슬로우 쿼리와 잠금 대기, 감사 범위, DataKit 수집 확인까지 다룹니다.
배포 직후 데이터베이스 대시보드의 응답 시간이 치솟았습니다. PostgreSQL 로그를 보면 쿼리 실행이 느렸는지, 세션이 잠금 해제를 기다렸는지 구분할 수 있습니다. 먼저 해당 이벤트가 어디에 기록됐는지 확인합니다. 컨테이너에서는 런타임이 수집한 표준 오류 출력일 수 있고, 직접 운영하는 서버에서는 PostgreSQL이 관리하는 JSON 파일일 수 있습니다.
예시는 PostgreSQL 15~18을 대상으로 합니다. 설정을 변경하기 전에 메이저 버전과 현재 로그 경로를 확인하세요.
어떤 설정에서 필요한 단서를 얻을까?
| 확인하려는 것 | 관련 설정 | 확인할 내용 |
|---|---|---|
| 서버 로그 위치 | log_destination, logging_collector |
런타임이나 서비스가 수집한 stderr 또는 current_logfiles에 나온 파일 |
| 느린 문장 | log_min_duration_statement |
완료된 문장이나 확장 프로토콜의 처리 단계가 임계값에 도달했는지 |
| 잠금 대기 | log_lock_waits |
deadlock_timeout을 넘긴 대기. 이 기록만으로 교착 상태를 확정할 수는 없음 |
| 감사에 필요한 SQL | log_statement 또는 pgAudit |
필요한 감사 범위와 문장 유형, 객체, 역할의 대응 관계 |
1. 로그 출력 위치 정하기
# postgresql.conf
logging_collector = on
log_destination = 'jsonlog'
log_directory = 'log'
log_filename = 'postgresql-%Y-%m-%d_%H%M%S.log'
log_rotation_age = 1d
log_rotation_size = 100MB
log_truncate_on_rotation = off
logging_collector를 변경하려면 재시작해야 합니다. 이미 활성화했다면 설정을 다시 읽어 log_destination 변경을 반영할 수 있습니다. csvlog와 jsonlog 모두 로깅 컬렉터가 필요합니다. JSON 출력은 PostgreSQL 15부터 사용할 수 있습니다. 상대 경로 log는 데이터 디렉터리 아래에 있으며, 같은 데이터 디렉터리의 current_logfiles에서 컬렉터가 현재 쓰는 파일을 확인할 수 있습니다.
시간과 크기 설정은 로그 회전 조건입니다. 100 MB는 파일 크기의 상한이 아니라 회전 임계값이며, 회전만으로 오래된 파일이 삭제되지는 않습니다. 파일 이름에 시각을 넣어 두면 같은 날에도 크기 기준으로 회전할 때 다른 이름으로 파일을 열 수 있습니다. 런타임이나 서비스 관리자가 이미 stderr를 수집하고 보존을 관리한다면 기존 경로를 유지해도 됩니다. PostgreSQL 로그 설정(영어) · PostgreSQL 15 릴리스 노트(영어)
2. 텍스트 로그의 접두사 정하기
log_line_prefix = '%m [%p] %c %q%u@%d %a '
%m은 밀리초를 포함한 시각, %p는 프로세스 ID, %c는 세션 식별자입니다. %s는 프로세스 시작 시각입니다. %q에서 세션과 관계없는 프로세스의 접두사 출력이 끝나므로, 뒤에 오는 사용자와 데이터베이스, 애플리케이션 이름은 세션 기록에 붙습니다. 필요에 따라 %e로 SQLSTATE를, %i로 명령 태그를 추가할 수 있습니다.
SQL 본문과 실행 시간이 서로 다른 줄에 기록될 때 세션 식별자로 두 기록을 연결할 수 있습니다. CSV나 JSON을 사용한다면 형식에 포함된 필드를 직접 읽습니다.
3. 느린 문장과 잠금 대기 기록하기
log_min_duration_statement = 500ms
log_lock_waits = on
log_checkpoints = on
log_temp_files = 0
500 ms는 설정 예시입니다. 임계값 이상 걸려 완료된 문장이 기록되며, -1은 이 기능을 끄고 0은 완료된 모든 문장의 소요 시간을 기록합니다. 확장 쿼리 프로토콜에서는 Parse, Bind, Execute를 각각 잽니다. 트래픽이 많으면 log_min_duration_sample과 log_statement_sample_rate로 더 빠른 문장 중 일부를 기록할 수 있습니다. 전체 기록 임계값에 도달한 문장에는 샘플링이 적용되지 않습니다.
log_lock_waits는 deadlock_timeout을 넘긴 잠금 대기를 기록합니다. 체크포인트 로그에서는 기록한 버퍼 수와 쓰기 시간 등을 확인할 수 있습니다. log_temp_files=0은 모든 임시 파일의 이름과 크기를 파일이 삭제될 때 기록합니다. 정렬이나 해시 연산이 디스크를 사용했는지 조사할 때 도움이 됩니다.
실행 계획이 필요하면 권한이 있는 세션에서 auto_explain을 로드하거나 필요한 범위에 미리 로드한 뒤 별도의 auto_explain.log_min_duration을 설정합니다. 실제 실행 통계나 노드별 시간 측정을 활성화하면 부하가 늘 수 있습니다. auto_explain(영어)
4. SQL과 연결 로그의 범위 제한하기
log_statement = 'ddl'
log_connections = on
log_disconnections = on
log_hostname = off
log_statement에는 none, ddl, mod, all을 지정할 수 있습니다. mod는 DDL과 조건에 해당하는 데이터 변경 문장을 기록합니다. all도 기본 구문 분석에 실패하거나 확장 프로토콜의 Execute 전에 실패한 문장은 남기지 않습니다. 이런 문장을 조사할 때는 log_min_error_statement를 확인합니다.
연결과 연결 종료 로그를 함께 보면 짧은 연결이 반복해서 만들어지는지 파악할 수 있습니다. PostgreSQL 15~17에서 log_connections는 불리언이고 18부터는 옵션 목록입니다. 18에서 호환용 on은 연결 수신, 인증, 인가를 기록하며 setup_durations는 포함하지 않습니다. 연결 종료 기록에는 세션이 유지된 시간이 들어갑니다. SQL과 바인드 매개변수에 민감한 데이터가 포함될 수 있으니 기록 기간과 접근 권한, 보존 기간을 제한하세요. PostgreSQL 17 로그 설정(영어) · PostgreSQL 18 로그 설정(영어)
5. 오류에 필요한 정보 남기기
log_error_verbosity = default
log_min_error_statement = error
log_error_verbosity는 메시지의 상세 수준을 정합니다. verbose에는 SQLSTATE와 소스 코드 위치가 들어갑니다. log_min_error_statement는 오류가 발생한 SQL 본문을 언제 포함할지 정하고, 서버 메시지 자체의 임계값은 log_min_messages가 정합니다. 오류 건수를 세려면 검증된 심각도나 SQLSTATE로 거르세요. ERROR로 실패한 쿼리와 FATAL로 종료된 세션은 의미가 다릅니다.
슬로우 쿼리 한 건으로 수집 확인하기
테스트 환경에서 식별할 수 있고 임계값에 도달하는 무해한 쿼리로 로그를 만든 뒤 원본을 확인합니다. DataKit 파일 수집(영어)에 실제 경로를 지정하고 읽기 권한을 부여합니다. DataKit PostgreSQL 연동(영어)에서도 파일 입력을 설정할 수 있습니다. 문서의 내장 파서 예시는 특정 텍스트 형식용입니다. JSON이나 CSV에는 그 형식에 맞는 파서를 설정합니다.
데이터베이스 이름, 사용자, 시각, 심각도를 원본과 대조하세요. JSON의 실행 시간은 message 안에 들어갈 수 있고 statement는 없을 수도 있습니다. 민감한 SQL을 전송하기 전에 필드 추출과 마스킹을 확인합니다. 데이터베이스 로그에서 확인한 필드와 값으로 Guance 로그 감지(영어)를 설정합니다.
자주 묻는 질문
csvlog와 jsonlog 중 무엇을 써야 하나요?
PostgreSQL 15 이상에서는 한 줄에 하나의 JSON 레코드를 쓸 수 있습니다. 일부 필드가 빠질 수 있고 타임스탬프의 시간대도 확인해야 합니다. 기존 CSV 파이프라인을 활용한다면 서버 버전에 맞는 열 순서와 따옴표, 여러 줄 값을 지원하는지 확인하세요. stderr가 이미 수집되고 있다면 실제 접두사에 맞는 텍스트 파서도 사용할 수 있습니다.
log_statement=all은 얼마나 오래 켜 둘 수 있나요?
조사를 짧게 끝내고 디스크와 I/O를 살펴보세요. 로그량은 트래픽, 문장 길이, 매개변수에 따라 달라집니다. 감사 분류나 릴레이션 단위 감사가 필요하다면 서버 버전에 맞는 pgAudit(영어)을 검토합니다. 미리 로드해야 하며, DDL 객체 정보를 남기려면 확장을 생성한 뒤 pgaudit.log를 설정합니다. 실제로 감사할 분류, 역할, 릴레이션도 확인하세요.
FATAL: remaining connection slots는 무슨 뜻인가요?
일반 역할이 쓸 수 있는 연결 슬롯을 모두 사용했다는 뜻입니다. 해당 권한이 있는 역할에 예약된 슬롯은 남아 있을 수 있습니다. 데이터베이스, 역할, 애플리케이션별 연결과 풀 사용량, 열려 있는 트랜잭션을 확인하세요. 유휴 상태만 보고 세션을 종료하지 마세요. max_connections를 변경하려면 재시작해야 하고 서버 자원 할당에도 영향을 줍니다. 연결 설정(영어)
컨테이너의 PostgreSQL 로그는 어떻게 수집하나요?
PostgreSQL이 stderr로 출력한다면 런타임이나 Kubernetes 환경에 맞는 DataKit 수집 기능을 켜고 로그 소스에 접근할 수 있도록 구성합니다. 컨테이너 안에서 파일에 쓴다면 파일 입력이 읽을 수 있는 곳에 로그 디렉터리를 마운트합니다. 같은 스트림을 두 경로에서 수집하면 중복될 수 있습니다.
