Prometheus TSDB 내부 구조: WAL, Chunks, Blocks, Compaction

data/
  |-- wal/
  |     |-- 00000001
  |     |-- 00000002
  |     +-- 00000003
  |
  |-- chunks_head/
  |     |-- 000001
  |     +-- 000002
  |
  |-- 01BKGV7JBM69T2G1BGBGM6KB12/   (Block ULID)
  |     |-- meta.json
  |     |-- index
  |     |-- chunks/
  |     |     |-- 000001
  |     |     +-- 000002
  |     +-- tombstones
  |
  |-- 01BKGTZQ1SYQJTR4PB43C8PD98/   (Block ULID)
  |     |-- meta.json
  |     |-- index
  |     |-- chunks/
  |     +-- tombstones
  |
  |-- lock
  +-- queries.active

세그먼트 파일 내부 구조:
+----------+----------+----------+-----+
| Record 1 | Record 2 | Record 3 | ... |
+----------+----------+----------+-----+

각 Record:
+--------+--------+---------+------+
| Type   | Length | CRC32   | Data |
| 1 byte | varint | 4 bytes | ...  |
+--------+--------+---------+------+

Series Record:
+----------+-------------------+
| Series ID| Labels (name/value pairs) |
+----------+-------------------+

Samples Record:
+----------+-----------+-------+
| Series ID| Timestamp | Value |
+----------+-----------+-------+

WAL 체크포인트 프로세스:
1. 현재 활성 시계열 목록 수집
2. 체크포인트 디렉토리 생성 (checkpoint.NNNNN)
3. 활성 시계열의 Series Record 기록
4. 이전 체크포인트 및 해당 WAL 세그먼트 삭제

Head Block:
+------------------------------------------+
| memSeries Map                             |
|   series_id_1 -> memSeries_1             |
|   series_id_2 -> memSeries_2             |
|   ...                                     |
+------------------------------------------+
| Posting Lists (in-memory index)          |
+------------------------------------------+
| Stripe Lock Pool                         |
+------------------------------------------+

memSeries:
+------------+
| ref (ID)   |
| labels     |
| chunks     | --> [chunk_0] -> [chunk_1] -> [chunk_current]
| headChunk  | --> 현재 활성 청크 (쓰기 가능)
| firstTs    |
| lastTs     |
| lastValue  |
+------------+

Sample 1: t1 (원본 값 저장)
Sample 2: d1 = t2 - t1 (첫 번째 delta)
Sample 3: dd = (t3 - t2) - (t2 - t1) (delta-of-delta)

스크래핑이 규칙적이면 dd는 대부분 0에 가까움
-> 매우 적은 비트로 표현 가능

비트 인코딩:
dd == 0: 1 bit ('0')
-63 <= dd <= 64: 2 + 7 = 9 bits
-255 <= dd <= 256: 2 + 9 = 11 bits
-2047 <= dd <= 2048: 2 + 12 = 14 bits
그 외: 4 + 32 = 36 bits

Sample 1: v1 (원본 float64 저장, 64 bits)
Sample 2: xor = v2 XOR v1
Sample 3: xor = v3 XOR v2

연속된 값이 유사하면 XOR 결과의 대부분이 0
-> leading zeros와 trailing zeros를 이용한 압축

비트 인코딩:
xor == 0: 1 bit ('0')
leading/trailing이 이전과 같으면: 2 + significant bits
그 외: 2 + 5(leading) + 6(significant_length) + significant bits

1. 새 샘플 도착
2. headChunk에 추가
3. headChunk가 120개 샘플 또는 chunkRange(2시간)에 도달
4. headChunk 완성 처리 (immutable)
5. chunks_head/ 디렉토리에 mmap 파일로 기록
6. 새 headChunk 생성
7. 이전 청크는 mmap으로 접근 (메모리에서 해제 가능)

Block Directory:
01BKGV7JBM69T2G1BGBGM6KB12/
  |-- meta.json      (블록 메타데이터)
  |-- index          (시계열 인덱스)
  |-- chunks/
  |     |-- 000001   (청크 데이터)
  |     +-- 000002
  +-- tombstones      (삭제 마킹)

{
  "ulid": "01BKGV7JBM69T2G1BGBGM6KB12",
  "minTime": 1602547200000,
  "maxTime": 1602554400000,
  "stats": {
    "numSamples": 1234567,
    "numSeries": 5678,
    "numChunks": 9012
  },
  "compaction": {
    "level": 1,
    "sources": ["01BKGV7JBM69T2G1BGBGM6KB12"]
  },
  "version": 1
}

Index File Structure:
+------------------+
| Symbol Table     |  (모든 레이블 이름/값의 사전)
+------------------+
| Series           |  (시계열별 레이블과 청크 참조)
+------------------+
| Label Index      |  (레이블 이름 -> 가능한 값들)
+------------------+
| Postings         |  (레이블 쌍 -> 시계열 ID 목록)
+------------------+
| Postings Offset  |  (포스팅 목록의 오프셋 테이블)
+------------------+
| TOC              |  (Table of Contents)
+------------------+

예시:
job="prometheus" -> [1, 3, 5, 7, 9]
job="node"       -> [2, 4, 6, 8, 10]
instance="localhost:9090" -> [1, 2]
instance="localhost:9100" -> [3, 4]

쿼리: job="prometheus" AND instance="localhost:9090"
  -> [1, 3, 5, 7, 9] INTERSECT [1, 2]
  -> [1]

Chunk File Format:
+--------+--------+--------+-----+
| Chunk 1| Chunk 2| Chunk 3| ... |
+--------+--------+--------+-----+

각 Chunk:
+----------+----------+--------+------+
| Length   | Encoding | Data   | CRC  |
| uvarint  | 1 byte   | ...    | 4B   |
+----------+----------+--------+------+

Level 0: [2h] [2h] [2h] [2h] [2h] [2h]
                     |
                     v (compaction)
Level 1: [  6h  ] [  6h  ] [  6h  ]
                     |
                     v (compaction)
Level 2: [      18h       ] [  6h  ]

컴팩션 결정 기준:
1. 시간 범위가 같은 레벨의 블록 3개 이상이 있을 때
2. 병합 결과의 시간 범위가 retention 기간의 10%를 초과하지 않을 때
3. 병합 결과가 max-block-duration을 초과하지 않을 때

컴팩션 프로세스:
1. 병합할 블록 선택
2. 새 블록 디렉토리 생성 (임시)
3. 모든 소스 블록의 시계열 병합
4. tombstone 적용 (삭제된 데이터 제거)
5. 새 인덱스 생성
6. 새 청크 파일 생성
7. meta.json 업데이트 (level 증가, sources 기록)
8. 원자적으로 새 블록을 활성화
9. 이전 블록 삭제 (지연)

발생 상황:
- Backfill로 과거 데이터 삽입
- out-of-order 샘플 허용 설정
- 블록 복원 후 중복 발생

처리 방식:
1. 겹치는 블록 감지
2. 동일 시계열의 샘플 병합 (타임스탬프 기반 정렬)
3. 중복 샘플 제거
4. 단일 블록으로 통합

1단계 - 삭제 요청 (API 호출):
  - tombstones 파일에 삭제 범위 기록
  - 실제 데이터는 아직 존재

2단계 - 컴팩션 시:
  - tombstones를 적용하여 삭제된 범위의 데이터 제외
  - 새 블록에는 삭제된 데이터가 포함되지 않음

--storage.tsdb.retention.time=15d (기본값)

동작 방식:
1. 블록의 maxTime이 현재 시간 - retention보다 이전이면 삭제 대상
2. 컴팩션 주기마다 확인
3. 블록 단위로 삭제 (부분 삭제 불가)

--storage.tsdb.retention.size=10GB

동작 방식:
1. 모든 블록의 총 디스크 사용량 계산
2. 제한을 초과하면 가장 오래된 블록부터 삭제
3. WAL과 chunks_head는 크기 계산에서 제외

--storage.tsdb.retention.time=30d
--storage.tsdb.retention.size=50GB

- 30일이 지난 블록은 크기에 관계없이 삭제
- 50GB를 초과하면 30일 이내라도 오래된 블록부터 삭제

mmap 사용 영역:
1. 영속 블록의 인덱스 파일
2. 영속 블록의 청크 파일
3. Head Block의 완성된 청크 (chunks_head/)

mmap의 장점:
- OS가 페이지 캐시를 통해 자동으로 메모리 관리
- 필요한 부분만 메모리에 로드 (lazy loading)
- 메모리 부족 시 OS가 자동으로 페이지 해제
- Go 프로세스의 힙 메모리 부담 감소

주요 메모리 소비 영역:

1. Head Block memSeries (가장 큰 비중):
   - 시계열당 약 500바이트~1KB
   - 활성 시계열 수에 비례

2. Head Block headChunks:
   - 시계열당 하나의 활성 청크
   - 청크당 약 100~200바이트

3. Posting Lists (인메모리 인덱스):
   - 레이블 카디널리티에 비례

4. WAL 리플레이 버퍼:
   - 시작 시 일시적으로 큰 메모리 사용
   - 리플레이 완료 후 해제

5. 쿼리 실행 메모리:
   - 동시 쿼리 수와 결과 크기에 비례

--storage.tsdb.out-of-order-time-window=30m

동작 방식:
1. 현재 Head Block의 최신 타임스탬프보다 과거 샘플 도착
2. out-of-order 윈도우 내이면 별도의 WBL(Write-Behind Log)에 기록
3. Head Block에 out-of-order 청크로 저장
4. 컴팩션 시 in-order 청크와 병합

WBL vs WAL:
- WAL: in-order 샘플 전용
- WBL: out-of-order 샘플 전용
- 두 로그 모두 크래시 복구에 사용
- WBL은 OOO 윈도우가 설정된 경우에만 활성화

쓰기 경로:
WAL Write (순차 I/O) -> Head Block Update (메모리)

특성:
- WAL은 순차 쓰기만 수행하여 디스크 I/O 최적화
- Head Block은 메모리 연산으로 매우 빠름
- 초당 수백만 샘플 수집 가능

읽기 경로:
1. 쿼리 파싱 및 최적화
2. 포스팅 리스트로 관련 시계열 검색
3. 해당 시간 범위의 청크 로드
4. 청크 디코딩 및 결과 계산

최적화:
- 포스팅 리스트 교집합으로 빠른 시계열 필터링
- mmap으로 필요한 청크만 로드
- 시간 범위로 불필요한 블록 스킵