Prometheus 설정은 성격이 다른 두 곳에 나뉘어 있다. 무엇을 수집할지는 prometheus.yml 에 적고, 데이터를 어떻게 저장할지는 실행 플래그로 준다. 이 경계를 모르면 저장 옵션을 prometheus.yml 에 적어 두고 왜 안 먹는지 헤매게 된다. 여기에 더해 타깃을 설정 파일에 직접 나열하지 않고 별도 파일로 빼는 file_sd 방식을 정리한다.
| 대상 | 위치 | 예 |
|---|---|---|
| 수집 대상 · 주기 · 재라벨링 · 알림 규칙 | prometheus.yml |
scrape_configs, global, rule_files |
| 저장 경로 · 보존 기간 · 블록 · WAL | 실행 플래그 | --storage.tsdb.* |
| 웹 UI · 수명주기 API | 실행 플래그 | --web.* |
storage.tsdb 를 YAML 키처럼 적으면 Prometheus 가 알 수 없는 필드라며 기동에 실패하거나, 무시하고 기본값으로 돈다.
수집 대상이 자주 바뀌면 prometheus.yml 을 고치고 재적재하는 대신, 타깃 목록만 별도 파일로 둔다. Prometheus 가 파일 변경을 감지해 반영하므로 재적재가 필요 없다.
scrape_configs:
- job_name: 'node'
file_sd_configs:
- files:
- /etc/prometheus/targets/*.json
- /etc/prometheus/targets/*.yml
refresh_interval: 30s
타깃 파일은 JSON 과 YAML 둘 다 된다. 확장자로 형식을 판단하므로 .json · .yml · .yaml 을 정확히 붙인다.
[
{
"targets": ["192.168.0.10:9100", "192.168.0.11:9100"],
"labels": {
"env": "prod",
"role": "worker"
}
},
{
"targets": ["192.168.0.20:8080"],
"labels": {
"env": "prod",
"role": "app"
}
}
]
같은 내용을 YAML 로 적으면 다음과 같다.
- targets:
- "192.168.0.10:9100"
- "192.168.0.11:9100"
labels:
env: "prod"
role: "worker"
labels 에 job 을 넣어 덮어쓸 수도 있지만, 되도록 job_name 을 파일별로 나누는 편이 관리하기 쉽다. 파일에 문법 오류가 있으면 그 파일의 타깃만 빠지고 Prometheus 는 계속 돈다. 조용히 사라지므로 반영 여부를 UI 의 Targets 화면에서 확인한다.
prometheus \
--config.file=/etc/prometheus/prometheus.yml \
--storage.tsdb.path=/prometheus/data \
--storage.tsdb.retention.time=15d \
--storage.tsdb.retention.size=200GB \
--web.enable-lifecycle
| 플래그 | 뜻 |
|---|---|
--storage.tsdb.path |
데이터 디렉터리. 기본은 data/ |
--storage.tsdb.retention.time |
보존 기간. 기본 15일 |
--storage.tsdb.retention.size |
보존 용량 상한. 시간과 함께 주면 먼저 걸리는 쪽이 적용된다 |
--storage.tsdb.wal-compression |
WAL 압축. 최근 버전은 기본으로 켜져 있다 |
WAL 압축은 디스크 쓰기량을 줄이는 대신 CPU 를 조금 더 쓴다. 현대 CPU 에서는 체감이 거의 없어 기본값을 그대로 두면 된다. 예전 문서에서 이 플래그를 명시적으로 켜라고 하는 것은 기본값이 꺼져 있던 시절의 이야기다.
--storage.tsdb.min-block-duration=2h \
--storage.tsdb.max-block-duration=2h \
두 값을 같게 주면 Prometheus 가 블록을 합치는 압축(compaction) 을 하지 않는다. 이것은 성능 튜닝이 아니라 Thanos 사이드카처럼 외부 시스템이 2시간 블록을 그대로 가져가 원격에서 압축하는 구성을 위한 설정이다.
압축을 끄면 블록 수가 계속 늘어 로컬 조회가 느려지고 디스크를 더 쓴다. 외부 압축 주체가 없다면 두 값을 건드리지 않는다. 두 플래그는 실험적 취급이라 버전에 따라 이름이나 동작이 달라질 수 있다.
--web.console.templates=/etc/prometheus/consoles \
--web.console.libraries=/etc/prometheus/console_libraries
Prometheus 에 내장된 옛 콘솔 템플릿의 경로를 지정한다. HTML 템플릿과 그 템플릿이 쓰는 JS · CSS 위치다. 요즘은 대시보드를 Grafana 로 만들기 때문에 실제로 쓰는 곳은 드물다. 패키지 기본 서비스 파일에 들어 있어 무엇인지 궁금해질 뿐, 없어도 수집과 조회에는 영향이 없다.
promtool check config /etc/prometheus/prometheus.yml
curl -X POST http://localhost:9090/-/reload
--web.enable-lifecycle 없이 시작했다면 /-/reload 가 405 를 돌려준다. 이때는 프로세스에 SIGHUP 을 보낸다.
open /prometheus/queries.active: permission denied 로 기동에 실패한다.