mtail을 활용한 prometheus metric 생성

개요

서비스 로그를 활용한 Grafana 시각화를 목적으로, 서버에서 발생하는 서비스 로그를 파싱하여 유의미한 지표(Metric)를 추출하기 위해 mtail을 사용한다.

---

mtail 설치 방법

1. 릴리스 페이지 확인: 공식 GitHub 릴리스 페이지에서 자신의 운영체제와 아키텍처에 맞는 최신 버전을 확인한다.
2. 다운로드: wget이나 curl을 사용하여 바이너리를 다운로드한다.
   wget https://github.com/google/mtail/releases/download/v3.0.8/mtail_3.0.8_linux_amd64.tar.gz
3. 압축 해제: 다운로드한 파일의 압축을 해제한다.
   tar -xzvf mtail_3.0.8_linux_amd64.tar.gz
4. 실행 파일 이동: 압축 해제 후 생성된 mtail 바이너리 파일을 실행 경로(예: /usr/local/bin)로 이동시켜 시스템 어디서든 실행할 수 있도록 한다.
   sudo mv mtail /usr/local/bin/

---

로그 예시

파싱할 대상 로그는 아래와 같은 형식이라고 가정한다.

[2025-10-01 20:30:15] INFO: status=200, method=GET, path="/api/v1/users", response_time_ms=15
[2025-10-01 20:30:17] ERROR: status=500, method=POST, path="/api/v1/orders", response_time_ms=120

---

mtail config 설정

mtail은 .mtail 확장자를 가진 설정 파일을 사용하여 로그를 파싱할 규칙을 정의한다. 위 로그 예시를 바탕으로 HTTP 상태 코드별 요청 수를 집계하고, 평균 응답 시간을 계산하는 규칙을 작성한다.

test.mtail 생성:

# HTTP 요청 수 카운터
counter http_requests_total by status, method, path

/.*status=(\d+), method=(\w+), path="([^"]+)".*/ {
  http_requests_total[$1, $2, $3]++
}

메트릭 정의

counter http_requests_total by status, method, path

http_requests_total이라는 이름의 카운터(counter) 메트릭을 생성합니다. 이 메트릭은 status, method, path 세 가지 라벨(label)을 가지며, 이 라벨 조합에 따라 요청 수가 개별적으로 카운트.

정규 표현식

/.*status=(\d+), method=(\w+), path="([^"]+)".*/

로그 라인에서 status, method, path의 값을 추출하는 정규식입니다. 괄호 ( )로 감싸인 각 부분은 순서대로 캡처 그룹이 되어 $1, $2, $3 변수로 사용할 수 있다.

실행 블록

{ http_requests_total[$1, $2, $3]++ }

정규식 매칭에 성공하면, 캡처된 변수 $1, $2, $3를 라벨 값으로 사용하여 http_requests_total 메트릭의 카운터를 1 증가(++)시킨다.

---

mtail 실행

설정 파일 작성이 완료되면, mtail을 실행하여 로그 파일을 감시하도록 한다.

mtail -progs /etc/mtail -logs /var/log/service.log

• -progs: .mtail 설정 파일이 위치한 디렉터리를 지정한다. (/etc/mtail은 예시이므로 원하는 경로에서 가능)
• -logs: 감시할 로그 파일의 경로를 지정한다. 와일드카드(*) 사용도 가능하다.

mtail은 기본적으로 3903 포트에서 HTTP 서버를 열고 수집된 지표를 노출한다. curl http://localhost:3903/metrics 명령으로 지표가 정상적으로 노출되는지 확인할 수 있다.

$ curl http://localhost:3903/metrics | grep http_requests_total
# HELP http_requests_total defined at service.mtail:2:9-27
# TYPE http_requests_total counter
http_requests_total{method="GET",path="/api/v1/users",prog="service.mtail",status="200"} 1

---

prometheus.yml 설정

Prometheus가 mtail이 노출하는 지표를 주기적으로 수집(scrape)하도록 prometheus.yml 파일에 잡(job)을 추가한다.

# prometheus.yml

scrape_configs:
  - job_name: 'mtail-service'
    static_configs:
      - targets: ['<mtail_server>:3903']

• <mtail_server>: mtail이 실행 중인 서버의 호스트명이나 IP를 입력.

---

Prometheus 재기동 필요 여부

Prometheus의 설정을 변경한 후에는 이를 적용하기 위한 절차가 필요하다.

 

1. API를 통한 리로드: 아래의 curl 명령을 실행한다. (프로메테우스 설정에서 Lifecycle 옵션이 활성화 되어있어야 한다.)

curl -X POST http://<prometheus_ip>:9090/-/reload

 

2. 프로세스에 SIGHUP 신호 전송: Prometheus 프로세스 ID(PID)를 찾아 kill 명령으로 SIGHUP 신호를 보낸다. (서비스 중단 없이 설정 파일을 다시 로드하여 적용)

kill -SIGHUP <PID>
# 또는 
kill -1 <PID>