prometheus 커맨드라인

prometheus 커맨드라인 (prometheus)

Prometheus 서버 바이너리는 실행할 때 수많은 커맨드라인 플래그를 받아요. 이 문서는 프로메테우스 서버의 모든 플래그를 설명과 기본값과 함께 정리한 참고 페이지예요. 플래그 이름과 기본값은 그대로 두고, 각 플래그가 무엇을 하는지 한국어로 풀어 설명해 드릴게요.

이 표를 모두 외울 필요는 없어요. 다만 웹 노출, 스토리지 보존 기간, 쿼리 제한, 규칙 평가, Alertmanager 통지 등 자주 손대는 플래그의 위치를 알아 두면 운영할 때 큰 도움이 돼요. 실행할 때 --help를 써도 같은 목록을 볼 수 있어요.

출처: 문서

본문

Prometheus 모니터링 서버

플래그 (Flags)

플래그 설명 기본값
-h, --help 상황에 맞는 도움말 표시(--help-long과 --help-man도 시도해 보세요).
--version 애플리케이션 버전 표시.
--config.file Prometheus 구성 파일 경로. prometheus.yml
--config.auto-reload 구성 파일 자동 리로드를 활성화. --config.auto-reload-interval도 참조. false
--config.auto-reload-interval 변경 감지 시 Prometheus 구성 파일을 확인하고 자동으로 리로드하는 간격을 지정. --config.auto-reload가 설정됐을 때만 사용됨. 30s
--web.listen-address ... UI, API, 텔레메트리를 위한 수신 주소. 반복 가능. 0.0.0.0:9090
--auto-gomaxprocs Linux 컨테이너 CPU 쿼터에 맞춰 GOMAXPROCS를 자동 설정. true
--auto-gomemlimit Linux 컨테이너 또는 시스템 메모리 한도에 맞춰 GOMEMLIMIT를 자동 설정. true
--auto-gomemlimit.ratio 예약된 GOMEMLIMIT 메모리의 감지된 최대 컨테이너/시스템 메모리에 대한 비율. 0.9
--web.config.file [EXPERIMENTAL] TLS 또는 인증을 활성화할 수 있는 구성 파일 경로.
--web.read-timeout 요청 읽기 타임아웃과 유휴 연결을 닫기 전 최대 지속시간. 5m
--web.max-connections 모든 리스너에 걸친 최대 동시 연결 수. 512
--web.max-notifications-subscribers 라이브 알림을 동시에 받을 수 있는 최대 구독자 수. 한도에 도달하면 기존 연결이 닫힐 때까지 새 구독 요청이 거부됨. 16
--web.external-url Prometheus가 외부에서 도달할 수 있는 URL(예: 리버스 프록시를 통해 서빙되는 경우). Prometheus 자체로 돌아오는 상대·절대 링크 생성에 사용. URL에 경로 부분이 있으면 Prometheus가 서빙하는 모든 HTTP 엔드포인트에 접두사로 사용됨. 생략하면 관련 URL 구성 요소가 자동으로 파생됨.
--web.route-prefix 웹 엔드포인트의 내부 라우트 접두사. --web.external-url의 경로가 기본값.
--web.user-assets /user에서 제공되는 정적 에셋 디렉터리 경로.
--web.enable-lifecycle HTTP 요청으로 셧다운과 리로드 활성화. false
--web.enable-admin-api 관리 제어 액션용 API 엔드포인트 활성화. false
--web.enable-remote-write-receiver remote write 요청을 받아들이는 API 엔드포인트 활성화. false
--web.remote-write-receiver.accepted-protobuf-messages remote write를 받을 때 수용할 remote write protobuf 메시지 목록. 지원 값: prometheus.WriteRequest, io.prometheus.write.v2.Request prometheus.WriteRequest
--web.enable-otlp-receiver OTLP write 요청을 받아들이는 API 엔드포인트 활성화. false
--web.console.templates /consoles에서 제공되는 콘솔 템플릿 디렉터리 경로. consoles
--web.console.libraries 콘솔 라이브러리 디렉터리 경로. console_libraries
--web.page-title Prometheus 인스턴스의 문서 제목. Prometheus Time Series Collection and Processing Server
--web.cors.origin CORS origin용 정규식. 완전히 고정(anchored)됨. 예: 'https?://(domain1|domain2).com' .*
--storage.tsdb.path 메트릭 저장 기준 경로. 서버 모드에서만 사용. data/
--storage.tsdb.retention.time [DEPRECATED] 저장소에 샘플을 보존할 기간. 이 플래그와 "storage.tsdb.retention.size" 모두 설정하지 않으면 보존 기간은 기본적으로 15d. 지원 단위: y, w, d, h, m, s, ms. 이 플래그는 더 이상 사용되지 않으며, 대신 구성 파일의 storage.tsdb.retention.time 필드를 사용하세요. 서버 모드에서만 사용.
--storage.tsdb.retention.size [DEPRECATED] 블록에 저장할 수 있는 최대 바이트 수. 단위 필수, 지원 단위: B, KB, MB, GB, TB, PB, EB. 예: "512MB". 2의 거듭제곱 기반이라 1KB는 1024B. 이 플래그는 더 이상 사용되지 않으며, 대신 구성 파일의 storage.tsdb.retention.size 필드를 사용하세요. 서버 모드에서만 사용.
--storage.tsdb.no-lockfile 데이터 디렉터리에 lockfile을 만들지 않음. 서버 모드에서만 사용. false
--storage.tsdb.head-chunks-write-queue-size head 청크가 디스크에 m-map되기 위해 쓰이는 큐의 크기. 0은 큐를 완전히 비활성화. 실험적. 서버 모드에서만 사용. 0
--storage.tsdb.delay-compact-file.path 업로드된 TSDB 블록(예: Thanos shipper meta 파일)이 있는 JSON 파일 경로. 설정하면 TSDB는 그 파일에서 업로드된 것으로 표시된 1레벨 블록만 컴팩트하여 Thanos sidecar 같은 외부 저장소 통합을 개선. 1+ 레벨 컴팩션은 지연되지 않음. 서버 모드에서만 사용.
--storage.agent.path 메트릭 저장 기준 경로. 에이전트 모드에서만 사용. data-agent/
--storage.agent.wal-compression 에이전트 WAL 압축. false면 --storage.agent.wal-compression-type 플래그는 무시됨. 에이전트 모드에서만 사용. true
--storage.agent.retention.min-time WAL이 잘릴 때 삭제로 간주되기 전 샘플이 가질 수 있는 최소 나이. 에이전트 모드에서만 사용. 5m
--storage.agent.retention.max-time WAL이 잘릴 때 강제 삭제되기 전 샘플이 가질 수 있는 최대 나이. 에이전트 모드에서만 사용. 4h
--storage.agent.checkpoint-from-in-memory-series 체크포인트를 만들 때 인메모리 시리즈 데이터만 사용. 에이전트 모드에서만 사용. false
--storage.agent.checkpoint-batch-size 플러시할 단일 WAL 로그 항목 청크의 크기. --storage.agent.checkpoint-from-in-memory-series 플래그 없이는 효과 없음. 에이전트 모드에서만 사용. 1000
--storage.agent.no-lockfile 데이터 디렉터리에 lockfile을 만들지 않음. 에이전트 모드에서만 사용. false
--storage.remote.flush-deadline 셧다운 또는 구성 리로드 시 샘플 플러시를 기다릴 시간. 1m
--storage.remote.read-sample-limit remote read 인터페이스를 통해 단일 쿼리에서 반환할 최대 전체 샘플 수. 0은 무제한. 스트리밍 응답 타입에는 적용되지 않음. 서버 모드에서만 사용. 5e7
--storage.remote.read-concurrent-limit 최대 동시 remote read 호출 수. 0은 무제한. 서버 모드에서만 사용. 10
--storage.remote.read-max-bytes-in-frame 마샬링 전 스트리밍 remote read 응답 타입의 단일 프레임 최대 바이트 수. 클라이언트도 프레임 크기 제한이 있을 수 있음. protobuf가 기본적으로 권장하는 1MB. 서버 모드에서만 사용. 1048576
--web.search.max-limit 실험적 검색 API(--enable-feature=search-api)가 받아들이는 "limit" 쿼리 파라미터의 상한. 더 높은 limit의 요청은 HTTP 400으로 거부됨. 0은 상한 비활성화. 서버 모드에서만 사용. 10000
--rules.alert.for-outage-tolerance 알림의 "for" 상태를 복원하기 위해 허용하는 Prometheus 중단 최대 시간. 서버 모드에서만 사용. 1h
--rules.alert.for-grace-period 알림과 복원된 "for" 상태 사이의 최소 지속시간. "for" 시간이 grace period보다 길게 구성된 알림에만 유지됨. 서버 모드에서만 사용. 10m
--rules.alert.resend-delay 알림을 Alertmanager로 재전송하기 전 대기하는 최소 시간. 서버 모드에서만 사용. 1m
--rules.max-concurrent-evals 동시에 실행될 수 있는 독립 규칙의 전역 동시성 제한. 설정 시 "query.max-concurrency"를 그에 맞게 조정해야 할 수 있음. 서버 모드에서만 사용. 4
--alertmanager.notification-queue-capacity 대기 중인 Alertmanager 알림 대기열의 용량. 서버 모드에서만 사용. 10000
--alertmanager.notification-batch-size Alertmanager로 보낼 배치당 최대 알림 수. 서버 모드에서만 사용. 256
--alertmanager.drain-notification-queue-on-shutdown 셧다운 시 미전송 Alertmanager 알림을 전송. false면 셧다운 시 미전송 Alertmanager 알림이 버려짐. 서버 모드에서만 사용. true
--query.lookback-delta 표현식 평가와 페더레이션 중 메트릭 검색의 최대 lookback 지속시간. 서버 모드에서만 사용. 5m
--query.timeout 쿼리가 중단되기 전 걸릴 수 있는 최대 시간. 서버 모드에서만 사용. 2m
--query.max-concurrency 동시에 실행되는 최대 쿼리 수. 서버 모드에서만 사용. 20
--query.max-samples 단일 쿼리가 메모리로 로드할 수 있는 최대 샘플 수. 쿼리가 이보다 더 많은 샘플을 메모리로 로드하려 하면 실패하므로, 이는 쿼리가 반환할 수 있는 샘플 수도 제한함. 서버 모드에서만 사용. 50000000
--enable-feature ... 활성화할 쉼표로 구분된 기능 이름. 유효 옵션: concurrent-rule-eval, created-timestamp-zero-ingestion, delayed-compaction, exemplar-storage, extra-scrape-metrics, histograms-st-encoding, memory-snapshot-on-shutdown, metadata-wal-records, old-ui, otlp-deltatocumulative, otlp-native-delta-ingestion, promql-binop-fill-modifiers, promql-delayed-name-removal, promql-experimental-functions, promql-extended-range-selectors, promql-per-step-stats, search-api, st-storage, st-synthesis, type-and-unit-labels, use-start-timestamps, use-uncached-io, xor2-encoding. 자세한 내용은 https://prometheus.io/docs/prometheus/latest/feature_flags/를 참조.
--agent 'Agent mode'로 Prometheus 실행.
--log.level 주어진 심각도 이상의 메시지만 로그. 다음 중 하나: [debug, info, warn, error] info
--log.format 로그 메시지의 출력 형식. 다음 중 하나: [logfmt, json] logfmt

더 알아보기 (Learn more)