Prometheus 모니터링 지표 수집 완벽 가이드

초급 개발자도 쉽게 이해할 수 있는 Prometheus 기반 모니터링 시스템 구축 가이드입니다. node-exporter, blackbox-exporter 설치부터 Ansible 자동화, 메트릭 수집 설정까지 실무에 필요한 모든 것을 담았습니다.

---

목차

1. Prometheus 아키텍처 이해
2. node-exporter 설치와 설정
3. blackbox-exporter로 외부 모니터링
4. Ansible role로 exporter 배포
5. scrape_configs 설정
6. 메트릭 네이밍 컨벤션

---

1. Prometheus 아키텍처 이해

입사 3개월 차 김개발 씨는 어느 날 갑자기 팀장님께 호출을 받았습니다. "김 개발님, 우리 서비스가 자꾸 느려진다는 고객 불만이 들어오는데, 정확히 어디서 문제가 생기는지 알 수가 없네요.

모니터링 시스템을 구축해야 할 것 같은데..." 김개발 씨는 막막했습니다. 모니터링이라니, 어디서부터 시작해야 할까요?

Prometheus는 오픈소스 모니터링 시스템으로, 시스템의 다양한 지표를 수집하고 저장하며 분석합니다. 마치 병원에서 환자의 체온, 혈압, 심박수를 측정하듯이 서버의 CPU, 메모리, 네트워크 상태를 끊임없이 측정합니다.

Pull 방식으로 데이터를 수집하며, 시계열 데이터베이스에 저장하여 시간에 따른 변화를 추적할 수 있습니다.

다음 코드를 살펴봅시다.

# Prometheus 기본 구조 예시 (prometheus.yml)
global:
  scrape_interval: 15s  # 15초마다 지표 수집
  evaluation_interval: 15s  # 15초마다 규칙 평가

# 지표를 수집할 대상 정의
scrape_configs:
  - job_name: 'prometheus'
    static_configs:
      - targets: ['localhost:9090']  # Prometheus 자신의 지표 수집

  - job_name: 'node'
    static_configs:
      - targets: ['localhost:9100']  # 서버 지표 수집

김개발 씨는 선배 개발자 박시니어 씨에게 도움을 청했습니다. "선배님, 모니터링 시스템이 뭔가요?

어떻게 만드나요?" 박시니어 씨가 웃으며 대답했습니다. "좋은 질문이에요.

먼저 Prometheus가 뭔지부터 이해해봅시다." Prometheus란 무엇일까요? 쉽게 비유하자면, Prometheus는 마치 건강검진 센터와 같습니다. 병원에서 환자의 건강 상태를 확인하기 위해 체온, 혈압, 심박수를 주기적으로 측정하듯이, Prometheus는 서버의 상태를 확인하기 위해 CPU 사용률, 메모리 사용량, 디스크 용량 등을 주기적으로 측정합니다.

이렇게 수집된 데이터를 분석하면 시스템이 건강한지, 문제가 생길 조짐은 없는지 알 수 있습니다. 모니터링이 없던 시절의 문제 Prometheus가 없던 시절에는 어땠을까요?

개발자들은 서버에 직접 접속해서 명령어를 입력해야 했습니다. "지금 CPU 사용률이 얼마지?" 하고 확인하려면 top 명령어를 실행하고, 메모리는 free 명령어로 확인했습니다.

하지만 서버가 10대, 100대로 늘어나면 어떻게 될까요? 모든 서버에 일일이 접속해서 확인할 수는 없습니다.

더 큰 문제는 과거 데이터를 알 수 없다는 점이었습니다. 지금 당장 CPU가 정상이라고 해도, 새벽 3시에 갑자기 CPU가 100%로 치솟아서 서비스가 다운됐다면?

그때의 상황을 알 방법이 없습니다. 마치 건강검진을 한 번도 받지 않다가 갑자기 쓰러진 후에야 병원에 가는 것과 같습니다.

Prometheus의 등장 바로 이런 문제를 해결하기 위해 Prometheus가 등장했습니다. Prometheus를 사용하면 자동으로 지표를 수집할 수 있습니다.

개발자가 일일이 서버에 접속하지 않아도, Prometheus가 알아서 15초마다 각 서버를 방문하여 데이터를 가져옵니다. 또한 모든 데이터를 시계열 데이터베이스에 저장하므로, 과거 어느 시점의 상태도 확인할 수 있습니다.

무엇보다 그래프로 시각화할 수 있어서 한눈에 추세를 파악할 수 있습니다. Prometheus의 핵심 아키텍처 Prometheus는 크게 세 가지 구성 요소로 이루어집니다.

첫 번째는 Prometheus 서버 자체입니다. 이것이 중앙 허브 역할을 합니다.

설정 파일에 정의된 대로 주기적으로 각 서버를 방문하여 지표를 수집하고, 시계열 데이터베이스에 저장하며, PromQL이라는 쿼리 언어로 데이터를 조회할 수 있게 해줍니다. 두 번째는 Exporter입니다.

각 서버나 애플리케이션에 설치되어 지표를 노출하는 작은 프로그램입니다. 예를 들어 node-exporter는 서버의 하드웨어 및 OS 지표를 노출하고, blackbox-exporter는 외부 서비스의 응답 시간을 측정합니다.

마치 체온계, 혈압계처럼 각각의 측정 도구가 있는 것과 같습니다. 세 번째는 알림 및 시각화 도구입니다.

Alertmanager는 임계값을 넘으면 알림을 보내고, Grafana는 예쁜 대시보드를 만들 수 있게 해줍니다. Pull 방식의 장점 Prometheus의 가장 큰 특징은 Pull 방식으로 데이터를 수집한다는 점입니다.

Push 방식은 각 서버가 중앙 서버로 데이터를 보내는 방식입니다. 반면 Pull 방식은 중앙 서버(Prometheus)가 각 서버를 방문하여 데이터를 가져오는 방식입니다.

마치 우편배달부가 우편함을 돌아다니며 편지를 수거하는 것과 같습니다. Pull 방식의 장점은 무엇일까요?

첫째, 네트워크 장애에 강합니다. 특정 서버가 일시적으로 접속 불가능하더라도, Prometheus는 다음 수집 주기에 다시 시도합니다.

둘째, 서비스 디스커버리와 연동하기 쉽습니다. Kubernetes 같은 환경에서 서버가 동적으로 추가되거나 삭제되어도 자동으로 감지할 수 있습니다.

시계열 데이터베이스의 힘 위의 설정 파일을 살펴보면, scrape_interval이 15초로 설정되어 있습니다. 이는 Prometheus가 15초마다 한 번씩 각 타겟을 방문하여 지표를 수집한다는 의미입니다.

이렇게 수집된 데이터는 시간과 함께 저장되므로, "어제 오후 3시의 CPU 사용률은?" 같은 질문에 답할 수 있습니다. 마치 주식 차트처럼 시간에 따른 변화를 추적할 수 있는 것입니다.

실무 활용 사례 실제 현업에서는 어떻게 활용할까요? 예를 들어 쇼핑몰 서비스를 운영한다고 가정해봅시다.

평소에는 CPU 사용률이 20%인데, 특정 시간대에 갑자기 90%로 치솟는다면? Prometheus로 확인해보니 매일 오후 8시에 급증하더군요.

알고 보니 인기 상품의 타임세일 시간이었습니다. 이런 패턴을 파악하면 사전에 서버를 증설하여 대비할 수 있습니다.

또 다른 사례로, 어느 날 갑자기 디스크 용량이 부족하다는 알림이 왔습니다. Prometheus 그래프를 확인해보니 지난 2주 동안 선형적으로 증가하는 추세더군요.

로그 파일이 삭제되지 않고 계속 쌓이고 있었던 것입니다. 이처럼 Prometheus는 단순히 현재 상태뿐 아니라 추세를 파악할 수 있게 해줍니다.

주의사항 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 너무 짧은 수집 주기를 설정하는 것입니다.

1초마다 수집하면 더 정확하지 않을까 생각하지만, 실제로는 Prometheus 서버에 과부하가 걸리고 저장 공간도 금방 차버립니다. 대부분의 경우 15초면 충분합니다.

또 다른 실수는 모든 지표를 수집하려는 욕심입니다. 필요하지 않은 지표까지 수집하면 데이터베이스가 비대해지고 쿼리 속도도 느려집니다.

꼭 필요한 지표만 선별하여 수집하는 것이 좋습니다. 정리 다시 김개발 씨의 이야기로 돌아가 봅시다.

박시니어 씨의 설명을 들은 김개발 씨는 고개를 끄덕였습니다. "아, Prometheus가 자동으로 서버를 돌아다니며 지표를 수집하고, 시간에 따라 저장해두는 시스템이군요!" Prometheus의 아키텍처를 제대로 이해하면 모니터링 시스템을 효과적으로 구축할 수 있습니다.

다음 단계에서는 실제로 Exporter를 설치하고 설정하는 방법을 배워보겠습니다.

실전 팁

💡 - scrape_interval은 15초가 적당하며, 너무 짧게 설정하지 마세요

• 필요한 지표만 선별하여 수집하면 성능과 비용을 절약할 수 있습니다
• Prometheus는 Pull 방식이므로 방화벽 설정에 주의하세요

---

2. node-exporter 설치와 설정

김개발 씨는 Prometheus의 구조를 이해했지만, 여전히 막막했습니다. "그래서 실제로 어떻게 설치하나요?" 박시니어 씨가 웃으며 답했습니다.

"먼저 node-exporter부터 설치해봅시다. 이게 가장 기본이에요."

node-exporter는 Linux 서버의 하드웨어 및 OS 지표를 수집하는 Exporter입니다. CPU, 메모리, 디스크, 네트워크 등 시스템의 기본 지표를 제공합니다.

마치 건강검진에서 기본 혈액검사를 하는 것처럼, 서버 모니터링의 가장 기초적인 도구입니다. 9100 포트로 지표를 노출하며, Prometheus가 이 포트로 접속하여 데이터를 가져갑니다.

다음 코드를 살펴봅시다.

# node-exporter 다운로드 및 설치 (Ubuntu/Debian)
wget https://github.com/prometheus/node_exporter/releases/download/v1.7.0/node_exporter-1.7.0.linux-amd64.tar.gz
tar xvfz node_exporter-1.7.0.linux-amd64.tar.gz
sudo mv node_exporter-1.7.0.linux-amd64/node_exporter /usr/local/bin/

# systemd 서비스 파일 생성
sudo tee /etc/systemd/system/node_exporter.service > /dev/null <<EOF
[Unit]
Description=Node Exporter
After=network.target

[Service]
User=node_exporter
Group=node_exporter
Type=simple
ExecStart=/usr/local/bin/node_exporter --collector.systemd --collector.processes
Restart=always

[Install]
WantedBy=multi-user.target
EOF

# 서비스 시작
sudo systemctl daemon-reload
sudo systemctl enable node_exporter
sudo systemctl start node_exporter

# 지표 확인 (정상적으로 노출되는지 테스트)
curl http://localhost:9100/metrics

박시니어 씨가 터미널을 열며 말했습니다. "자, 이제 실제로 node-exporter를 설치해봅시다.

생각보다 간단해요." node-exporter란 무엇일까요? node-exporter는 Linux 서버의 다양한 지표를 수집하는 작은 프로그램입니다. 쉽게 비유하자면, 마치 자동차의 계기판과 같습니다.

자동차 계기판에는 속도계, 연료계, 엔진 온도계 등이 있어서 운전자가 차량 상태를 한눈에 파악할 수 있습니다. node-exporter도 마찬가지로 서버의 CPU 사용률, 메모리 사용량, 디스크 용량, 네트워크 트래픽 등을 측정하여 보여줍니다.

왜 node-exporter가 필요할까요? Prometheus 자체는 데이터를 수집하고 저장하는 시스템입니다. 하지만 각 서버의 지표를 직접 읽을 수는 없습니다.

마치 온도계 없이는 체온을 측정할 수 없는 것처럼, Prometheus도 Exporter 없이는 서버 지표를 수집할 수 없습니다. 과거에는 서버에 직접 접속해서 top, free, df 같은 명령어를 실행해야 했습니다.

하지만 이런 방식은 자동화할 수 없고, 과거 데이터도 남지 않습니다. node-exporter를 사용하면 이 모든 지표가 HTTP 엔드포인트로 노출되어, Prometheus가 자동으로 수집할 수 있습니다.

설치 과정 살펴보기 위의 코드를 단계별로 살펴보겠습니다. 먼저 GitHub에서 최신 버전의 node-exporter를 다운로드합니다.

Prometheus 프로젝트는 오픈소스이므로 누구나 무료로 다운받아 사용할 수 있습니다. 압축을 풀고 실행 파일을 /usr/local/bin 디렉토리로 이동시킵니다.

이 디렉토리는 시스템 전역에서 접근 가능한 실행 파일을 두는 표준 위치입니다. 다음으로 systemd 서비스 파일을 생성합니다.

systemd는 Linux에서 서비스를 관리하는 시스템입니다. 이 파일을 만들어두면 서버가 재부팅되어도 node-exporter가 자동으로 시작되고, 문제가 생기면 자동으로 재시작됩니다.

마치 자동차의 시동 버튼처럼, 한 번만 설정해두면 알아서 작동합니다. 서비스 파일의 ExecStart 부분을 보면 몇 가지 옵션이 있습니다.

--collector.systemd는 systemd 서비스 상태를 수집하고, --collector.processes는 프로세스 정보를 수집합니다. node-exporter는 기본적으로 많은 collector를 활성화하지만, 특정 collector는 명시적으로 활성화해야 합니다.

마지막으로 systemctl 명령어로 서비스를 시작합니다. enable은 부팅 시 자동 시작을 활성화하고, start는 즉시 서비스를 시작합니다.

지표 확인하기 curl 명령어로 http://localhost:9100/metrics에 접속하면 무슨 일이 일어날까요? 화면에 수많은 지표가 쏟아져 나옵니다.

node_cpu_seconds_total, node_memory_MemAvailable_bytes, node_disk_read_bytes_total 같은 이름들이 보입니다. 각 지표마다 현재 값이 표시되어 있습니다.

이것이 바로 Prometheus가 수집할 원천 데이터입니다. 처음 보면 압도적으로 많아 보이지만, 걱정할 필요 없습니다.

Prometheus가 알아서 이 데이터를 파싱하여 저장합니다. 우리는 나중에 필요한 지표만 쿼리하면 됩니다.

실무 활용 사례 실제 현업에서는 어떻게 활용할까요? 어느 날 서비스가 느려진다는 고객 불만이 들어왔습니다.

node-exporter로 수집한 데이터를 확인해보니, 특정 서버의 메모리 사용률이 95%에 달했습니다. 원인을 조사해보니 메모리 누수가 있는 프로세스를 발견했고, 코드를 수정하여 문제를 해결했습니다.

만약 node-exporter가 없었다면 문제의 원인을 찾기까지 훨씬 더 오랜 시간이 걸렸을 것입니다. 또 다른 사례로, 디스크 용량이 매주 금요일마다 급증하는 패턴을 발견했습니다.

알고 보니 주간 로그 백업 작업이 돌아가는데, 백업이 끝난 후 원본 로그를 삭제하지 않고 있었습니다. 이런 패턴은 node-exporter의 디스크 지표를 시간대별로 분석하지 않았다면 발견하기 어려웠을 것입니다.

주의사항 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 보안을 간과하는 것입니다.

node-exporter의 9100 포트는 기본적으로 인증이 없습니다. 누구나 접속하면 서버의 모든 지표를 볼 수 있습니다.

따라서 방화벽으로 Prometheus 서버만 접속할 수 있도록 제한해야 합니다. 또 다른 실수는 불필요한 collector를 활성화하는 것입니다.

모든 collector를 켜두면 오버헤드가 증가합니다. 실제로 사용할 지표만 활성화하는 것이 좋습니다.

예를 들어 대부분의 경우 --collector.wifi는 필요하지 않습니다. 정리 김개발 씨는 직접 node-exporter를 설치하고 curl로 지표를 확인해보았습니다.

"와, 정말 쉽네요! 이렇게 간단하게 서버의 모든 지표를 수집할 수 있다니!" node-exporter를 제대로 설치하면 서버 모니터링의 기초를 다질 수 있습니다.

다음 단계에서는 외부 서비스를 모니터링하는 blackbox-exporter를 살펴보겠습니다.

실전 팁

💡 - 방화벽으로 9100 포트를 Prometheus 서버로만 제한하세요

• 필요한 collector만 활성화하여 오버헤드를 줄이세요
• systemd 서비스로 등록하면 재부팅 시에도 자동으로 시작됩니다

---

3. blackbox-exporter로 외부 모니터링

node-exporter를 성공적으로 설치한 김개발 씨는 뿌듯했습니다. 하지만 팀장님이 새로운 요구사항을 주었습니다.

"우리 API가 외부에서 제대로 접속되는지도 확인해야 해요. 응답 시간은 얼마나 걸리는지도 알고 싶고요." 박시니어 씨가 말했습니다.

"그럴 때는 blackbox-exporter를 쓰면 돼요."

blackbox-exporter는 외부 관점에서 서비스를 모니터링하는 Exporter입니다. HTTP, HTTPS, DNS, TCP, ICMP 등 다양한 프로토콜로 대상 서비스에 접속하여 응답 시간, 성공 여부, SSL 인증서 만료일 등을 측정합니다.

마치 고객이 실제로 서비스를 이용하는 것처럼 외부에서 테스트하는 것입니다. 9115 포트로 동작하며, Prometheus가 이 Exporter를 통해 외부 서비스를 프로브합니다.

다음 코드를 살펴봅시다.

# blackbox-exporter 설치
wget https://github.com/prometheus/blackbox_exporter/releases/download/v0.24.0/blackbox_exporter-0.24.0.linux-amd64.tar.gz
tar xvfz blackbox_exporter-0.24.0.linux-amd64.tar.gz
sudo mv blackbox_exporter-0.24.0.linux-amd64/blackbox_exporter /usr/local/bin/

# 설정 파일 생성 (/etc/blackbox_exporter/config.yml)
modules:
  http_2xx:  # HTTP 200 응답 확인 모듈
    prober: http
    timeout: 5s
    http:
      valid_http_versions: ["HTTP/1.1", "HTTP/2.0"]
      valid_status_codes: [200]  # 200 응답만 성공으로 간주
      method: GET
      fail_if_ssl: false  # SSL 인증서 오류 시 실패
      fail_if_not_ssl: false

  tcp_connect:  # TCP 연결 확인 모듈
    prober: tcp
    timeout: 5s

# systemd 서비스 등록
sudo tee /etc/systemd/system/blackbox_exporter.service > /dev/null <<EOF
[Unit]
Description=Blackbox Exporter
After=network.target

[Service]
User=blackbox_exporter
Type=simple
ExecStart=/usr/local/bin/blackbox_exporter --config.file=/etc/blackbox_exporter/config.yml
Restart=always

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable blackbox_exporter
sudo systemctl start blackbox_exporter

# 테스트: Google 홈페이지 HTTP 프로브
curl 'http://localhost:9115/probe?target=https://www.google.com&module=http_2xx'

박시니어 씨가 화이트보드에 그림을 그리며 설명했습니다. "node-exporter는 서버 내부를 모니터링하는 거였죠?

blackbox-exporter는 외부에서 서비스를 모니터링합니다." blackbox-exporter란 무엇일까요? blackbox-exporter는 마치 미스터리 쇼퍼와 같습니다. 레스토랑이 서비스 품질을 확인하기 위해 일반 손님처럼 가장한 평가자를 보내는 것처럼, blackbox-exporter는 실제 사용자처럼 서비스에 접속하여 정상적으로 작동하는지 확인합니다.

서버 내부는 정상이어도, 방화벽 문제나 DNS 문제로 외부에서 접속이 안 될 수도 있기 때문입니다. 이름이 blackbox인 이유는 서비스의 내부 구조를 모르는 상태에서 외부에서만 테스트하기 때문입니다.

마치 블랙박스처럼 입력과 출력만 확인하는 것입니다. 왜 외부 모니터링이 필요할까요? 실제 사례를 하나 들어보겠습니다.

어느 날 한 서비스가 정상적으로 작동한다고 생각했는데, 고객들로부터 접속이 안 된다는 불만이 쏟아졌습니다. 서버 내부 지표를 확인해보니 CPU, 메모리 모두 정상이었습니다.

무엇이 문제였을까요? 알고 보니 클라우드 업체의 네트워크 장비에 문제가 생겨서 외부에서 접속이 안 되고 있었습니다.

서버 자체는 정상이지만, 고객은 접속할 수 없는 상황이었던 것입니다. 이런 문제는 외부에서 테스트하지 않으면 발견할 수 없습니다.

또 다른 사례로, SSL 인증서 만료 문제가 있습니다. 인증서가 만료되면 브라우저에서 경고가 뜨고 사용자들이 접속을 꺼립니다.

blackbox-exporter는 SSL 인증서의 만료일을 자동으로 확인하여, 만료 30일 전에 알림을 보낼 수 있습니다. 설정 파일 살펴보기 위의 설정 파일을 단계별로 살펴보겠습니다.

blackbox-exporter는 모듈 개념을 사용합니다. 각 모듈은 서로 다른 프로브 방식을 정의합니다.

http_2xx 모듈은 HTTP 요청을 보내서 200 응답을 받는지 확인합니다. timeout을 5초로 설정했으므로, 5초 이내에 응답이 오지 않으면 실패로 간주합니다.

valid_status_codes에는 성공으로 간주할 HTTP 상태 코드를 나열합니다. 보통은 200만 허용하지만, 경우에 따라 301, 302 같은 리다이렉트도 성공으로 볼 수도 있습니다.

tcp_connect 모듈은 단순히 TCP 연결이 되는지만 확인합니다. 예를 들어 데이터베이스 포트(3306, 5432)가 열려 있는지 확인할 때 유용합니다.

프로브 동작 원리 curl 명령어로 테스트해보면 어떻게 동작하는지 알 수 있습니다. blackbox-exporter는 9115 포트에서 대기하고 있습니다.

/probe 엔드포인트로 요청을 보낼 때 두 가지 파라미터를 전달합니다. target은 테스트할 대상 URL이고, module은 어떤 프로브 방식을 사용할지 지정합니다.

blackbox-exporter는 이 요청을 받으면 즉시 https://www.google.com에 접속을 시도합니다. 응답을 받으면 probe_success(성공 여부), probe_duration_seconds(응답 시간), probe_http_status_code(HTTP 상태 코드) 같은 지표를 반환합니다.

Prometheus는 이런 방식으로 주기적으로 blackbox-exporter에 프로브를 요청하고, 결과를 시계열 데이터로 저장합니다. 실무 활용 사례 실제 현업에서는 어떻게 활용할까요?

어느 금융 서비스 회사에서 API 응답 시간을 모니터링하고 있었습니다. 평소에는 100ms 이내로 응답하는데, 어느 날부터 간헐적으로 3초 이상 걸리는 경우가 발생했습니다.

blackbox-exporter의 probe_duration_seconds 지표를 분석해보니, 특정 시간대에만 느려지는 패턴을 발견했습니다. 원인을 조사해보니 데이터베이스 백업 작업이 그 시간에 돌아가면서 API가 느려지고 있었습니다.

백업 시간을 새벽으로 옮기자 문제가 해결되었습니다. 이처럼 blackbox-exporter는 사용자 경험을 직접 측정할 수 있습니다.

또 다른 사례로, 마이크로서비스 아키텍처를 사용하는 회사에서 각 서비스 간의 연결성을 모니터링했습니다. 서비스 A가 서비스 B를 호출할 수 있는지, 응답 시간은 적절한지를 blackbox-exporter로 주기적으로 확인했습니다.

이를 통해 특정 서비스가 다운되면 즉시 알림을 받을 수 있었습니다. 주의사항 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 너무 짧은 주기로 프로브하는 것입니다. 예를 들어 1초마다 외부 API를 호출하면 서버에 과부하가 걸릴 수 있습니다.

대부분의 경우 30초~1분 주기면 충분합니다. 또 다른 실수는 인증이 필요한 API를 프로브하지 못하는 것입니다.

blackbox-exporter는 기본적으로 간단한 HTTP 요청만 보냅니다. JWT 토큰이나 API 키가 필요한 경우, 설정 파일에 헤더를 추가해야 합니다.

정리 김개발 씨는 blackbox-exporter로 회사의 주요 API를 프로브하도록 설정했습니다. "이제 외부에서도 서비스를 모니터링할 수 있네요!" 외부 모니터링과 내부 모니터링을 함께 사용하면 서비스의 전체적인 건강 상태를 파악할 수 있습니다.

다음 단계에서는 여러 서버에 Exporter를 자동으로 배포하는 방법을 알아보겠습니다.

실전 팁

💡 - 프로브 주기는 30초~1분이 적당하며, 너무 짧으면 부하가 증가합니다

• SSL 인증서 만료일을 모니터링하여 사전에 알림을 받으세요
• 중요한 API 엔드포인트를 여러 위치에서 프로브하면 더 정확합니다

---

4. Ansible role로 exporter 배포

김개발 씨는 두 서버에 node-exporter와 blackbox-exporter를 설치하고 뿌듯해했습니다. 하지만 팀장님이 말했습니다.

"좋아요! 그런데 서버가 50대인데, 하나씩 설치하려면 언제 끝나나요?" 김개발 씨는 막막해졌습니다.

박시니어 씨가 웃으며 말했습니다. "Ansible을 쓰면 한 번에 배포할 수 있어요."

Ansible은 서버 설정 자동화 도구로, YAML 파일로 작업을 정의하면 여러 서버에 동시에 배포할 수 있습니다. Role은 재사용 가능한 작업 묶음으로, node-exporter 설치 작업을 role로 만들어두면 어떤 서버에든 쉽게 적용할 수 있습니다.

마치 레시피처럼 한 번 작성해두면 언제든지 똑같이 요리할 수 있는 것입니다. SSH로 접속하여 명령을 실행하므로, 각 서버에 에이전트를 설치할 필요가 없습니다.

다음 코드를 살펴봅시다.

# Ansible role 구조 (roles/node_exporter/tasks/main.yml)
---
- name: node-exporter 사용자 생성
  user:
    name: node_exporter
    system: yes
    shell: /bin/false

- name: node-exporter 다운로드
  get_url:
    url: https://github.com/prometheus/node_exporter/releases/download/v1.7.0/node_exporter-1.7.0.linux-amd64.tar.gz
    dest: /tmp/node_exporter.tar.gz

- name: node-exporter 압축 해제
  unarchive:
    src: /tmp/node_exporter.tar.gz
    dest: /tmp/
    remote_src: yes

- name: node-exporter 바이너리 복사
  copy:
    src: /tmp/node_exporter-1.7.0.linux-amd64/node_exporter
    dest: /usr/local/bin/node_exporter
    mode: '0755'
    remote_src: yes

- name: systemd 서비스 파일 생성
  template:
    src: node_exporter.service.j2
    dest: /etc/systemd/system/node_exporter.service
  notify: reload systemd  # 변경 시 systemd 재로드

- name: node-exporter 서비스 시작 및 활성화
  systemd:
    name: node_exporter
    state: started
    enabled: yes

# Playbook 예시 (deploy_exporters.yml)
---
- hosts: web_servers  # 인벤토리에서 web_servers 그룹
  become: yes  # sudo 권한으로 실행
  roles:
    - node_exporter  # role 적용

박시니어 씨가 설명을 시작했습니다. "50대 서버에 일일이 SSH 접속해서 명령어를 실행하는 건 비효율적이죠.

Ansible을 쓰면 한 방에 해결됩니다." Ansible이란 무엇일까요? Ansible은 마치 요리 레시피와 같습니다. 한 번 레시피를 작성해두면, 누가 요리하든 똑같은 결과가 나옵니다.

Ansible도 마찬가지로 서버 설정 작업을 YAML 파일로 작성해두면, 어떤 서버에든 똑같이 적용할 수 있습니다. 가장 큰 장점은 에이전트가 필요 없다는 점입니다.

Chef나 Puppet 같은 다른 도구들은 각 서버에 에이전트를 설치해야 하지만, Ansible은 SSH만 있으면 됩니다. 이미 모든 Linux 서버에는 SSH가 설치되어 있으므로 추가 설치가 필요 없습니다.

Role이란 무엇일까요? Role은 재사용 가능한 작업 묶음입니다. 예를 들어 node-exporter를 설치하는 작업을 node_exporter role로 만들어두면, 어떤 서버에든 이 role을 적용하여 설치할 수 있습니다.

마치 레고 블록과 같습니다. 각 role은 하나의 기능을 담당하는 블록이고, 이 블록들을 조합하여 복잡한 서버 환경을 구축할 수 있습니다.

예를 들어 웹 서버에는 nginx role과 node_exporter role을 적용하고, 데이터베이스 서버에는 postgresql role과 node_exporter role을 적용하는 식입니다. Role 구조 살펴보기 Ansible role은 정해진 디렉토리 구조를 따릅니다.

roles/node_exporter/tasks/main.yml 파일이 핵심입니다. 여기에 실제 작업들이 순서대로 나열됩니다.

각 작업은 name으로 설명하고, module로 실제 동작을 지정합니다. 첫 번째 작업은 node_exporter 사용자를 생성합니다.

보안을 위해 root가 아닌 별도 사용자로 실행하는 것이 좋습니다. system: yes는 시스템 사용자로 생성한다는 의미이고, shell: /bin/false는 로그인을 막는다는 의미입니다.

두 번째 작업은 get_url 모듈로 GitHub에서 파일을 다운로드합니다. 세 번째는 unarchive 모듈로 압축을 풉니다.

remote_src: yes는 원격 서버에 있는 파일을 압축 해제한다는 의미입니다. 네 번째는 실행 파일을 /usr/local/bin으로 복사하고 실행 권한을 부여합니다.

다섯 번째는 template 모듈로 systemd 서비스 파일을 생성합니다. 이때 notify를 사용하면 파일이 변경되었을 때만 systemd를 재로드합니다.

마지막으로 systemd 모듈로 서비스를 시작하고 부팅 시 자동 시작되도록 설정합니다. Playbook으로 배포하기 Playbook은 어떤 서버에 어떤 role을 적용할지 정의하는 파일입니다.

hosts: web_servers는 인벤토리 파일에 정의된 web_servers 그룹의 모든 서버를 대상으로 한다는 의미입니다. become: yes는 sudo 권한으로 실행한다는 의미입니다.

roles 섹션에 node_exporter를 나열하면 해당 role이 적용됩니다. 이제 다음 명령어만 실행하면 됩니다: ansible-playbook -i inventory.ini deploy_exporters.yml Ansible은 인벤토리에 나열된 모든 서버에 SSH로 접속하여 작업을 실행합니다.

50대 서버든 100대 서버든 상관없이 동시에 배포됩니다. 실무 활용 사례 실제 현업에서는 어떻게 활용할까요?

어느 이커머스 회사에서 블랙프라이데이를 앞두고 서버를 50대에서 200대로 긴급 증설했습니다. 모든 서버에 모니터링을 설정해야 했는데, Ansible role 덕분에 1시간 만에 완료할 수 있었습니다.

만약 수작업으로 했다면 며칠이 걸렸을 것입니다. 또 다른 사례로, 보안 업데이트가 나왔을 때 모든 서버의 node-exporter를 새 버전으로 업그레이드해야 했습니다.

role 파일에서 버전 번호만 바꾸고 playbook을 실행하면 끝입니다. 모든 서버가 5분 안에 업데이트되었습니다.

멱등성의 중요성 Ansible의 핵심 개념 중 하나는 멱등성입니다. 멱등성이란 같은 작업을 여러 번 실행해도 결과가 동일하다는 의미입니다.

예를 들어 사용자 생성 작업을 실행했는데, 이미 사용자가 존재한다면 그냥 건너뜁니다. 파일 복사 작업을 실행했는데, 파일이 이미 존재하고 내용이 같다면 복사하지 않습니다.

이런 특성 덕분에 playbook을 안심하고 반복 실행할 수 있습니다. 실수로 두 번 실행해도 문제가 생기지 않습니다.

주의사항 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 변수 관리를 소홀히 하는 것입니다.

버전 번호를 하드코딩하면 업데이트할 때마다 여러 곳을 수정해야 합니다. 변수로 빼내서 한 곳에서 관리하는 것이 좋습니다.

또 다른 실수는 오류 처리를 하지 않는 것입니다. 예를 들어 다운로드가 실패하면 어떻게 할까요?

ignore_errors나 failed_when을 사용하여 오류 상황을 적절히 처리해야 합니다. 정리 김개발 씨는 Ansible role을 작성하고 50대 서버에 배포했습니다.

"와, 정말 1시간도 안 걸렸어요!" 박시니어 씨가 웃으며 말했습니다. "이제 진짜 DevOps 엔지니어가 되어가는군요." Ansible을 제대로 활용하면 수백 대의 서버도 쉽게 관리할 수 있습니다.

다음 단계에서는 Prometheus가 이렇게 배포된 Exporter에서 지표를 수집하도록 설정하는 방법을 알아보겠습니다.

실전 팁

💡 - Role은 버전 관리 시스템(Git)에 저장하여 팀원과 공유하세요

• 변수를 활용하여 버전 번호 같은 값을 한 곳에서 관리하세요
• 멱등성을 유지하여 playbook을 안전하게 반복 실행할 수 있도록 하세요

---

5. scrape configs 설정

모든 서버에 Exporter를 배포한 김개발 씨는 기대에 찼습니다. 하지만 Prometheus 대시보드를 열어보니 아무 데이터도 보이지 않았습니다.

"왜 수집이 안 되죠?" 박시니어 씨가 말했습니다. "Prometheus에게 어디서 데이터를 수집할지 알려줘야죠.

scrape_configs를 설정해야 해요."

scrape_configs는 Prometheus가 어떤 대상에서 지표를 수집할지 정의하는 설정입니다. 각 job마다 타겟 목록, 수집 주기, 라벨 등을 지정할 수 있습니다.

마치 우편배달부에게 배달할 주소 목록을 주는 것과 같습니다. static_configs로 고정된 서버 목록을 지정하거나, 서비스 디스커버리로 동적으로 타겟을 발견할 수도 있습니다.

Prometheus는 이 설정에 따라 주기적으로 각 타겟을 방문하여 /metrics 엔드포인트에서 데이터를 수집합니다.

다음 코드를 살펴봅시다.

# prometheus.yml의 scrape_configs 섹션
scrape_configs:
  # node-exporter 수집 설정
  - job_name: 'node'
    scrape_interval: 15s  # 15초마다 수집 (기본값 사용 시 생략 가능)
    static_configs:
      - targets:
          - 'web1.example.com:9100'
          - 'web2.example.com:9100'
          - 'db1.example.com:9100'
        labels:
          env: 'production'  # 모든 지표에 env=production 라벨 추가
          role: 'web'

      - targets:
          - 'db1.example.com:9100'
        labels:
          env: 'production'
          role: 'database'

  # blackbox-exporter를 통한 HTTP 프로브
  - job_name: 'blackbox'
    metrics_path: /probe  # /metrics 대신 /probe 사용
    params:
      module: [http_2xx]  # blackbox 설정의 http_2xx 모듈 사용
    static_configs:
      - targets:
          - https://api.example.com/health
          - https://www.example.com
    relabel_configs:
      # target을 __param_target으로 변경 (blackbox에 전달)
      - source_labels: [__address__]
        target_label: __param_target
      # 실제 수집 대상을 blackbox-exporter로 변경
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: localhost:9115  # blackbox-exporter 주소

# 설정 파일 검증
promtool check config prometheus.yml

# Prometheus 재시작으로 설정 적용
systemctl restart prometheus

박시니어 씨가 prometheus.yml 파일을 열며 설명했습니다. "Exporter를 설치했다고 자동으로 수집되는 게 아니에요.

Prometheus에게 알려줘야죠." scrape_configs란 무엇일까요? scrape_configs는 마치 배달 기사의 배달 목록과 같습니다. 어떤 주소로 가야 하는지, 얼마나 자주 방문해야 하는지, 어떤 메모를 남겨야 하는지 등이 모두 적혀 있습니다.

Prometheus는 이 목록을 보고 각 타겟을 주기적으로 방문하여 지표를 수집합니다. job_name의 의미 각 수집 설정은 job_name으로 그룹화됩니다.

job은 논리적인 묶음입니다. 예를 들어 모든 node-exporter를 'node' job으로 묶고, 모든 blackbox 프로브를 'blackbox' job으로 묶습니다.

나중에 PromQL로 쿼리할 때 job 라벨로 필터링할 수 있어서 편리합니다. 같은 job 내에서도 여러 static_configs 블록을 만들 수 있습니다.

위의 예시에서 웹 서버와 데이터베이스 서버를 분리하여 각각 다른 라벨을 붙였습니다. 이렇게 하면 "웹 서버의 CPU 사용률" 같은 쿼리를 쉽게 만들 수 있습니다.

라벨의 활용 라벨은 Prometheus에서 매우 중요한 개념입니다. 라벨은 지표에 붙는 태그와 같습니다.

env: 'production' 라벨을 붙이면 해당 서버가 운영 환경임을 나타냅니다. 나중에 개발 환경과 운영 환경의 지표를 분리하여 볼 수 있습니다.

role: 'web'이나 role: 'database' 같은 라벨을 붙이면 서버의 역할을 구분할 수 있습니다. "데이터베이스 서버들의 평균 메모리 사용률"을 계산하려면 role="database"로 필터링하면 됩니다.

라벨은 자유롭게 추가할 수 있습니다. team, region, version 등 필요한 라벨을 마음대로 붙일 수 있습니다.

blackbox-exporter 설정의 특수성 blackbox-exporter를 위한 설정은 조금 복잡합니다. 일반 Exporter는 그냥 타겟의 /metrics 엔드포인트를 호출하면 됩니다.

하지만 blackbox-exporter는 중개자 역할을 하므로, 실제 프로브할 대상을 파라미터로 전달해야 합니다. relabel_configs는 이런 복잡한 변환을 처리합니다.

첫 번째 규칙은 targets에 나열된 URL을 __param_target 파라미터로 변환합니다. 두 번째 규칙은 instance 라벨을 설정하여 나중에 어떤 URL을 프로브한 결과인지 알 수 있게 합니다.

세 번째 규칙은 실제 수집 대상을 blackbox-exporter 주소로 바꿉니다. 결과적으로 Prometheus는 http://localhost:9115/probe?target=https://api.example.com/health&module=http_2xx 같은 URL을 호출합니다.

동적 서비스 디스커버리 static_configs는 서버 목록을 직접 나열하는 방식입니다. 하지만 서버가 자주 추가되거나 삭제되는 환경에서는 불편합니다.

이럴 때는 서비스 디스커버리를 사용합니다. Prometheus는 Kubernetes, Consul, AWS EC2 등 다양한 플랫폼의 서비스 디스커버리를 지원합니다.

예를 들어 Kubernetes 환경에서는 다음과 같이 설정할 수 있습니다: yaml - job_name: 'kubernetes-nodes' kubernetes_sd_configs: - role: node 이렇게 하면 Kubernetes 클러스터의 모든 노드를 자동으로 발견하여 수집합니다. 노드가 추가되거나 삭제되어도 설정 파일을 수정할 필요가 없습니다.

설정 검증의 중요성 설정 파일을 잘못 작성하면 Prometheus가 시작되지 않습니다. 다행히 promtool이라는 도구로 미리 검증할 수 있습니다.

위의 코드에서 promtool check config prometheus.yml 명령어를 실행하면 문법 오류를 찾아줍니다. 운영 서버에 적용하기 전에 반드시 검증하는 습관을 들이세요.

실무 활용 사례 실제 현업에서는 어떻게 활용할까요? 어느 회사에서 여러 지역에 서버를 운영하고 있었습니다.

각 서버에 region 라벨을 붙여서 서울, 도쿄, 싱가포르를 구분했습니다. 어느 날 싱가포르 리전에서 네트워크 지연이 발생했는데, region="singapore"로 필터링하여 즉시 원인을 파악할 수 있었습니다.

또 다른 사례로, 마이크로서비스 아키텍처에서 각 서비스마다 job을 분리했습니다. user-service, order-service, payment-service 등으로 구분하여 각 서비스의 건강 상태를 독립적으로 모니터링했습니다.

주의사항 하지만 주의할 점도 있습니다. 초보 개발자들이 흔히 하는 실수 중 하나는 라벨을 과도하게 사용하는 것입니다.

라벨마다 별도의 시계열 데이터가 생성되므로, 불필요한 라벨을 많이 붙이면 저장 공간과 메모리가 급증합니다. 카디널리티가 높은 값(사용자 ID, 요청 ID 등)은 라벨로 사용하지 마세요.

또 다른 실수는 scrape_interval을 너무 짧게 설정하는 것입니다. 초 단위로 수집하면 Prometheus와 Exporter 모두에 부하가 걸립니다.

15초면 대부분의 경우 충분합니다. 정리 김개발 씨는 scrape_configs를 설정하고 Prometheus를 재시작했습니다.

드디어 대시보드에 지표가 나타나기 시작했습니다. "드디어 작동하네요!" scrape_configs를 제대로 이해하면 다양한 소스에서 지표를 수집하고 적절하게 라벨링할 수 있습니다.

다음 단계에서는 지표 이름을 어떻게 짓는지 알아보겠습니다.

실전 팁

💡 - 라벨은 필요한 것만 사용하여 카디널리티를 낮게 유지하세요

• promtool로 설정 파일을 검증한 후 적용하세요
• 서비스 디스커버리를 활용하면 동적 환경에서 편리합니다

---

6. 메트릭 네이밍 컨벤션

모든 설정을 마친 김개발 씨는 PromQL로 쿼리를 작성하려다가 막혔습니다. "node_cpu_seconds_total이랑 node_cpu_usage는 뭐가 다르죠?" 박시니어 씨가 설명했습니다.

"Prometheus에는 메트릭 이름을 짓는 규칙이 있어요. 이걸 알아야 나중에 헷갈리지 않죠."

메트릭 네이밍 컨벤션은 Prometheus 생태계에서 지표 이름을 일관성 있게 짓기 위한 규칙입니다. 이름만 봐도 무엇을 측정하는지, 단위는 무엇인지 알 수 있도록 명명합니다.

접두사로 애플리케이션이나 서비스를 나타내고, 기본 단위를 사용하며, suffix로 측정 방식을 표현합니다. 예를 들어 _total은 누적 카운터, _seconds는 시간 단위를 의미합니다.

올바른 네이밍을 사용하면 쿼리 작성이 쉬워지고 다른 개발자도 이해하기 쉽습니다.

다음 코드를 살펴봅시다.

# 좋은 메트릭 이름 예시

# Counter: 누적 값, _total suffix 사용
http_requests_total{method="GET", status="200"}  # HTTP 요청 총 개수
http_request_errors_total{method="POST"}  # HTTP 오류 총 개수

# Gauge: 현재 값, suffix 없음
node_memory_MemAvailable_bytes  # 사용 가능한 메모리 (bytes)
temperature_celsius  # 온도 (섭씨)
cpu_usage_ratio  # CPU 사용률 (0.0~1.0)

# Histogram: 분포 측정, _bucket, _sum, _count가 자동 생성됨
http_request_duration_seconds  # HTTP 요청 소요 시간
# 자동 생성:
#   http_request_duration_seconds_bucket{le="0.1"}
#   http_request_duration_seconds_bucket{le="0.5"}
#   http_request_duration_seconds_sum
#   http_request_duration_seconds_count

# Summary: 분위수 측정
http_request_duration_seconds{quantile="0.95"}  # 95 percentile

# 나쁜 예시 (피해야 할 패턴)
httpRequestsTotal  # 카멜케이스 대신 스네이크 케이스 사용
request_time_ms  # 밀리초 대신 기본 단위(초) 사용해야 함
memoryUsagePercent  # 퍼센트 대신 ratio(0.0~1.0) 사용해야 함

박시니어 씨가 화이트보드에 그림을 그리며 설명했습니다. "메트릭 이름을 막 지으면 나중에 정말 헷갈려요.

규칙을 알아야 합니다." 왜 네이밍 컨벤션이 중요할까요? Prometheus를 사용하는 회사가 수천 개의 지표를 수집한다고 상상해봅시다. 각 개발자가 제멋대로 이름을 짓는다면 어떻게 될까요?

어떤 사람은 requestCount라고 짓고, 다른 사람은 request_total이라고 짓고, 또 다른 사람은 total_requests라고 짓습니다. 시간 단위도 제각각입니다.

어떤 건 밀리초, 어떤 건 초, 어떤 건 마이크로초입니다. 나중에 대시보드를 만들거나 알림 규칙을 작성할 때 매번 "이 지표는 어떤 단위였지?" 하고 확인해야 합니다.

바로 이런 혼란을 방지하기 위해 네이밍 컨벤션이 필요합니다. 이름만 봐도 무엇을 측정하는지, 단위는 무엇인지 즉시 알 수 있습니다.

기본 규칙: 스네이크 케이스 Prometheus는 스네이크 케이스를 사용합니다. 카멜케이스(httpRequestsTotal)나 파스칼케이스(HttpRequestsTotal)가 아니라, 모두 소문자로 쓰고 단어 사이를 밑줄로 연결합니다.

http_requests_total처럼 말이죠. 이유는 간단합니다.

PromQL에서 쿼리할 때 대소문자를 구분하므로, 모두 소문자로 통일하면 실수가 줄어듭니다. 접두사: 애플리케이션 식별 메트릭 이름의 첫 부분은 보통 애플리케이션이나 서비스를 나타냅니다.

node_로 시작하면 node-exporter가 수집한 지표입니다. http_로 시작하면 HTTP 관련 지표입니다.

myapp_으로 시작하면 myapp이라는 애플리케이션의 커스텀 지표입니다. 이렇게 하면 지표가 어디서 왔는지 한눈에 알 수 있습니다.

예를 들어 prometheus_라는 접두사는 Prometheus 자신의 내부 지표를 나타냅니다. 기본 단위 사용 Prometheus는 기본 단위를 권장합니다.

시간은 **초(seconds)**를 사용합니다. 밀리초나 마이크로초가 아닙니다.

따라서 http_request_duration_seconds처럼 _seconds suffix를 붙입니다. 값이 0.001이면 1밀리초를 의미합니다.

용량은 **바이트(bytes)**를 사용합니다. 킬로바이트나 메가바이트가 아닙니다.

node_memory_MemAvailable_bytes처럼 _bytes suffix를 붙입니다. 비율은 0.0~1.0을 사용합니다.

퍼센트(0~100)가 아닙니다. cpu_usage_ratio처럼 _ratio suffix를 붙입니다.

0.85는 85%를 의미합니다. 메트릭 타입별 Suffix Prometheus에는 네 가지 메트릭 타입이 있습니다.

Counter는 누적 값입니다. 절대 감소하지 않고 계속 증가합니다.

예를 들어 HTTP 요청 총 개수는 계속 늘어납니다. Counter는 반드시 _total suffix를 붙입니다.

http_requests_total처럼 말이죠. Gauge는 현재 값입니다.

증가할 수도 있고 감소할 수도 있습니다. 예를 들어 현재 메모리 사용량, 현재 온도, 현재 연결된 클라이언트 수 등입니다.

Gauge는 특별한 suffix가 없습니다. Histogram은 값의 분포를 측정합니다.

예를 들어 HTTP 요청 소요 시간의 분포를 알고 싶을 때 사용합니다. Histogram은 자동으로 _bucket, _sum, _count suffix가 붙은 지표를 생성합니다.

Summary는 분위수를 측정합니다. 95 percentile 같은 값을 계산할 때 사용합니다.

좋은 예시 분석 위의 코드에서 좋은 예시를 살펴봅시다. http_requests_total{method="GET", status="200"}은 완벽한 이름입니다.

http_ 접두사로 HTTP 관련 지표임을 알 수 있고, _total suffix로 Counter임을 알 수 있습니다. 라벨로 method와 status를 구분하여 세부적으로 분석할 수 있습니다.

node_memory_MemAvailable_bytes는 단위가 명확합니다. _bytes suffix 덕분에 값이 바이트 단위임을 즉시 알 수 있습니다.

1073741824라는 값을 보면 약 1GB임을 계산할 수 있습니다. http_request_duration_seconds는 Histogram 타입입니다.

이름만 봐도 HTTP 요청 소요 시간을 초 단위로 측정한다는 걸 알 수 있습니다. 나쁜 예시 분석 이제 나쁜 예시를 살펴봅시다.

httpRequestsTotal은 카멜케이스를 사용했습니다. Prometheus 컨벤션에 맞지 않습니다.

http_requests_total이 올바릅니다. request_time_ms는 밀리초 단위를 사용했습니다.

기본 단위인 초를 사용해야 합니다. request_time_seconds로 바꾸고 값을 0.001 같은 형태로 저장해야 합니다.

memoryUsagePercent는 퍼센트 단위를 사용했습니다. 0.0~1.0 범위의 ratio를 사용해야 합니다.

memory_usage_ratio로 바꾸고 값을 0.85 같은 형태로 저장해야 합니다. 실무 활용 사례 실제 현업에서는 어떻게 활용할까요?

어느 회사에서 새로운 개발자가 myapp_request_count_total이라는 지표를 만들었습니다. 코드 리뷰에서 선배가 지적했습니다.

"count와 total이 중복이에요. myapp_requests_total로 바꾸세요." 이처럼 네이밍 컨벤션은 코드 리뷰에서 일관성을 유지하는 데 도움이 됩니다.

또 다른 사례로, 여러 팀이 협업하는 대규모 프로젝트에서 메트릭 네이밍 가이드를 문서화했습니다. 새로운 지표를 추가할 때마다 이 가이드를 참고하여 일관된 이름을 사용했고, 결과적으로 수천 개의 지표가 체계적으로 관리되었습니다.

PromQL에서의 활용 올바른 네이밍은 PromQL 쿼리를 작성할 때 빛을 발합니다. 예를 들어 초당 HTTP 요청 수를 계산하려면: rate(http_requests_total[5m]) _total suffix 덕분에 이것이 Counter임을 알 수 있고, rate() 함수를 사용해야 함을 직감할 수 있습니다.

만약 이름이 http_requests였다면 Counter인지 Gauge인지 헷갈렸을 것입니다. 주의사항 하지만 주의할 점도 있습니다.

초보 개발자들이 흔히 하는 실수 중 하나는 너무 긴 이름을 짓는 것입니다. api_gateway_user_service_http_request_duration_seconds_for_authenticated_users처럼 모든 정보를 이름에 담으려고 합니다.

이런 세부 정보는 라벨로 처리하는 것이 좋습니다. 또 다른 실수는 약어를 과도하게 사용하는 것입니다.

req, dur, auth 같은 약어는 작성자는 알아보지만 다른 사람은 헷갈립니다. request, duration, authentication처럼 풀어쓰는 것이 좋습니다.

정리 김개발 씨는 자신이 만든 커스텀 지표의 이름을 모두 수정했습니다. "이제 훨씬 깔끔하네요!" 박시니어 씨가 웃으며 말했습니다.

"좋아요. 이제 진짜 프로페셔널한 모니터링 시스템이 완성되었네요." 메트릭 네이밍 컨벤션을 제대로 이해하면 지표를 체계적으로 관리하고, 팀원과 협업할 때도 혼란이 없습니다.

이것으로 Prometheus 모니터링 지표 수집에 대한 기초를 모두 다뤘습니다.

실전 팁

💡 - 항상 스네이크 케이스를 사용하고 모두 소문자로 작성하세요

• Counter에는 _total, 시간에는 _seconds, 용량에는 _bytes suffix를 붙이세요
• 세부 정보는 이름 대신 라벨로 표현하여 이름을 간결하게 유지하세요

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!