3.1 Exporter 동작 구조
PostgreSQL Exporter는 PostgreSQL과 Prometheus 사이의 번역기입니다. Prometheus가 /metrics를 요청하면 활성 collector가 SQL을 실행하고, 결과 column을 Prometheus metric으로 변환해 응답합니다.
Collector가 query를 소유한다
현재 exporter는 기능별 built-in collector를 제공합니다. 대표적인 collector는 다음과 같습니다.
| Collector | 기본 상태 | 주요 원본 |
|---|---|---|
stat_database | 활성 | pg_stat_database |
locks | 활성 | pg_locks |
replication | 활성 | recovery 함수 |
replication_slots | 활성 | pg_replication_slots |
stat_user_tables | 활성 | pg_stat_user_tables |
stat_progress_vacuum | 활성 | pg_stat_progress_vacuum |
long_running_transactions | 비활성 | pg_stat_activity |
stat_statements | 비활성 | pg_stat_statements |
stat_checkpointer | 비활성 | pg_stat_checkpointer |
기본 비활성 collector는 비용, version 조건, series 증가 가능성을 검토한 뒤 하나씩 켭니다. 모든 collector를 한 번에 활성화하면 scrape latency와 cardinality가 같이 늘어나기도 합니다.
Scrape 시점 query
Exporter는 대부분의 값을 background에서 미리 수집하지 않습니다. Scrape 요청이 올 때 SQL을 실행하므로 database가 느리면 exporter 응답도 느려집니다. Prometheus의 scrape_timeout보다 수집 시간이 길어지면 target은 DOWN으로 보입니다.
이때 다음 세 상태를 구분합니다.
- Exporter process가 죽음: TCP connection 자체가 실패합니다.
- Exporter는 살았지만 PostgreSQL 접속 실패:
/metrics에는 exporter process metric이 있고pg_up은 0입니다. - 일부 collector만 실패: exporter log와 scrape error를 확인해야 하며 metric 일부가 누락되기도 합니다.
Exporter에는 collection timeout도 있습니다. PG_EXPORTER_COLLECTION_TIMEOUT으로 database 응답이 지나치게 늦을 때 connection이 쌓이는 것을 막을 수 있습니다.
Single-target과 multi-target
일반적인 self-managed 환경은 instance마다 exporter를 붙이는 single-target 구성이 단순합니다. network 경로가 짧고 target label도 명확합니다.
Managed database처럼 exporter를 host에 설치할 수 없으면 한 exporter가 /probe?target=...으로 여러 database를 조회하는 multi-target 기능을 사용할 수 있습니다. 이 방식은 beta이며 인증 module과 relabeling 설정을 함께 관리해야 합니다.
Custom query보다 built-in collector
--extend.query-path로 YAML query를 추가하는 기능은 deprecated입니다. PostgreSQL 표준 상태를 수집할 때는 built-in collector를 우선 사용합니다. 조직 고유의 제한된 집계값이 꼭 필요하다면 다음을 검토합니다.
- 기존 collector와
pg_stat_*metric으로 계산할 수 있는가? - Prometheus recording rule로 파생할 수 있는가?
- 일반 SQL 수집이 목적이라면
sql_exporter가 더 적합한가? - label 값이 table/tenant 수에 따라 무제한 증가하지 않는가?
Source of truth 확인
Metric의 의미가 애매할 때는 세 곳을 순서대로 봅니다.
- 실제
/metrics의 HELP와 TYPE - exporter collector source와 release note
- 해당 column의 PostgreSQL 공식 문서
Dashboard 설명만 믿으면 exporter version 차이나 metric rename을 놓치기 쉽습니다.