이번 커밋에서는 Promtail 로그 수집 설정을 리팩토링하여 LearningCollector의 로그를 더 효율적으로 파싱하고 수집할 수 있도록 개선했습니다.

monitoring: Promtail 로그 수집 설정 리팩토링

이번 커밋에서는 Promtail 로그 수집 설정을 리팩토링하여 LearningCollector의 로그를 더 효율적으로 파싱하고 수집할 수 있도록 개선했습니다.

요약

주요 변경사항: Promtail 설정 파일 (config/promtail/config.yml)을 수정하여 LearningCollector 코드 실행 로그 수집 관련 설정을 리팩토링했습니다.
작업 날짜: 2026년 2월 8일
전체적인 맥락: 기존에는 LearningCollector의 로그를 단순 텍스트로 수집했지만, 이번 변경을 통해 JSON 형식의 로그를 파싱하여 level, event, component, api 등의 레이블을 추출하도록 개선했습니다.

배경 및 목적

기존 Promtail 설정에서 LearningCollector의 로그를 수집할 때, 로그 메시지를 단순 텍스트로만 인식하여 로그의 구조적인 정보를 활용하기 어려웠습니다. 특히, 로그 내에 포함된 level, event, component, api와 같은 중요한 메타데이터를 별도로 추출하고 관리하는 기능이 부족했습니다.

이번 작업의 목적은 다음과 같습니다.

LearningCollector에서 생성되는 JSON 형식의 로그를 Promtail이 올바르게 파싱하도록 설정합니다.
파싱된 로그에서 level, event, component, api와 같은 필드를 추출하여 Promtail 레이블로 활용합니다.
이를 통해 로그 검색, 필터링 및 분석의 효율성을 높여 시스템 모니터링 및 문제 해결 능력을 강화합니다.

구현 내용

이번 커밋의 핵심 변경사항은 config/promtail/config.yml 파일의 LearningCollector_logs job 설정입니다.

주요 변경사항 상세 설명:
- 기존의 pipeline_stages 설정이 json 파싱 및 labels 적용 단계를 그대로 유지하면서, JSON 로그의 특정 필드를 expressions로 명시하여 추출하도록 개선되었습니다.
- pipeline_stages 내에 json 스테이지에서 level, event, component, api 필드를 추출하는 expressions가 추가되었습니다.
- 이어서 labels 스테이지에서 추출된 level, event, component, api를 Promtail 레이블로 설정하도록 구성되었습니다.
변경된 파일 목록:
- config/promtail/config.yml
추가/삭제된 코드 라인 수:
- 총 추가 라인: 21
- 총 삭제 라인: 20
- (순수 설정 파일 수정이므로 코드 라인 수보다는 설정 변경 내용이 중요합니다.)
핵심 코드 설명:
Promtail 설정 파일의 LearningCollector_logs 섹션에서 pipeline_stages 부분이 다음과 같이 변경되었습니다.

# LearningCollector 코드 실행 로그 수집
- job_name: LearningCollector_logs
  static_configs:
    - targets:
        - localhost
      labels:
        job: LearningCollector
        __path__: /app/LearningCollector/log/promtail_feed.jsonl

  pipeline_stages:
    - json:
        expressions:
          level:
          event:
          component:
          api:
    - labels:
        level:
        event:
        component:
        api:

위 설정은 /app/LearningCollector/log/promtail_feed.jsonl 경로의 로그 파일을 Promtail이 수집하도록 지시합니다. 수집된 로그가 JSON 형식일 경우, json 파싱 스테이지를 통해 level, event, component, api 키에 해당하는 값을 추출합니다. 이후 labels 스테이지에서 추출된 이 값들을 Promtail의 레이블로 사용하여 로그를 더욱 세분화할 수 있게 됩니다.

기술적 의사결정

이번 변경은 Promtail의 pipeline_stages 기능을 활용하기로 결정했습니다.

어떤 기술/라이브러리를 선택했는지: Promtail의 pipeline_stages 기능, 특히 json 및 labels 파이프라인 스테이지를 사용했습니다.
왜 그 선택을 했는지: LearningCollector의 로그가 JSON 형식으로 기록되고 있었기 때문에, Promtail이 이러한 구조화된 데이터를 직접 파싱하여 필요한 정보를 추출하고 레이블로 활용하는 것이 가장 효율적인 방법이라고 판단했습니다. pipeline_stages는 Promtail 자체적으로 제공하는 기능이므로 별도의 외부 라이브러리나 서비스를 추가할 필요 없이 설정을 통해 구현할 수 있다는 장점이 있습니다.
다른 대안과 비교:
- 별도의 파서/프로세서 사용: Fluentd, Logstash와 같은 별도의 로그 수집 및 처리 도구를 사용하여 Promtail로 전달하기 전에 로그를 파싱하는 방법도 고려할 수 있었습니다. 하지만 이 경우 시스템 복잡성이 증가하고, 별도의 서비스 운영 부담이 생기므로 Promtail 자체 기능으로 해결하는 것이 더 간결하다고 판단했습니다.
- 로그 포맷 변경: LearningCollector 애플리케이션 자체에서 로그 포맷을 변경하여 Promtail이 쉽게 파싱할 수 있도록 하는 방법도 가능합니다. 그러나 이는 애플리케이션 코드 수정이 필요하며, 이미 JSON 형식으로 기록되고 있는 로그를 활용하는 것이 더 직접적인 해결책이었습니다.
장단점 분석:
- 장점:
  - Promtail 자체 기능만으로 로그 파싱 및 레이블링 가능
  - 설정 변경만으로 구현 가능하여 간결함
  - 구조화된 로그 데이터를 활용한 강력한 필터링 및 분석 가능
- 단점:
  - Promtail의 pipeline_stages 기능에 대한 이해 필요
  - 복잡한 로그 파싱 시 설정이 다소 복잡해질 수 있음

배운 점 및 개선점

이번 작업을 통해 배운 점:
- Promtail의 pipeline_stages 기능이 로그 데이터를 구조화하고 레이블링하는 데 얼마나 강력한지 다시 한번 알게 되었습니다.
- JSON 형식 로그를 Promtail에서 효과적으로 파싱하기 위한 json 및 labels 스테이지의 활용법을 익혔습니다.
- 로그 수집 단계에서 메타데이터를 잘 활용하면 추후 로그 분석 및 모니터링 효율성이 크게 향상된다는 점을 체감했습니다.
앞으로 개선할 점:
- 이번에 추가된 level, event, component, api 레이블을 활용하여 Grafana 등에서 시각화 대시보드를 구축하고, 특정 이벤트나 API 호출에 대한 모니터링을 강화할 필요가 있습니다.
- LearningCollector에서 생성되는 다른 종류의 로그들도 유사한 방식으로 구조화하여 Promtail에서 관리할 수 있는지 검토해 볼 수 있습니다.
- Promtail 설정 파일의 가독성을 높이고, 향후 유지보수를 용이하게 하기 위한 표준화된 컨벤션을 적용하는 것을 고려할 수 있습니다.
다음 단계 계획:
- level 별 로그 발생 빈도 및 오류율 시각화
- 특정 component 또는 api 호출 시 발생한 event 기반 알림 설정
- Promtail 설정을 체계적으로 관리하기 위한 CI/CD 파이프라인 통합

참고 자료

Promtail Documentation - Pipeline Stages: https://grafana.com/docs/loki/latest/clients/promtail/pipelines/ (Promtail 공식 문서에서 파이프라인 스테이지 관련 내용을 참고했습니다.)