QB Configuration 빌드 통계, Grafana 대시보드

QuickBuild 로그는 보통 텍스트 파일 형태이므로, Grafana가 직접 읽을 수 없다. 따라서 중간에 로그를 수집하고 저장하는 시스템이 필요. 가장 인기 있고 Grafana와 궁합이 잘 맞는 조합은 Loki와 Promtail.

전체 프로세스 아키텍처

1. QuickBuild 서버: configuration.log 파일을 생성.
2. Promtail (로그 수집기): QuickBuild 서버에서 로그 파일을 읽어와 파싱(Parsing)한 후 Loki로 전송.
3. Loki (로그 저장소): Promtail로부터 받은 로그를 저장하고, Grafana가 쿼리할 수 있도록 API를 제공.
4. Grafana (시각화 도구): Loki를 데이터 소스로 연결하여, LogQL이라는 쿼리 언어를 사용해 데이터를 조회하고 대시보드로 시각화.

1단계: 필요 시스템 설치 (Loki & Promtail)

먼저 Grafana, Loki, Promtail을 설치. Docker를 사용하면 가장 간편하게 설치할 수 있다.

아래는 docker-compose.yml 예시. 이 파일을 원하는 디렉토리에 생성하세요.

version: "3.8"

services:
  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    networks:
      - loki

  loki:
    image: grafana/loki:latest
    container_name: loki
    ports:
      - "3100:3100"
    command: -config.file=/etc/loki/local-config.yaml
    networks:
      - loki

  promtail:
    image: grafana/promtail:latest
    container_name: promtail
    volumes:
      - ./promtail-config.yml:/etc/promtail/config.yml
      # QuickBuild 로그가 있는 디렉토리를 볼륨으로 마운트합니다.
      # Docker를 QuickBuild 서버와 다른 곳에서 실행한다면, 로그를 이쪽으로 복사하거나 다른 수집 방식을 사용해야 합니다.
      - /path/to/quickbuild/logs:/var/logs/quickbuild 
    command: -config.file=/etc/promtail/config.yml
    networks:
      - loki

networks:
  loki:

volumes:
  grafana-data:

설명:

• /path/to/quickbuild/logs: 실제 QuickBuild 로그가 저장된 경로로 변경. (예: /opt/quickbuild/logs)
• promtail-config.yml: Promtail이 어떻게 로그를 수집하고 Loki로 보낼지 정의하는 설정 파일. 이 파일을 docker-compose.yml과 같은 위치에 생성.

2단계: Promtail 설정 (로그 수집 및 파싱)

이제 promtail-config.yml 파일을 작성하여 QuickBuild 로그를 수집하고 파싱하도록 설정. QuickBuild 로그는 보통 정형화되지 않은 텍스트이므로, **정규표현식(regex)**을 사용해 의미 있는 데이터를 추출하는 것이 중요.

promtail-config.yml 예시:

server:
  http_listen_port: 9080
  grpc_listen_port: 0

positions:
  filename: /tmp/positions.yaml

clients:
  - url: http://loki:3100/loki/api/v1/push

scrape_configs:
- job_name: quickbuild
  static_configs:
  - targets:
      - localhost
    labels:
      job: quickbuild_config
      __path__: /var/logs/quickbuild/configuration.log # Docker 컨테이너 내부 경로

  # 파이프라인: 로그를 파싱하여 라벨을 추출하는 단계
  pipeline_stages:
  # 1. 정규표현식으로 빌드 상태, 설정 경로, 소요 시간 등을 추출
  - regex:
      # 예시: "2023-10-27 15:30:00,123 [master>root/my-project/main-build] INFO  build.BuildManager - Build '12345' is FINISHED (SUCCESS) in 120 seconds"
      expression: '^(?P<timestamp>\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d{3}) \[(?P<config_path>[^\]]+)\]\s+\w+\s+build\.BuildManager - Build ''(?P<build_id>\d+)'' is FINISHED \((?P<status>\w+)\) in (?P<duration_sec>\d+) seconds'
      
  # 2. 추출한 데이터를 라벨로 설정
  - labels:
      config_path:
      status:
  
  # 3. 로그 메시지에서 타임스탬프를 사용
  - timestamp:
      source: timestamp
      format: '2006-01-02 15:04:05,000'

  # 만약 위 정규식이 맞지 않는 로그가 많다면, 다른 파서(json, logfmt 등)를 추가하거나 정규식을 더 정교하게 만들어야 합니다.

 

설정 설명:

• __path__: Promtail이 읽을 로그 파일의 경로.
• pipeline_stages: 로그를 처리하는 과정.
  • regex: 정규표현식을 사용해 로그 한 줄에서 원하는 정보를 그룹으로 추출 (< > 안의 이름).
  • labels: regex에서 추출한 config_path, status 등을 Loki의 검색 가능한 라벨로 만든다. 라벨은 검색 성능에 중요.
  • timestamp: 로그에 기록된 시간을 실제 로그 시간으로 사용하도록 설정.

이제 터미널에서 docker-compose up -d 명령을 실행하여 Grafana, Loki, Promtail을 실행.

3단계: Grafana에서 Loki 데이터 소스 추가

1. 웹 브라우저에서 http://localhost:3000 으로 접속하여 Grafana에 로그인. (기본 ID/PW: admin/admin)
2. 왼쪽 메뉴에서 톱니바퀴 아이콘 (Configuration) > Data Sources로 이동.
3. Add data source 버튼을 클릭하고 Loki를 선택.
4. Settings 섹션에서 HTTP URL에 http://loki:3100을 입력. (Docker Compose 네트워크를 사용하므로 서비스 이름으로 접근 가능)
5. Save & test 버튼을 클릭하여 "Data source is working" 메시지가 나오는지 확인.

4단계: Grafana 대시보드 만들기

1. 왼쪽 메뉴에서 플러스 아이콘 (+) > Dashboard를 클릭.
2. Add new panel을 선택.

예제 1: 빌드 성공/실패 횟수 (Stat 패널)

특정 기간 동안의 전체 빌드 성공 및 실패 횟수를 표시.

• 패널 타입: 오른쪽에서 Stat 선택
• 쿼리:Generated logql

  // 성공 횟수
  count_over_time({job="quickbuild_config", status="SUCCESS"}[$__interval])

  // 실패 횟수
  count_over_time({job="quickbuild_config", status="FAILED"}[$__interval])

   
• 설정:
  • Query 탭에서 위 쿼리를 각각 입력.
  • Legend에 {{status}} 라고 입력하면 각 통계에 'SUCCESS', 'FAILED' 이름 표시.
  • 오른쪽 Panel options에서 Text mode를 Auto로, Color mode를 Background로 설정하면 상태에 따라 색상이 바뀐다.

예제 2: 설정별 빌드 횟수 (Bar chart 또는 Pie chart)

어떤 설정(Configuration)이 가장 많이 빌드되었는지 확인.

• 패널 타입: Bar chart 또는 Pie chart
• 쿼리:Generated logql

  // 설정 경로(config_path)를 기준으로 그룹화하여 빌드 횟수를 합산
  sum by (config_path) (count_over_time({job="quickbuild_config"}[$__range]))

   
• 설정:
  • Bar chart의 경우 Orientation을 Horizontal로 하면 보기 편하다.
  • Pie chart의 경우 Value 옵션을 All values로 설정.

예제 3: 평균 빌드 시간 (Time series 또는 Stat)

시간에 따른 평균 빌드 시간의 변화를 추적.

• 패널 타입: Time series
• 쿼리:Generated logql

  // 먼저 로그 라인을 파싱하여 duration_sec 필드를 숫자로 만듭니다.
  // 그 다음 시간 경과에 따른 평균을 계산합니다.
  avg_over_time({job="quickbuild_config"} | logfmt | unwrap duration_sec [$__interval])

   
  • logfmt 또는 json 파서가 필요할 수 있다. Promtail에서 정규식으로 파싱했다면 unwrap만으로 충분할 수 있다. unwrap은 라벨이 아닌 로그 라인에서 숫자 값을 추출.
  • 만약 Promtail에서 duration_sec을 라벨로 만들었다면, avg_over_time({job="quickbuild_config"} | unwrap label_value(duration_sec))[$__interval]와 같이 사용.

예제 4: 최근 실패한 빌드 로그 (Logs 패널)

실패한 빌드의 원본 로그를 바로 확인할 수 있다.

• 패널 타입: Logs
• 쿼리:Generated logql

  {job="quickbuild_config", status="FAILED"}

   
• 설정:
  • Show time 옵션을 켜면 로그 시간을 볼 수 있다.
  • Wrap lines를 켜면 긴 로그를 보기 편하다.

추가 팁

• 변수(Variables) 사용: 대시보드 상단에 config_path를 선택할 수 있는 드롭다운 메뉴를 만들 수 있다. Dashboard settings > Variables에서 Query 타입 변수를 만들고, 쿼리에 label_values({job="quickbuild_config"}, config_path)를 입력하면 된다.
• 알림(Alerting): 특정 조건(예: 5분 내 실패 횟수 3회 이상)을 만족하면 알림을 받도록 설정할 수 있습니다. Grafana Alerting 기능을 활용해 보세요.
• 정규식: QuickBuild 로그 형식이 위 예시와 다를 수 있습니다. 실제 로그에 맞게 promtail-config.yml의 regex를 수정하는 것이 가장 중요. Regex101 같은 사이트에서 테스트하며 작성.