엑스포터 작성

엑스포터 작성 (Writing exporters)

이 문서는 기존 소프트웨어(직접 계측하기 어려운 시스템, 서드파티 도구)의 메트릭을 수집해 Prometheus 형식으로 노출하는 **엑스포터(exporter)**를 작성하는 지침을 설명해요. 엑스포터는 소스 시스템에서 데이터를 얻어 게이지·카운터 등 Prometheus 메트릭으로 변환하는 별도의 프로세스입니다.

엑스포터 작성 시 고려할 백엔드(풀/푸시), 사전 정의 메트릭 수집기, 공통 메트릭(프로세스·업타임), 계측 상황, 그리고 엑스포터 패키징·배포에 대한 권장 사항을 정리합니다.

출처: 문서

본문

백엔드 선택: 풀 vs 푸시

  • 풀(pull) 방식(권장) — 엑스포터가 HTTP 서버를 띄우고 /metrics를 제공하는 방식. 대부분의 경우 이 방식이 적합합니다.
  • 푸시(push) 방식 — 스크레이프할 수 없는 짧은 배치 작업 등에서는 Pushgateway로 메트릭을 푸시합니다.

사전 정의 메트릭 수집기

가능하면 기존 클라이언트 라이브러리가 제공하는 "수집기(collector)"를 재사용하세요. 예를 들어 Go 클라이언트는:

  • 프로세스 메트릭 영어로 process_*(CPU, 메모리, 파일 디스크립터).
  • Go 런타임 메트릭 go_*.

이러한 수집기를 엑스포터에 함께 등록하면, 스크레이프 시 공통 메트릭이 자동으로 포함됩니다.

데이터 수집 유형

  • 직접 읽기: 파일, 소켓, HTTP API 등에서 데이터를 읽어 메트릭으로 변환.
  • 시스템 콜 / 하드웨어: /proc, sysfs, SNMP처럼 시스템 인터페이스에서 값을 얻는 경우.
  • 가능하면 폴링 대신 값을 갱신하는 구조로, 스크레이프 시점에 최신 값을 반환하도록 설계합니다.

계측 패턴

  • 게이지: 현재 상태(예: 온도, 연결 수).
  • 카운터: 누적 횟수(예: 총 요청).
  • 엑스포터가 소스로부터 받은 값에 오류가 있으면 그 값을 메트릭으로 노출하기보다 상태를 적절히 나태냅니다(예: up 또는 개별 메트릭).

공통 관례

  • 엑스포터는 _exporter 또는 도메인 관련 접두어를 메트릭 이름에 사용하는 것을 권장합니다(예: node_, mysqld_).
  • HELP/TYPE 주석을 제공해야 합니다.
  • 빈 값이나 NaN을 적절히 처리합니다.

패키징·배포

  • 엑스포터는 별도 바이너리/컨테이너로 배포하고, 시스템 서비스(예: systemd)로 실행하거나 컨테이너 오케스트레이션에 배포합니다.
  • 루트 권한이 필요한 수집기는 최소 권한으로 실행합니다.

더 알아보기 (Learn more)