Prometheus를 활용한 LF Edge eKuiper 규칙 상태 모니터링

LF Edge eKuiper는 끊임없이 유입되는 데이터 스트림을 처리하는 규칙(Rule) 기반의 스트리밍 엔진입니다. 각 규칙은 독립적인 작업 단위로 실행되며, 운영 환경에서는 이러한 규칙들이 정상적으로 동작하고 있는지, 데이터 처리 지연이나 오류가 발생하지 않는지 실시간으로 감시하는 것이 매우 중요합니다. 이를 위해 eKuiper는 CNCF의 대표적인 모니터링 도구인 Prometheus와의 통합 기능을 제공합니다.

eKuiper 규칙 상태 데이터 분석

eKuiper 내에서 실행 중인 규칙의 지표는 기본적으로 REST API를 통해 확인할 수 있습니다. 예를 들어, sensor_analysis라는 이름의 규칙이 실행 중이라면 다음과 같은 명령어로 현재 상태를 조회할 수 있습니다.

curl -X GET "http://localhost:9081/rules/sensor_analysis/status"

이 API는 각 연산자(Operator)별 성능 지표를 포함한 JSON 데이터를 반환합니다. 다음은 SQL 쿼리 SELECT temperature FROM sensor_stream과 MQTT 전송 액션이 포함된 규칙의 상태 예시입니다.

{
  "status": "running",
  "source_sensor_stream_0_records_in_total": 1050,
  "source_sensor_stream_0_records_out_total": 1050,
  "source_sensor_stream_0_process_latency_us": 120,
  "source_sensor_stream_0_buffer_length": 0,
  "source_sensor_stream_0_exceptions_total": 0,
  "op_1_project_0_records_in_total": 1050,
  "op_1_project_0_records_out_total": 1050,
  "op_1_project_0_process_latency_us": 45,
  "sink_mqtt_0_0_records_in_total": 1050,
  "sink_mqtt_0_0_records_out_total": 1048,
  "sink_mqtt_0_0_exceptions_total": 2,
  "sink_mqtt_0_0_last_exception": "network timeout",
  "sink_mqtt_0_0_last_exception_time": 1672531200000
}

핵심 모니터링 지표 설명

각 연산자에서 공통적으로 수집되는 주요 지표는 다음과 같습니다.

records_in_total / records_out_total: 유입 및 처리 완료된 메시지 총량입니다. 두 값의 차이를 통해 데이터 유실 여부를 파악할 수 있습니다.
process_latency_us: 메시지 처리에 소요된 마이크로초(us) 단위의 시간입니다. 급격한 수치 상승은 성능 병목을 의미합니다.
buffer_length: 연산자 간 큐에 대기 중인 메시지 수입니다. 이 값이 지속적으로 증가한다면 다운스트림 처리 속도가 유입 속도를 따라가지 못하는 상황입니다.
exceptions_total: 규칙 실행 중 발생한 비치명적 오류(네트워크 순시 단절, 데이터 형식 오류 등)의 누적 횟수입니다.
last_exception / last_exception_time: 가장 최근에 발생한 오류 메시지와 발생 시각을 나타내어 디버깅을 돕습니다.

Prometheus 엔드포인트 활성화

eKuiper는 내장된 Prometheus 서버 기능을 통해 지표를 노출할 수 있습니다. 기본적으로는 비활성화되어 있으므로 설정 변경이 필요합니다.

설정 파일 수정

etc/kuiper.yaml 파일을 열어 Prometheus 관련 옵션을 수정합니다.

# etc/kuiper.yaml
basic:
  prometheus: true
  prometheusPort: 20499

Docker 환경 설정

컨테이너 환경에서 실행 중이라면 환경 변수를 통해 간편하게 활성화할 수 있습니다.

docker run -d \
  --name ekuiper_monitor \
  -p 9081:9081 \
  -p 20499:20499 \
  -e KUIPER__BASIC__PROMETHEUS=true \
  lfedge/ekuiper:latest

설정이 완료되면 http://localhost:20499/metrics 주소에서 Prometheus 포맷으로 구조화된 실시간 데이터를 확인할 수 있습니다.

Prometheus 서버 구성 및 시각화

이제 수집된 지표를 Prometheus 서버에서 가져가도록 설정해야 합니다. Prometheus 설치 디렉토리의 prometheus.yml 파일을 수정합니다.

scrape_configs:
  - job_name: 'ekuiper_metrics'
    scrape_interval: 10s
    static_configs:
      - targets: ['host.docker.internal:20499'] # eKuiper 실행 주소

Prometheus 서버를 재시작한 뒤 웹 UI(기본 포트 9090)에 접속하면 kuiper_sink_records_out_total과 같은 지표를 검색하고 차트화할 수 있습니다.

모니터링 활용 팁

단순한 수치 확인을 넘어 Prometheus의 rate() 함수를 사용하면 초당 데이터 처리량(TPS)을 계산할 수 있으며, sum() 함수를 통해 여러 규칙의 총 처리량을 합산하여 시스템 전체 부하를 모니터링할 수 있습니다. 이러한 데이터는 Grafana와 같은 대시보드 도구와 연동하여 더욱 직관적인 운영 관제 시스템을 구축하는 밑바탕이 됩니다.

태그: eKuiper prometheus Monitoring IoT DataStream

7월 30일 04:17에 게시됨

괴물 클럽