모니터링 & 메트릭
모니터링 & 메트릭 (Monitoring and Metrics)
Apache Pinot의 모니터링과 메트릭에 관한 레퍼런스 문서예요.
출처: 문서
본문
Apache Pinot은 각 구성 요소(Controller, Broker, Server)에서 다양한 메트릭을 수집해 JVM 기반 메트릭 시스템(Micrometer + Micrometer registry)을 통해 노출해요. 이를 통해 클러스터 상태를 모니터링하고 문제를 진단할 수 있어요.
메트릭 프레임워크 (Metrics framework)
Pinot은 메트릭 수집/노출에 Micrometer를 사용해요. 메트릭 이름은 구성 요소와 계층 구조를 반영하는 형식을 따르며, 서로 다른 Micrometer registry를 바인딩해 Prometheus, JMX 등으로 내보낼 수 있어요.
주요 내보내기 방식:
- JMX: MBeans를 통해 노출.
- Prometheus: Micrometer Prometheus registry로
/metrics엔드포인트 등에서 스크랩. - CloudWatch: AWS용 reporter.
메트릭을 활성화하려면 필요한 Micrometer registry 구현(prometheus, jmx 등)을 클래스패스에 추가하고, pinot.*.metrics 관련 구성을 설정해요.
Controller 메트릭
Controller는 테이블과 세그먼트 관리 상태를 메트릭으로 노출해요. 주요 메트릭은 다음과 같아요.
| 메트릭 | 설명 |
|---|---|
| numberOfTables | 클러스터의 테이블 수. |
| numberOfRealtimeSegments | 실시간 세그먼트 수. |
| numberOfOfflineSegments | 오프라인 세그먼트 수. |
| tableStatus | 테이블 상태(Ideal State vs External View 반영). |
| averageTableSize | 테이블 평균 크기. |
| percentOfReplicas | 복제본 달성 퍼센트. |
| controllerLeader | 이 broker/테이블에 대해 controller가 leader인지 여부. |
| errors | Controller에서 발생한 오류 수(예: segmentCountMismatchError, tablePruningFailedError). |
| minion | Minion 작업 상태 메트릭. |
Broker 메트릭
Broker는 쿼리 처리와 라우팅 상태를 메트릭으로 노출해요.
| 메트릭 | 설명 |
|---|---|
| QUERY_TIME (queryTimeMs) | 쿼리 처리 시간. |
| QUERY_REQUEST_SIZE / QUERY_RESPONSE_SIZE | 쿼리 요청/응답 크기. |
| REQUEST_EXCEPTIONS | 요청 중 발생한 예외. |
| BROKER_QUERY_QUOTA_EXCEEDED (queryQuotaExceeded) | 쿼리 할당량 초과로 인한 429 상태. |
| QUERY_BY_TABLE | 테이블별 쿼리 수. |
| SERVER_BROKEN_RESPONSES | 응답하지 못한 서버 수. |
| FAILURE_DETECTOR_* | 장애 감지기 상태 메트릭. |
| ADAPTIVE_ROUTING_* | adaptive 라우팅 게이지. |
| STARTUP_WARMUP_* | 시작 워밍업 상태. |
| NETTY_CONNECTION_* | Netty 연결 관련 게이지. |
Server 메트릭
Server는 세그먼트와 쿼리 실행 및 수집 상태를 메트릭으로 노출해요.
| 메트릭 | 설명 |
|---|---|
| EXECUTION_TIME (queryExecutionTime) | 쿼리 실행 시간. |
| TOTAL_DOCS / DOCS_SCANNED | 스캔된 문서 수. |
| ENTRIES_SCANNED | 스캔된 엔트리 수. |
| NUM_SEGMENTS_QUERIED / NUM_SEGMENTS_PROCESSED | 쿼리된/처리된 세그먼트 수. |
| NETTY_CONNECTION_* | Netty 연결 수/상태. |
| REALTIME_INGESTION_OFFSET_LAG | 실시간 수집 오프셋 지연. |
| REALTIME_INGESTION_FRESHNESS_LAG | 실시간 수집 freshiness 지연. |
| CONSUMPTION_RATE_LIMIT | 소비 속도 제한 상태 게이지. |
| SEGMENT_* | 세그먼트 로딩/삭제/오류 관련 메트릭. |
| OPEN_STRUCT_LAST_SEGMENT_KEY_DOC_COUNT | OPEN_STRUCT dense 키 문서 수 게이지. |
구성 (Configuration)
메트릭 리포터/레지스트리 관련 주요 구성:
pinot.broker.metrics.*,pinot.server.metrics.*,pinot.controller.metrics.*— 구성 요소별 메트릭 설정.- 메트릭 exporter 선택과 내보내기 간격을 설정해 특정 metrics backend로 전송할 수 있어요.
Prometheus 등으로 내보내려면 해당 registry 의존성을 추가하고 exporter 구성을 설정하세요.