[Docker] Logging & Monitoring

배창민·2025년 12월 2일

TIL docker 한화시스템 BEYOND SW 캠프

한화시스템 BEYOND SW 캠프_20기

목록 보기

112/133

ELK, Prometheus, Grafana로 이해하는 로깅 & 모니터링 기본기

Spring Boot 애플리케이션을 실제로 운영하려면 단순 로그 출력만으로는 부족하다.
로그를 모아서 검색하고, 성능과 장애 상황을 시계열로 추적하고, 대시보드로 한눈에 보고 싶다.

그 역할을 나눠서 담당하는 것이 바로 ELK(로그), Prometheus + Grafana(모니터링) 조합이다.

1. ELK 스택으로 로그 수집·검색·시각화

1-1. ELK란 무엇인가

ELK 스택은 다음 세 가지로 구성된 로그 수집·분석 도구 묶음이다.

Elasticsearch
JSON 기반 검색 엔진.
애플리케이션 로그를 문서 형태로 저장하고, 빠르게 검색·집계할 수 있게 해준다.
Logstash
로그 수집기.
파일, TCP, Kafka 등 다양한 입력에서 로그를 받아서 파싱·가공 후 Elasticsearch로 전달한다.
Kibana
Elasticsearch에 쌓인 데이터를 시각화하는 대시보드 도구.
검색, 필터링, 차트, 대시보드를 구성하는 데 사용한다.

즉, 한 줄로 정리하면:

애플리케이션 로그 → Logstash → Elasticsearch → Kibana로 시각화

1-2. 전체 구성 흐름

로그 흐름은 보통 이렇게 잡는다.

Spring Boot → Logstash → Elasticsearch → Kibana

Spring Boot
logback에서 JSON 형태로 로그를 찍어서 Logstash로 전송
Logstash
수신한 JSON 로그를 파싱하고, 인덱스 규칙에 맞게 Elasticsearch에 저장
Elasticsearch
날짜별 인덱스에 로그 저장 (order-service-YYYY.MM.dd 같은 패턴)
Kibana
저장된 로그를 검색, 필터링, 대시보드로 시각화

1-3. Logstash 기본 설정 구조

예시 설정:

input {
  tcp {
    port => 5000
    codec => json
  }
}

output {
  elasticsearch {
    hosts => ["elasticsearch:9200"]
    index => "order-service-%{+YYYY.MM.dd}"
  }
}

정리:

input
- tcp
  - port => 5000 : Spring Boot가 로그를 보내는 포트
  - codec => json : 들어오는 로그가 JSON 형식이라는 뜻
output
- elasticsearch
  - hosts : Elasticsearch 주소 (도커라면 서비스 이름 사용 가능)
  - index : 저장할 인덱스 이름 패턴
    - "order-service-%{+YYYY.MM.dd}"
    - 날짜 기준으로 매일 새로운 인덱스 생성
    - 예: order-service-2025.12.02

1-4. Elasticsearch 기본 쿼리 예시

curl로 직접 쿼리할 수 있다.

기본 형태

curl -X GET "http://localhost:9200/<인덱스>/_search" \
  -H 'Content-Type: application/json' -d '
{
  "query": {
    ...
  }
}'

<인덱스>에 order-service-*처럼 패턴 사용 가능

1) 특정 로그 레벨 조회

curl -X GET "http://localhost:9200/order-service-*/_search" \
  -H 'Content-Type: application/json' -d '
{
  "query": {
    "match": {
      "level": "WARN"
    }
  }
}'

2) 메시지에 특정 단어 포함된 로그

curl -X GET "http://localhost:9200/order-service-*/_search" \
  -H 'Content-Type: application/json' -d '
{
  "query": {
    "match": {
      "message": "Order created"
    }
  }
}'

3) 최근 1시간 로그만 조회

curl -X GET "http://localhost:9200/order-service-*/_search" \
  -H 'Content-Type: application/json' -d '
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "now-1h",
        "lte": "now"
      }
    }
  }
}'

4) 복합 조건 (레벨 + 메시지)

curl -X GET "http://localhost:9200/order-service-*/_search" \
  -H 'Content-Type: application/json' -d '
{
  "query": {
    "bool": {
      "must": [
        { "match": { "level": "INFO" } },
        { "match": { "message": "Order list" } }
      ]
    }
  }
}'

5) 결과 개수 제한

curl -X GET "http://localhost:9200/order-service-*/_search" \
  -H 'Content-Type: application/json' -d '
{
  "size": 3,
  "query": {
    "match_all": {}
  }
}'

1-5. Kibana 인덱스 패턴 등록

Kibana에서 Elasticsearch 인덱스를 바라보게 설정해야 Discover에서 로그를 볼 수 있다.

브라우저에서 http://localhost:5601 접속
좌측 메뉴에서 Discover 선택
Create index pattern 클릭
인덱스 패턴 입력: order-service-*
Time field로 @timestamp 선택
생성 후 Discover로 돌아가서 로그 검색

인덱스가 안 보이면 Elasticsearch 인덱스 목록을 확인한다.

curl http://localhost:9200/_cat/indices?v

2. Monitoring 개념 정리

운영 환경에서는 단순히 “로그만 보는 것”으로는 모자라다.

장애 발생 시 빠르게 파악하고 알림을 받아야 하고
CPU, 메모리, 요청 수, 에러율 같은 지표들을 시간 흐름에 따라 보고 싶고
여러 서비스가 얽힌 복잡한 구조를 한눈에 모니터링하고 싶다

그래서 보통 모니터링 시스템을 이렇게 나눈다.

수집
- 애플리케이션, 서버, DB, 네트워크에서 지표·로그 수집
통합
- 하나의 스토리지(시계열 DB 등)에 모아서 저장
시각화
- 대시보드, 그래프, 차트, 알림으로 보여주기

Prometheus와 Grafana는 이 모니터링 파이프라인에서

Prometheus → 수집 + 저장
Grafana → 시각화

역할을 맡는다.

3. Prometheus로 메트릭 수집

3-1. Prometheus 특징

Prometheus는 오픈 소스 모니터링 및 알림 도구다.

주요 특징:

시간 기반 메트릭 수집
CPU, 메모리, HTTP 요청 수, 응답 시간처럼 시간에 따라 변하는 값을 시계열 데이터로 저장
알림 기능
Alertmanager와 연동해서 특정 조건(에러율 증가 등)에서 알림 발송
전용 쿼리 언어 (PromQL)
원하는 메트릭을 조회·집계·변형하는 쿼리 언어 제공

Spring Boot와 연결할 때는 Actuator + Micrometer를 통해 메트릭을 노출하고,
Prometheus가 주기적으로 그 엔드포인트를 긁어 가는 구조다.

3-2. Spring Boot + Micrometer + Actuator

메트릭 흐름은 이렇게 보면 된다.

Spring Boot (Actuator + Micrometer)
          ↓
    /actuator/prometheus
          ↓
     Prometheus 스크래핑

Micrometer
- JVM 애플리케이션의 메트릭을 수집하는 추상화 라이브러리
- Prometheus뿐 아니라 여러 모니터링 시스템을 지원
Actuator
- Spring Boot에서 제공하는 운영용 엔드포인트 묶음
- /actuator/health, /actuator/metrics, /actuator/prometheus 등 노출
- Micrometer와 함께 사용할 때 /actuator/prometheus에서 Prometheus 형식으로 메트릭을 출력

예시로 /actuator/metrics에서 노출되는 메트릭 이름 일부:

{
  "names": [
    "application.ready.time",
    "disk.free",
    "hikaricp.connections",
    "http.server.requests",
    "jvm.memory.used",
    "logback.events",
    "process.cpu.usage",
    "system.cpu.count",
    "tomcat.sessions.active.current"
  ]
}

Prometheus는 이 메트릭들을 일정 주기로 가져가서, 과거 이력까지 포함해 저장하는 DB 역할을 한다.

3-3. Prometheus 설정 파일 설명

기본 설정 예시:

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'spring-boot'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['order-service:8080']

정리:

global.scrape_interval: 15s
- 기본 스크래핑 주기
- 15초마다 대상 서비스에 메트릭 요청
scrape_configs
- 어떤 대상(서비스)에서 어떤 경로로 메트릭을 수집할지 정의
job_name: 'spring-boot'
- 이 수집 작업의 이름.
  Grafana에서 메트릭 분류에 사용된다.
metrics_path: '/actuator/prometheus'
- Spring Boot Actuator가 Prometheus용 포맷으로 메트릭을 노출하는 경로
targets: ['order-service:8080']
- 메트릭을 가져올 대상 주소
- 도커 환경이라면 서비스 이름 + 포트로 접근

동작 순서:

Prometheus가 15초마다 http://order-service:8080/actuator/prometheus 요청
Spring Boot가 메트릭을 텍스트 형식으로 응답
Prometheus가 이 데이터를 시계열로 저장

3-4. Prometheus UI 사용법

접속 주소: http://localhost:9090

기본 흐름:

상단의 검색창에 메트릭 이름 입력 (자동완성 지원)
Execute 클릭
Table 탭 / Graph 탭에서 결과 확인

자주 보는 예시:

예시 PromQL	설명
`http_server_requests_seconds_count`	HTTP 요청 수
`jvm_memory_used_bytes`	JVM 메모리 사용량
`process_cpu_usage`	애플리케이션 CPU 사용률
`system_cpu_usage`	시스템 전체 CPU 사용률
`rate(http_server_requests_seconds_count[1m])`	최근 1분 간 초당 요청 수

Prometheus UI는 주로

메트릭 이름 탐색
쿼리 테스트
그래프 확인

용도로 쓰고, 실제 대시보드는 주로 Grafana에서 구성한다.

4. Grafana로 메트릭 시각화

4-1. Grafana 특징

Grafana는 데이터 시각화 및 대시보드 도구다.

특징:

다양한 데이터 소스 지원
- Prometheus, InfluxDB, MySQL, PostgreSQL, Elasticsearch 등
대시보드 구성
- 여러 패널(그래프, 테이블, 게이지 등)을 조합해서 화면 구성
알림
- 특정 조건을 만족할 때 슬랙, 이메일 등으로 알림 전송 가능

Prometheus와 함께 쓸 때는 보통 이렇게 생각하면 된다.

Prometheus = 메트릭 DB
Grafana = 그 DB를 예쁘게 보여주는 대시보드

4-2. Grafana 동작 원리

구성 흐름:

Spring Boot → Prometheus → Grafana

Prometheus가 메트릭을 수집해서 시계열 데이터로 저장
Grafana가 Prometheus를 데이터 소스로 등록
Grafana 대시보드에서 PromQL 쿼리를 날려 그래프/차트로 시각화

4-3. Grafana 데이터 소스 설정 (datasource.yml)

프로비저닝을 사용하면 Grafana가 시작될 때 자동으로 데이터 소스를 등록할 수 있다.

apiVersion: 1

datasources:
  - name: Prometheus
    type: prometheus
    access: proxy
    url: http://prometheus:9090
    isDefault: true

필드 설명:

name
- Grafana UI에서 보여질 데이터 소스 이름
type: prometheus
- 데이터 소스 타입
access: proxy
- Grafana 서버가 직접 Prometheus에 HTTP 요청
url: http://prometheus:9090
- Prometheus 주소 (도커 환경이면 서비스 이름 기준)
isDefault: true
- 기본 데이터 소스로 설정 (패널 만들 때 기본 선택)

4-4. Grafana UI 사용법

접속 주소: http://localhost:3000
기본 계정: admin / admin (최초 로그인 시 비밀번호 변경)

1) 데이터 소스 확인

왼쪽 사이드바에서 설정 메뉴(톱니바퀴 아이콘) 선택
Data Sources 메뉴 진입
Prometheus 데이터 소스 존재 여부 확인
들어가서 Save & test 버튼으로 연결 확인

2) 대시보드 생성

상단 또는 사이드바에서 Dashboards → New → New dashboard 선택
Add new panel 클릭
Query 영역에서 PromQL 입력
예: rate(http_server_requests_seconds_count[1m])
Run query로 그래프 확인
패널 옵션으로 제목, 범례, 축 단위 등 설정
Apply → 대시보드 저장

이렇게 한두 개 패널만 만들어도

HTTP 요청 수 추이
응답 시간 변화
CPU/메모리 사용량

같은 기본 모니터링 대시보드를 빠르게 구성할 수 있다.

마무리 정리

ELK
- 로그 수집(Logstash) → 저장·검색(Elasticsearch) → 시각화(Kibana)
Prometheus
- Spring Boot Actuator + Micrometer를 통해 메트릭 수집
- 시계열 DB처럼 메트릭 이력을 관리
Grafana
- Prometheus를 데이터 소스로 등록
- 대시보드, 차트, 알림으로 모니터링 환경 구성

운영 환경을 준비할 때

로그는 ELK로
메트릭은 Prometheus + Grafana로

나눠서 설계하면 구조가 훨씬 깔끔해지고, 장애 대응과 성능 분석도 훨씬 수월해진다.

배창민

개발자 희망자

이전 포스트

BEYOND SW 캠프 20기 11월 회고록

다음 포스트