promtool 커맨드라인

promtool 커맨드라인 (promtool)

promtool은 프로메테우스 모니터링 시스템을 위한 유틸리티 도구예요. 규칙 파일 검증, 서버 쿼리 실행, 디버그 정보 수집, 유닛 테스트, TSDB 분석 등 다양한 작업을 커맨드라인에서 할 수 있게 해 줘요. 이 문서는 promtool의 모든 플래그와 명령을 정리한 참고 페이지예요.

특히 promtool check는 규칙 파일을 프로메테우스에 로드하기 전에 유효성을 검사할 수 있어서 운영 전 단계에서 아주 유용해요. 명령 이름과 플래그는 그대로 두고, 각각이 무엇을 하는지 한국어로 풀어 설명해 드릴게요.

출처: 문서

본문

Prometheus 모니터링 시스템용 도구.

플래그 (Flags)

플래그 설명
-h, --help 상황에 맞는 도움말 표시(--help-long과 --help-man도 시도해 보세요).
--version 애플리케이션 버전 표시.
--experimental 실험적 명령 활성화.
--enable-feature ... 활성화할 쉼표로 구분된 기능 이름. 유효 옵션: promql-experimental-functions, promql-delayed-name-removal, promql-extended-range-selectors. 자세한 내용은 https://prometheus.io/docs/prometheus/latest/feature_flags/를 참조.

명령 (Commands)

명령 설명
help 도움말 표시.
check 리소스의 유효성 검사.
query Prometheus 서버에 대해 쿼리 실행.
debug 디버그 정보 가져오기.
push Prometheus 서버로 푸시.
test 유닛 테스트.
tsdb tsdb 명령 실행.
promql PromQL 포맷팅과 편집. --experimental 플래그 필요.

promtool help

도움말 표시.

인자 (Arguments)

인자 설명
command 명령에 대한 도움말 표시.

promtool check

리소스의 유효성 검사.

플래그

플래그 설명 기본값
--query.lookback-delta 서버의 최대 쿼리 lookback 지속시간. 5m
promtool check service-discovery

주어진 잡 이름에 대한 서비스 디스커버리를 수행하고 relabeling을 포함한 결과를 보고.

플래그
플래그 설명 기본값
--timeout 디스커버리 결과를 기다릴 시간. 30s
인자
인자 설명 필수
config-file prometheus 구성 파일. 예
job 서비스 디스커버리를 실행할 잡. 예
promtool check config

구성 파일이 유효한지 아닌지 검사.

플래그
플래그 설명 기본값
--syntax-only 구성에서 참조되는 파일과 콘텐츠 검증을 무시하고 구성 파일 문법만 검사.
--lint 구성에 지정된 규칙/스크랩 구성에 적용할 린팅 검사. 사용 가능 옵션: all, duplicate-rules, none, too-long-scrape-interval. 린팅 비활성화는 --lint=none 사용. duplicate-rules
--lint-fatal 린트 오류가 종료 코드 3으로 나가게 함. false
--ignore-unknown-fields 구성 파일이 읽는 규칙 그룹의 알 수 없는 필드 무시. 커스텀 메타데이터로 규칙 파일을 확장하고 싶을 때 유용. 기본적으로 엄격한 검사를 수행하므로 Prometheus 서버에 로드하기 전에 그 필드를 제거해야 함. false
--agent Agent mode의 Prometheus에 대한 구성 파일 검사.
인자
인자 설명 필수
config-files 검사할 구성 파일. 예
promtool check web-config

웹 구성 파일이 유효한지 아닌지 검사.

인자
인자 설명 필수
web-config-files 검사할 구성 파일. 예
promtool check healthy

Prometheus 서버가 건강한지 검사.

플래그
플래그 설명 기본값
--http.config.file HTTP 클라이언트 구성 파일. 자세한 내용은 https://prometheus.io/docs/prometheus/latest/configuration/promtool 참조.
--url Prometheus 서버의 URL. http://localhost:9090
promtool check ready

Prometheus 서버가 준비됐는지 검사.

플래그
플래그 설명 기본값
--http.config.file HTTP 클라이언트 구성 파일. 자세한 내용은 https://prometheus.io/docs/prometheus/latest/configuration/promtool 참조.
--url Prometheus 서버의 URL. http://localhost:9090
promtool check rules

규칙 파일이 유효한지 아닌지 검사.

플래그
플래그 설명 기본값
--lint 적용할 린팅 검사. 사용 가능 옵션: all, duplicate-rules, none. 린팅 비활성화는 --lint=none 사용. duplicate-rules
--lint-fatal 린트 오류가 종료 코드 3으로 나가게 함. false
--ignore-unknown-fields 규칙 파일의 알 수 없는 필드 무시. 커스텀 메타데이터로 규칙 파일을 확장하고 싶을 때 유용. 기본적으로 엄격한 검사를 수행하므로 Prometheus 서버에 로드하기 전에 그 필드를 제거해야 함. false
인자
인자 설명
rule-files 검사할 규칙 파일. 기본값은 표준 입력에서 읽음.
promtool check metrics

Prometheus 메트릭을 stdin으로 넘겨 일관성과 정확성을 린트하고, 선택적으로 카디널리티 분석을 수행.

예:

$ cat metrics.prom | promtool check metrics

$ curl -s [http://localhost:9090/metrics](http://localhost:9090/metrics) | promtool check metrics `--extended`

$ curl -s [http://localhost:9100/metrics](http://localhost:9100/metrics) | promtool check metrics `--extended` `--lint`=none
플래그
플래그 설명 기본값
--extended 메트릭 카디널리티와 관련된 확장 정보 출력.
--lint 메트릭에 적용할 린팅 검사. 사용 가능 옵션: all, none. 메트릭 린팅 비활성화는 --lint=none 사용. all

promtool query

Prometheus 서버에 대해 쿼리 실행.

플래그

플래그 설명 기본값
-o, --format 쿼리의 출력 형식. promql
--http.config.file HTTP 클라이언트 구성 파일. 자세한 내용은 https://prometheus.io/docs/prometheus/latest/configuration/promtool 참조.
promtool query instant

인스턴트 쿼리 실행.

플래그
플래그 설명
--time 쿼리 평가 시간(RFC3339 또는 Unix 타임스탬프).
--header 서버로 보낼 추가 헤더.
인자
인자 설명 필수
server 쿼리할 Prometheus 서버. 예
expr PromQL 쿼리 표현식. 예
promtool query range

범위 쿼리 실행.

플래그
플래그 설명
--header 서버로 보낼 추가 헤더.
--start 쿼리 범위 시작 시간(RFC3339 또는 Unix 타임스탬프).
--end 쿼리 범위 종료 시간(RFC3339 또는 Unix 타임스탬프).
--step 쿼리 스텝 크기(지속시간).
인자
인자 설명 필수
server 쿼리할 Prometheus 서버. 예
expr PromQL 쿼리 표현식. 예
promtool query series

시리즈 쿼리 실행.

플래그
플래그 설명
--match ... 시리즈 셀렉터. 여러 번 지정 가능.
--start 시작 시간(RFC3339 또는 Unix 타임스탬프).
--end 종료 시간(RFC3339 또는 Unix 타임스탬프).
인자
인자 설명 필수
server 쿼리할 Prometheus 서버. 예
promtool query labels

라벨 쿼리 실행.

플래그
플래그 설명
--start 시작 시간(RFC3339 또는 Unix 타임스탬프).
--end 종료 시간(RFC3339 또는 Unix 타임스탬프).
--match ... 시리즈 셀렉터. 여러 번 지정 가능.
인자
인자 설명 필수
server 쿼리할 Prometheus 서버. 예
name 라벨 값을 제공할 라벨 이름. 예
promtool query analyze

Prometheus에 대해 쿼리를 실행해 특정 메트릭의 사용 패턴을 분석.

플래그
플래그 설명 기본값
--server 쿼리할 Prometheus 서버.
--type 메트릭 유형: histogram.
--duration 분석할 시간 프레임. 1h
--time 쿼리 시간(RFC3339 또는 Unix 타임스탬프). 기본값은 현재.
--match ... 시리즈 셀렉터. 여러 번 지정 가능.

promtool debug

디버그 정보 가져오기.

promtool debug pprof

프로파일링 디버그 정보 가져오기.

인자
인자 설명 필수
server pprof 파일을 가져올 Prometheus 서버. 예
promtool debug metrics

메트릭 디버그 정보 가져오기.

인자
인자 설명 필수
server 메트릭을 가져올 Prometheus 서버. 예
promtool debug all

모든 디버그 정보 가져오기.

인자
인자 설명 필수
server 모든 디버그 정보를 가져올 Prometheus 서버. 예

promtool push

Prometheus 서버로 푸시.

플래그

플래그 설명
--http.config.file HTTP 클라이언트 구성 파일. 자세한 내용은 https://prometheus.io/docs/prometheus/latest/configuration/promtool 참조.
promtool push metrics

prometheus remote write로 메트릭 푸시(테스트 목적 전용).

플래그
플래그 설명 기본값
--label 메트릭에 첨부할 라벨. 여러 번 지정 가능. job=promtool
--timeout 메트릭 푸시를 기다릴 시간. 30s
--header Prometheus remote write 헤더.
--protobuf_message 쓸 때 사용할 Protobuf 메시지(prometheus.WriteRequest 또는 io.prometheus.write.v2.Request). prometheus.WriteRequest
--remote-write.path 기본 remote write API 경로를 재정의. /api/v1/write
인자
인자 설명 필수
remote-write-url 메트릭을 푸시할 Prometheus remote write url. 예
metric-files 푸시할 메트릭 파일. 기본값은 표준 입력에서 읽음.

promtool test

유닛 테스트.

플래그

플래그 설명
--junit JUnit XML 테스트 결과를 저장할 파일 경로.
promtool test rules

규칙에 대한 유닛 테스트.

플래그
플래그 설명 기본값
--run ... 설정하면 이름이 정규식과 일치하는 테스트 그룹만 실행. 여러 번 지정 가능.
--debug 유닛 테스트 디버깅 활성화. false
--diff [실험적] 기대 출력과 받은 출력 사이의 컬러 차이 출력. false
--ignore-unknown-fields 테스트 파일의 알 수 없는 필드 무시. 커스텀 메타데이터로 규칙 파일을 확장하고 싶을 때 유용. 기본적으로 엄격한 검사를 수행하므로 Prometheus 서버에 로드하기 전에 그 필드를 제거해야 함. false
인자
인자 설명 필수
test-rule-file 유닛 테스트 파일. 예

promtool tsdb

tsdb 명령 실행.

promtool tsdb bench

벤치마크 실행.

promtool tsdb bench write

쓰기 성능 벤치마크 실행.

플래그
플래그 설명 기본값
--out 출력 경로 설정. benchout
--metrics 읽을 메트릭 수. 10000
--scrapes 시뮬레이션할 스크랩 수. 3000
인자
인자 설명 기본값
file 샘플 데이터가 있는 입력 파일. 기본값은 (../../tsdb/testdata/20kseries.json). ../../tsdb/testdata/20kseries.json
promtool tsdb analyze

churn, 라벨 쌍 카디널리티, 컴팩션 효율성 분석.

플래그
플래그 설명 기본값
--limit 각 목록에 표시할 항목 수. 20
--extended 확장 분석 실행.
--match 분석할 시리즈 셀렉터. 현재 1세트의 매처만 지원됨.
인자
인자 설명 기본값
db path 데이터베이스 경로(기본값은 data/). data/
block id 분석할 블록(기본값은 마지막 블록).
promtool tsdb list

tsdb 블록 나열.

플래그
플래그 설명
-r, --human-readable 사람이 읽을 수 있는 값 출력.
인자
인자 설명 기본값
db path 데이터베이스 경로(기본값은 data/). data/
promtool tsdb dump

TSDB에서 데이터(시리즈+샘플, 또는 선택적으로 시리즈만) 덤프.

플래그
플래그 설명 기본값
--sandbox-dir-root 샌드박스 디렉터리가 생성될 루트 디렉터리. 이 샌드박스는 WAL 재생이 청크를 생성하는 경우에 사용됨(기본값은 데이터베이스 경로). 샌드박스는 마지막에 정리됨.
--min-time 덤프할 최소 타임스탬프(Unix epoch 이후 밀리초). -9223372036854775808
--max-time 덤프할 최대 타임스탬프(Unix epoch 이후 밀리초). 9223372036854775807
--match ... 시리즈 셀렉터. 여러 번 지정 가능. {__name__=~'(?s:.*)'}
--format 덤프의 출력 형식(prom(기본) 또는 seriesjson). prom
인자
인자 설명 기본값
db path 데이터베이스 경로(기본값은 data/). data/
promtool tsdb dump-openmetrics

[실험적] TSDB에서 샘플을 OpenMetrics 텍스트 형식으로 덤프. OpenMetrics에서 표현할 수 없는 네이티브 히스토그램과 staleness 마커는 제외.

플래그
플래그 설명 기본값
--sandbox-dir-root 샌드박스 디렉터리가 생성될 루트 디렉터리. 이 샌드박스는 WAL 재생이 청크를 생성하는 경우에 사용됨(기본값은 데이터베이스 경로). 샌드박스는 마지막에 정리됨.
--min-time 덤프할 최소 타임스탬프(Unix epoch 이후 밀리초). -9223372036854775808
--max-time 덤프할 최대 타임스탬프(Unix epoch 이후 밀리초). 9223372036854775807
--match ... 시리즈 셀렉터. 여러 번 지정 가능. {__name__=~'(?s:.*)'}
인자
인자 설명 기본값
db path 데이터베이스 경로(기본값은 data/). data/
promtool tsdb create-blocks-from

[실험적] 입력에서 샘플을 가져와 TSDB 블록 생성. 자세한 내용은 storage 문서 참조.

플래그
플래그 설명
-r, --human-readable 사람이 읽을 수 있는 값 출력.
-q, --quiet 생성된 블록을 출력하지 않음.
promtool tsdb create-blocks-from openmetrics

OpenMetrics 입력에서 샘플을 가져와 TSDB 블록 생성. 자세한 내용은 storage 문서 참조.

플래그
플래그 설명
--label 메트릭에 첨부할 라벨. 여러 번 지정 가능. 예: --label=label_name=label_value
인자
인자 설명 기본값 필수
input file 샘플을 읽을 OpenMetrics 파일. 예
output directory 생성된 블록의 출력 디렉터리. data/
promtool tsdb create-blocks-from rules

새 기록 규칙을 위한 데이터 블록 생성.

플래그
플래그 설명 기본값
--http.config.file HTTP 클라이언트 구성 파일. 자세한 내용은 https://prometheus.io/docs/prometheus/latest/configuration/promtool 참조.
--url 규칙을 백필할 데이터가 있는 Prometheus API의 URL. http://localhost:9090
--start 새 규칙을 백필하기 시작할 시간. RFC3339 형식 날짜 또는 Unix 타임스탬프여야 함. 필수.
--end 종료 시간이 제공되면 제공된 규칙 파일의 모든 기록 규칙이 종료 시간까지 백필됨. 기본값은 3시간 전까지 백필. RFC3339 형식 날짜 또는 Unix 타임스탬프여야 함.
--output-dir 생성된 블록의 출력 디렉터리. data/
--eval-interval 기록 규칙 파일에 값이 설정되지 않았을 때 백필 중 규칙을 평가할 빈도. 60s
인자
인자 설명 필수
rule-files 백필할 기록 규칙을 포함하는 파일 하나 이상의 목록. 파일의 모든 기록 규칙이 백필됨. 알림 규칙은 평가되지 않음. 예

promtool promql

PromQL 포맷팅과 편집. --experimental 플래그 필요.

promtool promql format

PromQL 쿼리를 pretty-printed 형태로 포맷.

인자
인자 설명 필수
query PromQL 쿼리. 예
promtool promql label-matchers

기존 PromQL 쿼리에 포함된 라벨 매처 편집.

promtool promql label-matchers set

쿼리에 라벨 매처 설정.

플래그
플래그 설명 기본값
-t, --type 설정할 라벨 매처의 유형. =
인자
인자 설명 필수
query PromQL 쿼리. 예
name 설정할 라벨 매처의 이름. 예
value 설정할 라벨 매처의 값. 예
promtool promql label-matchers delete

쿼리에서 라벨 삭제.

인자
인자 설명 필수
query PromQL 쿼리. 예
name 삭제할 라벨의 이름. 예

더 알아보기 (Learn more)