# Prometheus v3.5.0

2025-07-14 · [릴리스 노트 원문](https://github.com/prometheus/prometheus/releases/tag/v3.5.0) · [전체 정리](https://ratatosk.io/ko/releases/prometheus/v3.5.0)

보안 1 · 호환성 변경 1 · 중요 수정 16 · 기능·개선 12 · 기타 9

## 보안 (1)

### CORS 응답의 Origin별 구분

- 영향 대상: 응답이 `SetCORS`를 거치는 HTTP 엔드포인트 (추정)

이렇게 하면 Origin을 기준으로 구분하지 않은 응답이 캐시에서 재사용되는 일을 방지합니다.

> * [BUGFIX] API: Add HTTP `Vary: Origin` header to responses to avoid cache poisoning. #16008

## 호환성 변경 (1)

### 문자열 레이블 크기 인코딩 변경 및 길이 16MB 제한

- 영향 대상: 레이블 이름이나 값이 16MB를 초과하는 설정 (추정)

이전에는 레이블 크기를 varint로 인코딩했지만, 이제는 크기가 0~254바이트이면 1바이트를 사용하고, 크기가 255이면 값 255 뒤에 3바이트 리틀엔디언 크기를 붙입니다. 크기가 0~127바이트와 2MB~16MB일 때는 메모리 사용량이 그대로입니다. 128~254바이트와 16384바이트~2MB일 때는 1바이트 줄고, 255~16383바이트일 때는 2바이트 늘어납니다.

근거: “Instead of using varint to encode the size of each label, use a single byte for size 0-254, or a flag value of 255 followed by the size in 3 bytes little-endian.” https://github.com/prometheus/prometheus/pull/16069

> * [PERF] Labels: Simpler/faster stringlabels encoding. #16069

## 중요 수정 (16)

### PromQL 범위 집계의 스칼라 매개변수 변경 지원

- 영향 대상: `quantile`, `topk` 같은 집계에서 상수가 아닌 스칼라 매개변수를 사용하는 PromQL 범위 쿼리

쿼리 범위의 각 평가 시점에서 사용된 매개변수 값이 결과에 반영됩니다.

> * [ENHANCEMENT] PromQL: support non-constant parameter in aggregations like `quantile` and `topk`. #16404

### Prometheus의 `GOGC` 환경 변수 처리 수정

- 영향 대상: `GOGC`가 설정되어 있고 로드된 config에 `runtime.gogc` 필드가 없는 Prometheus 구성 (추정)

이전에는 `GOGC`가 설정되어 있어도 config에 `runtime` 블록이 없으면 Prometheus가 이를 무시하고 기본값 75%를 사용했습니다. 이제 `runtime` 블록의 유무와 관계없이 환경 변수 값을 사용합니다. 단, `runtime.gogc`가 설정되어 있으면 이 값이 우선합니다.

> * [BUGFIX] Config: Respect GOGC environment variable if no "runtime" block exists. #16558

### PromQL `last_over_time` 네이티브 히스토그램 처리 수정

- 영향 대상: `last_over_time`를 사용하는 네이티브 히스토그램 쿼리

float 샘플이 없는 혼합 샘플에서 히스토그램 타임스탬프가 0보다 작으면 기본 float 값인 `T=0, V=0.0`을 잘못 반환했습니다.

> * [BUGFIX] PromQL: Fix native histogram `last_over_time`. #16744

### 충돌하는 입력에서 PromQL 히스토그램 함수가 결과를 반환하지 않음

- 영향 대상: 동일한 시계열의 같은 타임스탬프에 classic 및 native histogram 데이터가 있는 경우 `histogram_fraction` 또는 `histogram_quantile`을 사용하는 설정

이 충돌 상황에서는 이전에 함수가 결과가 없어야 하는데도 값을 반환할 수 있었습니다. 이제 함수는 결과를 반환하지 않고 classic/native histogram 혼합 경고를 내보냅니다.

> * [BUGFIX] PromQL: Don't emit a value from `histogram_fraction` or `histogram_quantile` if classic and native histograms are present at the same timestamp. #16552

### PromQL duration 반올림 오류 수정

- 영향 대상: 오프셋, 범위 셀렉터, 서브쿼리 범위 또는 스텝에 쓰이는 PromQL 숫자 duration

`[1001ms]` 같은 duration이 `[1s]`로 내림 처리되어, 샘플이 촘촘한 데이터에서 셀렉터가 샘플을 놓칠 수 있었습니다. 이제 가장 가까운 나노초 단위로 반올림하므로 `[1001ms]`는 1001밀리초로 표현됩니다.

> * [BUGFIX] PromQL: Incorrect rounding of `[1001ms]` to `[1s]` and similar. #16478

### PromQL 히스토그램 쿼리의 카운터 리셋 감지 수정

- 영향 대상: `histogram_count`, `histogram_sum` 또는 `histogram_avg`와 함께 `rate`, `irate` 또는 `increase`를 사용하는 네이티브 히스토그램 쿼리

범위의 마지막 샘플이 직전 샘플에 비해 카운터 리셋을 일으키면 리셋 감지가 실패할 수 있었습니다. 그 결과 `histogram_count`와 `histogram_sum` 값이 일관되지 않거나 때로는 음수가 될 수 있었습니다.

> * [BUGFIX] PromQL: Fix inconsistent / sometimes negative `histogram_count` and `histogram_sum`. #16682

### PromQL `histogram_quantile` 및 `histogram_fraction`의 NaN 처리 수정

- 영향 대상: NaN 관측값이 포함된 네이티브 히스토그램을 `histogram_quantile` 또는 `histogram_fraction`에 사용하는 경우

NaN 관측값이 포함된 네이티브 히스토그램에서 모든 관측값이 NaN이면 `histogram_quantile`이 0을 반환할 수 있었습니다. 분위수가 정상 관측값을 모두 넘어서는 경우에는 상위 버킷 경계를 반환할 수도 있었고, `histogram_fraction`은 계산에 NaN을 포함했습니다. 이제 분위수가 모든 정상 관측값을 지나 NaN 구간에 들어가면 `histogram_quantile`은 NaN을 반환하고, `histogram_fraction`은 NaN을 제외합니다. NaN이 결과에 영향을 미치는 경우에는 정보 수준 어노테이션으로 이를 알립니다.

> * [BUGFIX] PromQL: Improve handling of NaNs in native histograms. #16724

### duration 표현식에서 PromQL 단항 마이너스 우선순위 수정

- 영향 대상: `promql-duration-expr`를 활성화한 PromQL duration 표현식

단항 마이너스 뒤에 다른 연산자가 오면 `foo offset -1^1` 같은 표현식이 잘못된 우선순위로 파싱될 수 있었습니다. 이제 단항 마이너스가 duration에 먼저 결합하므로 `foo offset -1^1`은 `foo offset (-1^1)`이 아니라 `(foo offset -1) ^ 1`로 파싱됩니다.

> * [BUGFIX] PromQL: Fix unary operator precedence in duration expressions. #16713

### Prometheus 및 OpenMetrics 텍스트 파서의 메모리 손상 수정

- 영향 대상: Prometheus 또는 OpenMetrics 텍스트 형식을 사용하는 스크레이프 (추정)

파서의 레이블 처리 과정에서 파서 버퍼 데이터에 대한 참조가 남을 수 있었습니다. 재현 사례는 스크레이핑과 TSDB 헤드 압축이 겹칠 때 발생하는 데이터 레이스를 다룹니다.

> * [BUGFIX] Scraping: Fix rare memory corruption bug. #16623

### 지수형 히스토그램 뒤 클래식 히스토그램의 NHCB 변환 재개

- 영향 대상: 네이티브 히스토그램과 NHCB 변환 대상 클래식 히스토그램이 포함된 Protobuf 스크레이프 (추정)

이전에는 지수형 네이티브 히스토그램을 만난 뒤에 나오는 변환 대상 클래식 히스토그램이 NHCB로 변환되지 않았습니다. 이제 해당 클래식 히스토그램의 레이블이 지수형 히스토그램과 다르면 변환이 재개되며, 레이블이 같으면 변환이 계속 억제됩니다.

> * [BUGFIX] Scraping: continue handling custom-bucket histograms after an exponential histogram is encountered. #16720

### 서비스 디스커버리 UI의 타깃 수에 서버 측 전체 수 사용

- 영향 대상: `keep_dropped_targets`로 보관할 드롭된 타깃 세부 정보를 제한하는 서비스 디스커버리 UI

UI는 추가 드롭된 타깃 세부 정보가 표시되지 않는 경우를 나타냅니다.

> * [ENHANCEMENT] UI: Better total target count display when using `keep_dropped_targets` option. #16604

### WAL 로딩 전 Prometheus 규칙 파일 검증

- 영향 대상: 규칙 파일 패턴을 사용하는 Prometheus 설정

설정한 패턴이 존재하지 않는 파일로 해석되거나 파일에 유효하지 않은 규칙이 들어 있어도, 이 시작 단계에서는 파싱이 수행되지 않았으며 systemd가 크래시 후 재시작을 반복할 수 있었습니다. 이제 조기 검사에서 이러한 경우 시작 오류를 로그에 남기고 종료 상태 2로 종료합니다.

> * [ENHANCEMENT] Rules: Check that rules parse without error earlier at startup. #16601

### TSDB WAL 초기화 중 Prometheus의 높은 메모리 사용량 수정

- 영향 대상: TSDB WAL을 초기화하고 로드하는 Prometheus 환경 (추정)

초기화 및 WAL 로드 중에는 Prometheus가 설정값이나 기본값인 75%를 적용하기 전에 Go의 기본 `GOGC` 값인 100%가 적용되어 메모리 사용량이 증가했습니다. 업그레이드 후에는 해당 단계에서 설정된 `GOGC` 값이나 기본값인 75%를 사용합니다.

> * [BUGFIX] Top-level: Update GOGC before loading TSDB. #16491

### PromQL 집계 표현식 위치 수정 및 잘못된 표현식의 패닉 수정

- 영향 대상: PromQL 쿼리 파싱

`ParenExpr` 안의 집계 표현식은 이전에 끝 위치가 괄호로 묶인 표현식 전체까지 이어져, 위치 기반 출력에 토큰이 하나 더 포함됐습니다. 또한 `sum(rate(` 같은 잘못된 표현식은 범위를 벗어난 접근으로 패닉을 일으킬 수 있었습니다. 이제 끝 위치는 집계 표현식에서 멈추며, 잘못된 표현식도 패닉 없이 처리됩니다.

> * [BUGFIX] PromQL: Fix reported parser position range in errors for aggregations wrapped in ParenExpr #16041 #16754

### 디스커버리 잠금 순서 역전으로 인한 교착 상태 수정

- 영향 대상: Prometheus 서비스 디스커버리 (추정)

종료 중 `Manager.ApplyConfig()`와 `Manager.cleaner()`가 `Provider.mu`와 `Manager.targetsMtx`를 서로 반대 순서로 획득하면 Prometheus가 멈출 수 있었습니다. 이제 두 루틴은 일관된 순서로 잠금을 획득해 이 교착 상태를 방지합니다.

> * [BUGFIX] Discovery: Avoid deadlocks by taking locks in consistent order. #16587

### `otlp:` 미설정 시 OTLP 리시버 기본값 적용

- 영향 대상: `otlp:` 블록이 없는 OTLP 리시버 구성

이전에는 `otlp:` 블록을 생략하면 OTLP 기본값이 적용되지 않았지만, 이제 리시버가 `DefaultOTLPConfig`를 사용합니다. 여기에는 `TranslationStrategy: UnderscoreEscapingWithSuffixes`가 포함됩니다.

> * [BUGFIX] OTLP: Default config not respected when `otlp:` block is unset. #16693

## 기능·개선 (12)

- PromQL 타입 어노테이션을 위한 타입 및 단위 메타데이터 라벨 (사용 조건: `--enable-feature=type-and-unit-labels`)
- PromQL 샘플 타임스탬프 함수 추가 (사용 조건: `experimental-promql-functions` 기능 플래그를 활성화해야 합니다.)
- 클래식 히스토그램과 네이티브 히스토그램 동시 스크레이프를 위한 전역 제어 (사용 조건: 전역 `always_scrape_classic_histograms` 옵션 활성화)
- OTLP 리소스 어트리뷰트 승격 옵션 추가 (사용 조건: 모든 리소스 어트리뷰트를 승격하려면 `otlp.promote_all_resource_attributes: true`로 설정합니다. `ignore_resource_attributes`는 이 설정과 함께 사용할 때만 허용되며, `promote_resource_attributes`와 함께 사용할 수 없습니다.)
- STACKIT Cloud 서비스 디스커버리
- Hetzner 디스커버리 서버 필터링용 `label_selector` (사용 조건: 필수 역할 `role=hcloud`; 해당 역할에서만 사용 가능한 `label_selector`)
- 상태, 이름, 레이블로 `/rules` 페이지의 규칙 필터링
- 테이블 쿼리 탭의 쿼리 통계 (사용 조건: 테이블 쿼리 요청에 `stats: "true"` 설정)
- `promtool test rules`의 선택적 부동소수점 퍼지 비교 (사용 조건: `--fuzzy-compare` 또는 `fuzzy_compare: true`)
- 실험적 청크 쓰기용 비캐시 I/O (사용 조건: `--enable-feature=use-uncached-io`를 활성화해야 합니다. 실험적 기능이며 Linux에서만 사용할 수 있습니다.)
- 그래프 뷰에서 쿼리 경고와 정보 표시
- Azure AD remote-write의 기본 관리형 ID 지원 (사용 조건: Azure AD remote-write 인증에서 `managed_identity`를 설정하고 `client_id`를 비워 둔 구성)

## 기타 (9)

- 검색 중 스크레이프 풀 선택값 초기화
- `histogramStatsIterator` 재사용으로 PromQL 할당 감소
- PromQL 네이티브 히스토그램의 커스텀 버킷 저장소 재사용
- `/targets` 페이지의 불필요한 리렌더링 감소
- 상태 메뉴를 열 때 발생하던 페이지 전체 재렌더링 수정
- Kubernetes EndpointSlice 디스커버리에서 서비스 `cache.Indexer` 사용
- 요청한 제한에 도달하면 중단하는 TSDB 라벨 값 조회
- 설정 적용 중 스크레이프 풀 동시 리로드
- PromQL 평균에 Kahan 합산과 범위 폴백 적용

---

정리 내용은 AI가 작성하므로 틀릴 수 있으며, 보증 없이 제공합니다.
