구성

구성 (Configuration)

프로메테우스는 커맨드라인 플래그와 구성 파일로 구성돼요. 커맨드라인 플래그는 저장 위치, 디스크와 메모리에 보관할 데이터 양 같은 불변의 시스템 파라미터를 구성하고, 구성 파일은 잡과 인스턴스 스크래핑과 관련된 모든 것, 그리고 어떤 규칙 파일을 로드할지를 정의해요. 이 문서는 prometheus.yml 구성 파일의 모든 옵션을 담은 거대한 참고 페이지예요.

이 페이지는 공식 문서 중에서도 가장 방대한 참고 문서 중 하나예요. 원문은 200KB가 넘는 YAML 옵션 사양이므로, 여기서는 구성의 전체 구조와 각 핵심 옵션을 충실하게 정리해 드릴게요. 구체적인 개별 옵션 하나하나가 필요하면 원문 페이지를 함께 보세요.

출처: 문서

본문

Prometheus는 커맨드라인 플래그와 구성 파일로 구성돼요. 커맨드라인 플래그는 불변의 시스템 파라미터(저장 위치, 디스크와 메모리에 보관할 데이터 양 등)를 구성하는 반면, 구성 파일은 잡과 그들의 인스턴스 스크래핑과 관련된 모든 것, 그리고 어떤 규칙 파일을 로드할지를 정의해요.

사용 가능한 모든 커맨드라인 플래그를 보려면 ./prometheus -h를 실행하세요.

Prometheus는 런타임에 구성을 리로드할 수 있어요. 새 구성이 잘 구성되지 않았으면 변경이 적용되지 않아요. 구성 리로드는 Prometheus 프로세스에 SIGHUP을 보내거나 /-/reload 엔드포인트에 HTTP POST 요청을 보내서(--web.enable-lifecycle 플래그가 활성화된 경우) 트리거돼요. 이렇게 하면 구성된 규칙 파일도 함께 리로드돼요.

구성 파일 (Configuration file)

로드할 구성 파일을 지정하려면 --config.file 플래그를 사용하세요.

파일은 아래 설명된 스키마로 정의된 YAML 형식으로 작성돼요. 대괄호는 파라미터가 선택 사항임을 나타내요. 리스트가 아닌 파라미터의 값은 지정된 기본값으로 설정돼요.

일반 자리표시자(placeholder)는 다음과 같이 정의돼요.

  • <boolean>: true 또는 false 값을 가질 수 있는 불리언
  • <duration>: 정규식 ((([0-9]+)y)?(([0-9]+)w)?(([0-9]+)d)?(([0-9]+)h)?(([0-9]+)m)?(([0-9]+)s)?(([0-9]+)ms)?|0)와 일치하는 지속시간. 예: 1d, 1h30m, 5m, 10s
  • <path>: 현재 작업 디렉터리의 유효한 경로
  • <float>: 부동소수점 숫자
  • <host>: 호스트네임 또는 IP 뒤에 선택적 포트 번호로 구성된 유효한 문자열
  • <int>: 정수 값
  • <labelname>: 정규식 [a-zA-Z_][a-zA-Z0-9_]*와 일치하는 문자열. 소스 라벨의 다른 지원되지 않는 문자는 밑줄로 변환해야 해요. 예를 들어 app.kubernetes.io/name 라벨은 app_kubernetes_io_name으로 써야 해요.
  • <labelvalue>: 유니코드 문자 문자열
  • <filename>: 유효한 URL 경로
  • <scheme>: http 또는 https 값을 가질 수 있는 문자열
  • <secret>: 비밀번호 같은 시크릿인 일반 문자열
  • <string>: 일반 문자열
  • <size>: 바이트 단위 크기. 예: 512MB. 단위 필수. 지원 단위: B, KB, MB, GB, TB, PB, EB.
  • <tmpl_string>: 사용 전에 템플릿 확장되는 문자열

다른 자리표시자는 별도로 지정돼요.

유효한 예제 파일은 여기에서 찾을 수 있어요.

전역 구성은 다른 모든 구성 컨텍스트에서 유효한 파라미터를 지정해요. 이것들은 또한 다른 구성 섹션의 기본값 역할을 해요.

global:
  # 기본적으로 타깃을 스크랩하는 빈도.
  [ scrape_interval: <duration> | default = 1m ]

  # 스크랩 요청이 타임아웃되기까지의 시간.
  # 스크랩 간격보다 클 수 없음.
  [ scrape_timeout: <duration> | default = 10s ]

  # 스크랩 중 클라이언트와 협상할 프로토콜.
  # 지원 값(대소문자 구분): PrometheusProto, OpenMetricsText0.0.1,
  # OpenMetricsText1.0.0, PrometheusText0.0.4, PrometheusText1.0.0.
  # 여기와 개별 스크랩 구성 둘 다에서 설정하지 않으면, 그 스크랩 구성에서
  # 사용되는 협상 순서는 그 스크랩 구성의 scrape_native_histograms의
  # 유효값에 따라 달라짐.
  # scrape_native_histograms가 false면 순서는
  # [ OpenMetricsText1.0.0, OpenMetricsText0.0.1, PrometheusText1.0.0, PrometheusText0.0.4 ].
  # true면 순서는
  # [ PrometheusProto, OpenMetricsText1.0.0, OpenMetricsText0.0.1, PrometheusText1.0.0, PrometheusText0.0.4 ].
  [ scrape_protocols: [ <string>, ... ] ]

  # 규칙을 평가하는 빈도.
  [ evaluation_interval: <duration> | default = 1m ]

  # 이 특정 그룹의 규칙 평가 타임스탬프를 지정된 기간만큼 과거로 오프셋해
  # 기본 메트릭이 수신됐는지 보장.
  # 메트릭 가용성 지연은 Prometheus가 remote write 타깃으로 실행될 때 더 발생할
  # 가능성이 높지만, 스크래핑에 이상이 있을 때도 발생할 수 있음.
  [ rule_query_offset: <duration> | default = 0s ]

  # 외부 시스템(페더레이션, 원격 저장소, Alertmanager)과 통신할 때
  # 어떤 타임시리즈나 알림에 추가할 라벨.
  # 환경 변수 참조 `${var}` 또는 `$var`는 현재 환경 변수의 값에 따라 치환됨.
  # 정의되지 않은 변수에 대한 참조는 빈 문자열로 치환됨.
  # `$` 문자는 `$$`로 이스케이프할 수 있음.
  external_labels:
    [ <labelname>: <labelvalue> ... ]

  # PromQL 쿼리가 기록되는 파일.
  # 구성 리로드 시 파일이 다시 열림.
  [ query_log_file: <string> ]

  # 스크랩 실패가 기록되는 파일.
  # 구성 리로드 시 파일이 다시 열림.
  [ scrape_failure_log_file: <string> ]

  # 이 바이트 수보다 큰 압축되지 않은 응답 본문은 스크랩을 실패시킴.
  # 0은 무제한. 예: 100MB.
  # 이것은 실험적 기능이며, 동작이 미래에 바뀌거나 제거될 수 있음.
  [ body_size_limit: <size> | default = 0 ]

  # 수락될 스크랩 샘플 수에 대한 스크랩별 제한.
  # 메트릭 relabeling 후 이 숫자보다 많은 샘플이 있으면 전체 스크랩이
  # 실패로 처리됨. 0은 무제한.
  [ sample_limit: <int> | default = 0 ]

  # 샘플당 수락될 라벨 수 제한. 메트릭 relabeling 후 어떤 샘플에도
  # 이 숫자보다 많은 라벨이 있으면 전체 스크랩이 실패로 처리됨. 0은 무제한.
  [ label_limit: <int> | default = 0 ]

  # 각 개별 라벨 이름의 길이(바이트) 제한. 스크랩에서 어떤 라벨 이름이
  # 메트릭 relabeling 후 이 숫자보다 길면 전체 스크랩이 실패로 처리됨.
  # 라벨 이름은 UTF-8로 인코딩되며 문자는 최대 4바이트를 차지할 수 있음. 0은 무제한.
  [ label_name_length_limit: <int> | default = 0 ]

  # 각 개별 라벨 값의 길이(바이트) 제한. 스크랩에서 어떤 라벨 값이
  # 메트릭 relabeling 후 이 숫자보다 길면 전체 스크랩이 실패로 처리됨.
  # 라벨 값은 UTF-8로 인코딩되며 0은 무제한.
  [ label_value_length_limit: <int> | default = 0 ]

  # 스크랩 구성당 수락될 고유 타깃 수 제한. 타깃 relabeling 후
  # 이 숫자보다 많은 타깃이 있으면 Prometheus는 스크랩하지 않고 타깃을
  # 실패로 표시함. 0은 무제한. 실험적 기능.
  [ target_limit: <int> | default = 0 ]

  # relabeling으로 버려진 타깃 중 메모리에 유지될 수의 스크랩 구성당 제한.
  # 0은 무제한.
  [ keep_dropped_targets: <int> | default = 0 ]

  # 메트릭과 라벨 이름의 검증 스킴 지정. 전체 UTF-8 지원을 위해 비어 있거나
  # "utf8", 문자/숫자/콜론/밑줄을 위해 "legacy".
  [ metric_name_validation_scheme: <string> | default = "utf8" ]

  # true면 타깃이 노출하는 네이티브 히스토그램이 스크랩 중 인식되어
  # 그대로 수집됨. false면 히스토그램의 네이티브 부분은 무시되고
  # 클래식 부분만 인식됨(명시적 클래식 버킷이 없으면 +Inf 버킷만 있는
  # 클래식 히스토그램일 수 있음).
  [ scrape_native_histograms: <boolean> | default = false ]

  # 스크랩된 클래식 히스토그램을 커스텀 버킷을 가진 네이티브 히스토그램으로
  # 변환할지 지정.
  [ convert_classic_histograms_to_nhcb: <boolean> | default = false ]

  # 히스토그램이 네이티브 부분으로도 노출되거나 커스텀 버킷을 가진
  # 네이티브 히스토그램으로 변환되더라도, 그 클래식 부분을 추가로
  # 스크랩할지 지정.
  [ always_scrape_classic_histograms: <boolean> | default = false ]

  # 활성화되면 Prometheus가 각 스크랩에 대해 추가 타임시리즈를 저장:
  # scrape_timeout_seconds, scrape_sample_limit, scrape_body_size_bytes.
  # 이 메트릭들은 타깃이 구성된 한도에 얼마나 가까운지 모니터링하는 데 도움.
  # 이 옵션은 스크랩 구성별로 재정의할 수 있음.
  [ extra_scrape_metrics: <boolean> | default = false ]

runtime:
  # Go 가비지 컬렉터 GOGC 파라미터 구성
  # 참조: https://tip.golang.org/doc/gc-guide#GOGC
  # 이 숫자를 낮추면 CPU 사용이 늘어남.
  [ gogc: <int> | default = 75 ]

# 규칙 파일은 glob 목록을 지정. 모든 일치하는 파일에서 규칙과 알림이 읽힘.
rule_files:
  [ - <filepath_glob> ... ]

# 스크랩 구성 파일은 glob 목록을 지정. 모든 일치하는 파일에서 스크랩 구성이
# 읽혀 스크랩 구성 목록에 추가됨.
scrape_config_files:
  [ - <filepath_glob> ... ]

# 스크랩 구성 목록.
scrape_configs:
  [ - <scrape_config> ... ]

# Alerting은 Alertmanager와 관련된 설정을 지정.
alerting:
  alert_relabel_configs:
    [ - <relabel_config> ... ]
  alertmanagers:
    [ - <alertmanager_config> ... ]

scrape_config (스크랩 구성)

각 scrape_config는 타깃을 식별하고 매개변수화하는 방법을 지정해요. 여기에는 다음이 포함돼요.

  • job_name: 기본적으로 스크랩된 메트릭에 할당되는 잡 이름.
  • scrape_interval: 이 잡에서 타깃을 스크랩하는 빈도(전역에서 상속).
  • scrape_timeout: 스크랩별 타임아웃. 스크랩 간격보다 클 수 없음.
  • scrape_protocols: 스크랩 중 클라이언트와 협상할 프로토콜 목록.
  • fallback_scrape_protocol: 스크랩이 빈/파싱 불가능/유효하지 않은 Content-Type을 반환할 때 사용할 폴백 프로토콜.
  • metrics_path: 타깃에서 메트릭을 가져올 HTTP 리소스 경로(기본 /metrics).
  • honor_labels: 스크랩된 데이터에 이미 있는 라벨과 Prometheus가 서버 측에서 붙이는 라벨("job", "instance", 수동 타깃 라벨, 서비스 디스커버리 라벨) 사이의 충돌을 어떻게 처리할지 제어. true면 스크랩 데이터의 라벨 값을 유지하고, false면 충돌 라벨을 exported_로 이름 바꿔 붙임(예: exported_instance). 페더레이션과 Pushgateway 스크랩에 유용.
  • honor_timestamps: 스크랩 데이터의 타임스탬프를 존중할지 제어.
  • track_timestamps_staleness: 명시적 타임스탬프가 있는 메트릭의 staleness 추적을 제어.
  • scheme: 요청에 사용할 프로토콜 스킴(http/https).
  • params: 선택적 HTTP URL 파라미터.
  • enable_compression: false면 Prometheus가 스크랩 타깃에 압축되지 않은 응답을 요청.
  • scrape_failure_log_file: 스크랩 실패가 기록되는 파일.
  • http_config: basic auth, 인증, 프록시, TLS, 커스텀 HTTP 헤더 등 HTTP 클라이언트 설정.
  • sample_limit, label_limit, label_name_length_limit, label_value_length_limit, body_size_limit, target_limit, keep_dropped_targets: 각종 스크랩 제한.
  • service discovery mechanisms: azure_sd_configs, consul_sd_configs, dns_sd_configs, ec2_sd_configs, file_sd_configs, gce_sd_configs, http_sd_configs, kubernetes_sd_configs, static_configs 등 수많은 서비스 디스커버리 구성.
  • relabel_configs, metric_relabel_configs: 타깃 라벨 재작성 스크립트.
  • static_configs: 정적으로 지정된 타깃 목록.

alerting

alerting 섹션은 Alertmanager와 관련된 설정을 지정해요. alert_relabel_configs는 Alertmanager로 보내기 전에 알림에 적용되는 relabel링이고, alertmanagers는 Alertmanager 인스턴스를 구성하는데 static_configs 또는 서비스 디스커버리로 지정하며 TLS, basic auth, api_version 같은 설정을 가져요.

remote_write / remote_read (원격 쓰기 / 원격 읽기)

원격 저장소와의 통신을 구성해요.

  • remote_write: 수집된 샘플을 원격 저장소로 보내는 구성. url(원격 엔드포인트), write_relabel_configs(전송 전 샘플 재작성), remote_timeout, queue_config(capacity, max_shards, min_shards, max_samples_per_send, batch_send_deadline, min_backoff, max_backoff), tls_config, basic_auth/authorization/oauth2, send_exemplars, send_native_histograms 같은 옵션을 포함.
  • remote_read: 원격 저장소에서 시리즈를 읽어 쿼리에 통합하는 구성. url, remote_timeout, read_recent, required_matchers, tls_config 같은 옵션.

storage (TSDB)

TSDB 저장소와 관련된 실행 시 재로드 가능한 설정. storage.tsdb 아래에 보존 기간(retention.time), 보존 크기(retention.size), lockfile_allow_relative, chunk_encoding.floats(xor/xor2) 등이 있어요. 이전에는 플래그였던 보존 설정이 이제 구성 파일에서 관리돼요.

exemplars

exemplars 섹션은 exemplar 저장의 원형 버퍼 크기를 exemplar 수로 제어해요(max_exemplars).

otlp / tracing / 기타

  • otlp: OTLP 수신기 관련 설정. 수집된 메트릭에 대한 설정. 가이드는 여기에서.
  • tracing: OpenTelemetry로 트레이스 내보내기 구성(endpoint, sampling_fraction 등).
  • feature flags: enable_feature 필드로 기능 플래그를 활성화할 수 있어요.

더 알아보기 (Learn more)