ClickHouse Response Log 테이블 설계 문서

1. 테이블 개요

API 응답 로그를 저장하기 위한 테이블로, 각 요청의 처리 시간과 결과를 추적하고 분석하기 위한 목적으로 설계되었습니다.

CREATE TABLE response_log
(
    method        String,
    path          String,
    host          String,
    status_code   UInt16,        
    elapsed_time  UInt32,        
    timestamp     DateTime,
    
    response_date Date MATERIALIZED toDate(timestamp),
    is_error      UInt8 MATERIALIZED status_code >= 500 ? 1 : 0
)
    ENGINE = MergeTree()
    PARTITION BY toYYYYMM(timestamp)
    ORDER BY (timestamp, status_code)
    SETTINGS index_granularity = 8192;

2. 컬럼 설계

2.1 기본 컬럼

컬럼명	데이터 타입	설명	선정 근거
method	String	HTTP 메서드	- 길이가 가변적이지만 짧은 문자열 (GET, POST 등)
			- 제한된 종류의 값만 존재하나, Enum보다 String이 더 유연함
path	String	요청 경로	- URL 경로는 가변 길이
			- 문자열 검색이 필요한 필드
host	String	서버 호스트명	- 호스트명은 일반적으로 고정된 값
			- 멀티 호스트 환경 지원 필요
status_code	UInt16	HTTP 상태 코드	- HTTP 상태 코드는 양수이며 65535를 넘지 않음
			- UInt16으로 충분한 범위 커버
elapsed_time	UInt32	응답 처리 시간(ms)	- 처리 시간은 양수
			- 최대 ~4.2M ms (약 71분)까지 저장 가능
timestamp	DateTime	요청 발생 시간	- 초 단위 정밀도로 충분
			- 파티셔닝과 정렬에 사용

2.2 MATERIALIZED 컬럼

컬럼명	데이터 타입	계산식	설계 근거
response_date	Date	`toDate(timestamp)`	- 일자별 통계를 위한 최적화
			- timestamp에서 자동 생성되어 저장 공간 절약
is_error	UInt8	`status_code >= 500 ? 1 : 0`	- 서버 에러 빠른 필터링 용도
			- Boolean 대신 UInt8 사용으로 집계 최적화

3. 테이블 엔진 설정

3.1 ENGINE = MergeTree()

선정 이유:
- 높은 INSERT 성능 필요
- 시계열 데이터 특성상 Range 스캔 빈번
- 백그라운드 데이터 병합으로 저장 최적화

3.2 PARTITION BY toYYYYMM(timestamp)

설계 근거:
- 월별 파티셔닝으로 적절한 파티션 크기 유지
- 오래된 데이터 삭제 용이
- 월 단위 조회가 빈번할 것으로 예상

3.3 ORDER BY (timestamp, status_code)

설계 근거:
- 시간 기반 Range 스캔 최적화
- status_code 추가로 에러 상태 빠른 필터링
- 복합 정렬로 시간대별 에러 분석 쿼리 성능 향상

3.4 index_granularity = 8192

설계 근거:
- ClickHouse 기본값 사용
- 일반적인 로그 조회 패턴에 적합
- 메모리 사용량과 쿼리 성능의 적절한 균형점

ClickHouse Response Log 테이블 설계 문서

1. 테이블 개요

2. 컬럼 설계

2.1 기본 컬럼

2.2 MATERIALIZED 컬럼

3. 테이블 엔진 설정

3.1 ENGINE = MergeTree()

3.2 PARTITION BY toYYYYMM(timestamp)

3.3 ORDER BY (timestamp, status_code)

3.4 index_granularity = 8192

4. 성능 고려사항

4.1 성능 최적화 포인트