Prometheus 3.16.0 업그레이드: 호환성 변경과 TSDB 유실 수정 점검

Prometheus 3.16.0의 호환성 변경과 WAL·압축 관련 샘플 유실 수정 조건을 기준으로 업그레이드 검증 범위를 정한다.

2026-11-14

업그레이드 검증을 호환성과 저장 경로로 나눈다

Prometheus 3.16.0에는 WAL 체크포인트와 재생, selected-series·stale-series 압축에서 샘플이 유실될 수 있던 문제의 수정이 포함됐다. 동시에 Remote Write 2.0 메트릭이 제거되고 쿼리 샘플 통계의 집계 범위도 바뀐다. 프로세스가 정상 기동하는지만 확인하면 기존 대시보드의 참조 오류나 통계 해석의 변화를 놓칠 수 있다.

이 글의 기준 버전은 **Prometheus 3.16.0 (2026-11-04)**이며, 변경 사실은 공식 v3.16.0 릴리스노트에 근거한다. 운영 환경에 적용할 때는 기존 설정과 관측 체계가 영향을 받는지 확인하는 작업, 저장 경로의 수정 조건을 검증하는 작업, 새 기능의 활성화 여부를 결정하는 작업으로 나누는 편이 좋다.

아래 비교는 각 검증 영역에서 무엇을 대조하고 어떤 판단을 내려야 하는지 보여 준다.

⤢✕ Prometheus 3.16.0 업그레이드 검증 영역 호환성 영역 저장 경로 영역 새 기능 영역 검증 대상 대조할 내용 내려야 할 판단 기존 설정과 관측 체계 WAL과 압축 PromQL 기능 활성화 TLS 외부 URL 기본값 · Remote Write 2.0 메트릭 제거 · 서브쿼리 통계 · exemplar 레이블 검증 WAL 체크포인트 · WAL 재생 · selected-series 및 stale-series 압축 · 재시작 smoothed·anchored 안정화와 별도 기능 플래그 기존 설정·대시보드·알림· 입력 데이터의 수정 필요 여부 해당 조건에서 샘플과 exemplar가 보존되는지 기본 제공 기능과 선택적으로 켤 기능의 구분

기본값과 입력 검증 변경을 기존 구성에 대조한다

호환성 점검은 변경 항목을 모두 같은 무게로 읽기보다, 현재 사용하는 기능과 연결하는 데서 시작한다. 다음 항목에 해당하는 구성이나 호출이 있다면 업그레이드 검증 대상에 넣는다.

변경 영역 3.16.0의 동작 운영자가 확인할 대상
외부 URL --web.config.file로 TLS를 켜면 --web.external-url의 기본값이 https가 됨 외부 URL을 기본값에 맡기는 TLS 구성
실험적 검색 API batch_size를 최대 1000으로 제한 1000보다 큰 배치를 요청하는 호출
exemplar 저장 레이블 이름이 중복된 exemplar를 거부 exemplar를 생성하거나 전달하는 입력 경로
Remote Write 수신 통계 metadata-wal-records가 꺼져 있어도 메타데이터 없이 수집한 Remote Write 2.x 샘플·히스토그램을 집계 해당 카운터를 사용하는 대시보드와 알림
API 시간 인자 int64 범위를 넘는 timeout·lookback_delta를 거부 해당 값을 생성하는 API 클라이언트

외부 URL 변경은 TLS 사용 여부와 기본값 사용 여부를 함께 확인해야 한다. 릴리스노트가 설명하는 변경은 --web.config.file이 TLS를 활성화할 때의 기본값이다. 외부 URL을 명시한 구성까지 같은 이유로 수정할 근거는 없다.

exemplar는 이전에 저장되던 입력이 거부될 수 있다는 점을 봐야 한다. 레이블 이름이 중복된 exemplar를 저장하면 /api/v1/query_exemplars 응답에 중복 JSON 키가 나올 수 있었고, 이번 버전은 저장 단계에서 이를 거부한다. exemplar를 보내는 경로에서 레이블 이름의 유일성을 확인하고, 조회 응답만 검사하던 검증 범위를 입력까지 넓힌다.

Remote Write 대시보드는 메트릭 이름부터 검색한다

Remote Write 2.0 큐에서는 다음의 deprecated 메트릭 노출이 중단된다.

prometheus_remote_storage_metadata_total
prometheus_remote_storage_metadata_failed_total
prometheus_remote_storage_metadata_retried_total
prometheus_remote_storage_metadata_bytes_total

업그레이드 전에 대시보드, 기록 규칙, 알림 규칙에서 이 이름을 검색한다. 참조가 남아 있다면 업그레이드 후 해당 메트릭에 의존하는 패널과 규칙을 검증 대상으로 지정한다. 이 변경은 Remote Write 2.0 큐에 대한 설명이므로 다른 큐까지 일괄적으로 같은 동작이라고 해석하지 않는다. 제공된 릴리스노트에는 대체 메트릭 매핑이 없으므로, 이름이 비슷한 메트릭으로 기계적으로 치환해서도 안 된다.

수신 측에서는 다음 메트릭의 집계 조건이 바뀐다.

prometheus_api_remote_write_without_metadata_appended_samples_total

이제 metadata-wal-records가 비활성화돼 있어도 메타데이터 없이 수집한 Remote Write 2.x 샘플과 히스토그램이 집계된다. 업그레이드 전후의 값 차이를 해석할 때는 입력 데이터 변화뿐 아니라 이 집계 조건 변경도 확인해야 한다.

관련 알림도 함께 검토한다. 이번 릴리스에는 mixin의 PrometheusRemoteStorageFailures 알림에서 실패한 샘플을 분모에 중복 집계하던 수정이 포함됐다. 이 알림을 사용하는 환경이라면 알림식 변경도 비교 대상에 넣는다.

서브쿼리 통계 증가는 실행량 변화와 구분한다

PromQL 통계에서는 서브쿼리 샘플이 TotalSamples와 TotalSamplesPerStep에 포함된다. 범위 쿼리의 SamplesRead도 @ 수정자가 붙은 서브쿼리에서 발생한 읽기를 집계한다.

따라서 같은 쿼리를 실행해 통계 값이 달라졌다고 해서 곧바로 실행 비용이 늘었다고 판단하면 안 된다. 서브쿼리를 사용하는 쿼리는 통계가 세는 범위 자체가 달라졌다. 업그레이드 검증에서는 결과 값, 실행 시간, 샘플 통계를 각각 비교하고, 통계 변화가 집계 변경과 맞닿아 있는지 확인한다.

릴리스노트에는 서브쿼리를 구체화하며 만든 샘플을 총 샘플 통계에 세지 않도록 한 수정도 별도로 나온다. 이를 “서브쿼리를 포함한다”와 모순되는 설명으로 읽기보다, 서브쿼리 관련 집계에서도 어떤 샘플을 세는지 구분해야 한다는 신호로 받아들이는 편이 정확하다.

@ 수정자가 붙은 서브쿼리는 고정된 윈도만 선택하도록 성능도 개선됐다. 이 경로를 사용하는 대표 쿼리가 있다면 통계 변경과 성능 변경을 같은 검증에서 관찰하되, 어느 쪽이 원인인지 미리 단정하지 않는다.

WAL과 압축 수정은 발생 조건별로 검증한다

TSDB 수정은 “데이터 유실 버그 수정”이라는 한 항목으로 묶기에는 발생 조건이 다르다. 운영 환경에서 사용하는 저장 경로와 맞춰 검증해야 한다.

경로 릴리스노트의 문제 조건 검증 초점
WAL 체크포인트 out-of-order write-behind log가 아직 필요로 하는 시리즈 레코드를 체크포인트가 제거 out-of-order 샘플 보존
WAL 재생 같은 시리즈의 여러 참조를 병합할 때 mapped chunk를 보존하지 못함 재시작 후 out-of-order 샘플 누락과 in-order 청크 중복
selected-series·stale-series 압축 블록 기록 이후, head에서 시리즈를 제거하기 전에 샘플이 커밋됨 압축과 쓰기가 겹치는 구간의 샘플 보존
selected-series·stale-series 압축 같은 시리즈에 대한 별도 쓰기의 cleanup이 보호에 필요한 근거를 지움 별도 쓰기와 cleanup이 겹치는 조건
압축 후 재시작 exemplar 복구에 필요한 시리즈 식별 정보가 보존되지 않음 재시작 후 exemplar 복구

압축 경쟁 조건의 핵심은 블록 기록이 끝난 시점과 head에서 시리즈를 제거하는 시점 사이에 쓰기가 들어올 수 있었다는 것이다. 해당 수정은 더 이상 isolation 활성화 여부에 의존하지 않는다고 명시돼 있다. isolation 설정을 확인하는 것만으로 이 수정의 검증을 대신할 수 없다.

다음 흐름은 수정된 압축 경쟁 조건에서 샘플이 유실될 수 있었던 시간적 틈을 보여 준다.

⤢✕selected-series·stale-series압축블록 기록 완료새 샘플 커밋head에서 시리즈 제거수정 전: 새 샘플 유실 가능3.16.0: 해당 경쟁 조건 수정

운영 검증도 이 조건에 맞춘다. out-of-order 데이터를 사용하는 환경에서는 WAL 체크포인트와 재시작 전후의 조회 결과를 비교하고, selected-series·stale-series 압축을 사용하는 환경에서는 압축과 쓰기가 겹치는 상황을 검증 범위에 넣는다. 샘플 수만 보는 데 그치지 않고 재시작 이후의 샘플 누락, 청크 중복, exemplar 복구를 나누어 확인한다.

이 수정들이 이미 유실된 샘플을 복원한다고 쓰여 있지는 않다. 업그레이드 검증과 과거 데이터의 상태 확인은 구분해야 한다.

WAL 경고와 손상 카운터의 의미도 다시 읽는다

prometheus_tsdb_wal_corruptions_total은 체크포인트 생성 중 WAL 손상이 발견됐을 때도 증가하도록 바뀌었다. 재시작에 따른 복구 시점뿐 아니라 압축 시점에 발견한 손상도 메트릭에 반영한다.

이 카운터를 사용하는 알림이 있다면 값의 변화와 함께 손상이 발견된 시점을 확인한다. 업그레이드 후 증가가 보일 때, 체크포인트 생성 중의 손상이 새로 집계되는 조건인지 점검할 수 있어야 한다. 그렇다고 증가 자체를 집계 변경만으로 치부해서도 안 된다. 메트릭은 손상이 감지됐다는 사실을 반영한다.

경고와 샘플 유실도 구분한다. 디스크에 selected-series 또는 stale-series 압축으로 만든 블록만 있을 때, 재시작 후 WAL 재생 중 잘못 출력되던 "unknown series references" 경고가 수정됐다. 반면 WAL watcher가 head truncation보다 뒤처졌을 때 체크포인트 시리즈 garbage collection을 영구적으로 건너뛰던 문제는 별도의 수정이다.

재시작 검증에서는 조회 결과와 함께 WAL 재생 경고, 손상 카운터, garbage collection 관련 동작을 각자의 수정 조건에 맞춰 관찰한다.

셀렉터 안정화와 실험 기능 활성화를 분리한다

smoothed와 anchored 벡터 셀렉터는 안정화돼 항상 활성화된다. 다만 이 수정자를 사용하는 float 시계열에서 시작 타임스탬프로 카운터 리셋을 감지하는 기능은 use-start-timestamps 기능 플래그 뒤에 있다. 셀렉터를 사용할 수 있다는 사실만으로 시작 타임스탬프 기반 리셋 감지까지 활성화됐다고 판단하면 안 된다.

새 기능의 활성화 조건은 다음처럼 나뉜다.

기능 제공 상태·활성화 조건 적용 판단
smoothed·anchored 안정화, 항상 활성화 해당 셀렉터를 사용하는 쿼리 검증
시작 타임스탬프 기반 리셋 감지 use-start-timestamps 기능 플래그 필요 확장 범위 셀렉터로 조회하는 float 시계열
integral() 실험 함수 플래그 필요 범위 벡터의 시간 적분 계산이 필요한 경우
query cost query-cost 기능 플래그 필요 비용 추정·실제 비용 보고·실행 제한을 검토하는 경우

아래 비교는 기본 제공되는 셀렉터와 별도 활성화가 필요한 기능 사이의 경계를 보여 준다.

⤢✕ PromQL 안정화 범위와 별도 활성화 경계 Prometheus 3.16.0 업그레이드: 호환성 변경과 TSDB 유실 수정 점검 항상 활성화 smoothed 벡터 셀렉터 anchored 벡터 셀렉터 안정화 ≠ 자동 활성화 별도 기능 플래그 필요 시작 타임스탬프 기반 카운터 리셋 감지 적용 조건 anchored·smoothed로 조회하는 float 시계열 use-start-timestamps integral() promql-experimental-functions 쿼리 비용 추정· 실제 비용 보고·실행 제한 query-cost Prometheus 3.16.0 | infra-system

릴리스노트에 명시된 실험 기능 활성화 플래그는 다음과 같다. 업그레이드 필수 설정으로 일괄 추가하기보다, 필요한 기능의 도입 여부를 따로 판단한다.

--enable-feature=promql-experimental-functions
--enable-feature=query-cost

API에는 쿼리별로 PromQL 시작 타임스탬프 처리를 재정의하는 X-Prometheus-Use-Start-Timestamps HTTP 헤더도 추가됐다. 다만 제공된 자료에는 헤더 값과 상세 상호작용이 없으므로 여기서는 요청 예시를 만들지 않는다.

재시작과 전송 경로까지 확인하고 적용을 마친다

저장 경로 검증 뒤에는 현재 구성에 해당하는 재시작·전송 수정도 확인한다.

for 지속 시간이 --rules.alert.for-grace-period보다 짧은 firing 알림은 재시작 후 복원되도록 수정됐다. 이런 규칙을 사용한다면 재시작 직전과 이후의 알림 상태를 비교한다. 설정 자동 재적재를 사용한다면 실패한 설정 변경을 되돌렸을 때 다시 재적재되는지도 확인한다.

TLS와 http2: true를 사용하는 환경에서는 빌드의 Go 버전도 검증 조건이다. Go 1.27+에서 HTTP/2 협상이 조용히 HTTP/1.1로 떨어지던 문제가 수정됐고, 서버는 ALPN으로 h2를 광고해 단일 연결에서 동시 요청을 다중화하도록 바뀌었다. 이 조건에 해당한다면 TLS 연결 성공 여부와 실제 협상된 HTTP 프로토콜을 함께 확인한다.

규칙 테스트를 사용하는 환경에는 promtool의 test rules가 --enable-feature를 따르도록 한 수정도 있다. 실험 기능을 사용하는 규칙이라면 테스트에 전달하는 기능 플래그를 실제 운영 설정과 대조한다.

업그레이드 완료 판단은 각 환경에서 선택한 검증 항목으로 내린다. 제거된 메트릭의 참조를 처리했는지, 서브쿼리 통계 차이를 설명할 수 있는지, 사용하는 WAL·압축 경로에서 데이터가 보존되는지, 재시작 후 알림과 전송이 기대대로 동작하는지가 그 근거다. 새 PromQL 기능 활성화는 이 검증과 별도의 변경으로 기록하면 적용 결과를 해석하기 쉽다.

PrometheusPromQLTSDBWAL모니터링