Broker 구성

Broker 구성

Apache Pinot Broker의 구성 속성 레퍼런스 문서예요.

출처: 문서

본문

공유 MSE 사서함 keep-alive 속성(pinot.query.runner.channel.keep.alive.* 및 pinot.query.runner.mailbox.server.permit.keep.alive.*)은 Mailbox channel keep-alive를 참고하세요.

broker 속성은 구성 파일에 설정할 수 있어요. 파일은 시작 시 다음과 같이 제공할 수 있어요:

bin/pinot-admin.sh StartBroker -configFileName /path/to/broker.conf

구성 파일의 중복 키 (Duplicate Keys)

Apache Pinot 1.3.0부터 구성 파일의 중복 키는 시작 시 ConfigurationException을 발생시켜요. 이전에는 중복 키가 목록으로 조용히 병합됐어요. 이 오류가 발생하면 각 구성 속성이 구성 파일에 한 번만 나타나는지 확인하세요. 예외에는 정확한 파일 경로, 중복 키 이름, 중복이 발견된 줄 번호가 포함돼요.

예시 오류:

ConfigurationException: Duplicate key found in /path/to/broker.conf at line 10 and line 15: pinot.broker.timeoutMs

broker.conf는 다음 속성을 가질 수 있어요. 모든 속성은 이 클래스에 정의돼 있어요.

Broker 구성 속성 테이블

라우팅 쿼리 수신 로그 (Routing query-received logs)

org.apache.pinot.broker.querylog.QueryLogger 로거는 전처리 SQL query for request ... 레코드와 통계가 포함된 쿼리 완료 레코드를 모두 방출해요. 전처리 레코드만 SLF4J 마커 QUERY_RECEIVED를 전달하므로 메시지 텍스트를 매칭하지 않고도 독립적으로 필터링하거나 라우팅할 수 있어요.

예를 들어 로그를 보내는 appender에 다음 Log4j2 필터를 추가해 query-received 레코드를 해당 대상에서 제외할 수 있어요:

<MarkerFilter marker="QUERY_RECEIVED" onMatch="DENY" onMismatch="NEUTRAL"/>

로컬 포렌식용으로 수신 레코드가 필요하면 필터링되지 않은 다른 대상을 유지하세요. 완료되지 않는 쿼리에는 완료 레코드가 없을 수 있어요. 마커를 추가해도 로깅이 비활성화되거나 메시지 텍스트가 바뀌지 않아요. pinot.broker.query.log.logBeforeProcessing은 기본적으로 true로 유지되며, false로 설정하면 수신 레코드를 아예 비활성화해요.

Broker 시작 pre-connect

Broker 시작 pre-connect는 첫 single-stage 쿼리에서 각 서버로 보내는 TCP 연결과(구성 시) TLS 핸드셰이크를 제거해요. Helix 수렴 후 broker는 라우팅 테이블의 모든 (server, table type) 쌍에 대해 하나의 Netty 채널을 열어요. broker는 pre-connect가 끝나거나 pinot.broker.startup.preconnect.timeoutMs에 도달할 때까지 STARTING 상태로 남아요.

Pre-connect는 기본적으로 활성화되며 best effort예요. 느리거나 사용 불가한 서버는 구성된 예산을 초과해도 시작을 막지 않으며, 준비되지 않은 채널은 기존 지연 연결 경로로 대체돼요. OFFLINE과 REALTIME 경로가 별도 채널을 사용하므로 두 유형을 모두 호스팅하는 서버는 두 연결을 받을 수 있어요.

구성된 타임아웃이 유일한 조기 해제 경계예요. Pre-connect는 시도된 모든 채널이 연결되었거나 실패하는 즉시 반환하고, 그렇지 않으면 마감까지 기다려요. 이 기능은 broker가 Netty single-stage 전송을 사용할 때만 적용돼요. broker-서버 gRPC 핸들러, multi-stage 엔진, 시계열 경로에는 채널을 워밍하지 않아요.

이전 동작(첫 쿼리가 각 채널을 설정)을 복원하려면:

pinot.broker.startup.preconnect.enabled=false

라우팅된 서버가 많거나 TLS 핸드셰이크가 느린 배포에서는 오케스트레이션 시스템이 허용하는 최대 시작 지연보다 낮게 유지하면서 예산을 늘리세요:

pinot.broker.startup.preconnect.enabled=true
pinot.broker.startup.preconnect.timeoutMs=60000

STARTUP_PRECONNECT_DURATION_MS로 시작 워밍업 시간을, NETTY_CONNECTION_CONNECT_LATENCY_MS로 개별 채널 연결 시간 분포를 모니터링하세요.

Broker 쿼리 서빙 경로 워밍업 (Broker query serve-path warmup)

Broker 쿼리 서빙 경로 워밍업은 HTTP readiness가 부여되기 전에 single-stage 컴파일, 라우트, scatter-gather, 역직렬화, 리듀스, 응답 직렬화 경로를 실행해 재시작 후 첫 트래픽 폭증 동안의 지연을 줄여요. 기본적으로 비활성화되어 있으며 시작 pre-connect를 보완해요.

활성화되면 broker는 Helix 수렴 후 먼저 로컬 컴파일과 응답 직렬화 작업을 수행한 다음 고정 SELECT * FROM "<table>" LIMIT 1 프로브를 발행하면서 STARTING 상태로 유지돼요. Pinot은 해당 broker에 보이는 모든 서버를 커버하는 결정적 라우팅 가능 테이블 집합을 선택해요. 합성 프로브는 액세스 제어, 쿼리 할당량, 고객 쿼리 로그, 일반 쿼리 메트릭을 우회해요.

워밍업은 pinot.broker.startup.warmup.minIterations 프로브가 성공하거나 pinot.broker.startup.warmup.budgetMs가 만료되면 완료돼요. 오류, 중단, 예산 소진은 readiness 게이트를 해제하므로 워밍업이 롤링 재시작을 무한정 차단할 수 없어요.

pinot.broker.startup.warmup.enabled=true
pinot.broker.startup.warmup.budgetMs=30000
pinot.broker.startup.warmup.minIterations=1000
pinot.broker.startup.warmup.concurrency=1

이 워밍업은 Netty single-stage 쿼리 경로에만 적용돼요. 게이트는 HTTP readiness에 영향을 주지만 워밍하는 동안 broker를 Helix 디스커버리에서 제거하지는 않아요.

다음 broker 메트릭을 모니터링하세요:

• STARTUP_WARMUP_COMPLETE: 워밍업 활성 중 0, readiness 진행 가능 시 1, 비활성화 시 항상 1.
• STARTUP_WARMUP_DURATION_MS: Helix 수렴부터 워밍업 게이트 해제까지의 전체 시간.
• STARTUP_WARMUP_UNCOVERED_SERVERS: 선택된 프로브 테이블이 커버하지 못한 라우팅 서버 수, 보통 0.

장애 감지기 (Failure detector)

기본값(NO_OP)은 broker가 비정상 서버를 추적하지 않아요. pinot.broker.failure.detector.type=CONNECTION으로 설정하면 쿼리가 연결 실패를 만날 때 서버를 비정상으로 표시하고 라우팅에서 제외한 뒤 나중에 재시도해요.

재시도는 지수 백오프(retry.initial.delay.ms, retry.delay.factor)를 사용해요. max.retries 후 broker는 리스너가 서버를 잃지 않도록 다시 정상으로 표시해요.

CUSTOM은 pinot.broker.failure.detector.class에 있는 클래스를 로드해요. 값은 NO_OP, CONNECTION, CUSTOM이에요.

Broker gRPC 전송 (Broker gRPC transport)

Pinot broker는 두 가지 다른 gRPC 쿼리 경로에 참여할 수 있어요:

• 클라이언트 → broker: broker는 pinot.broker.grpc.port 또는 pinot.broker.grpc.tls.port에서 Broker gRPC API를 노출해요.
• broker → 서버: broker는 pinot.broker.request.handler.type=grpc일 때만 Pinot 서버와 gRPC로 통신해요.

보안 broker gRPC 리스너의 경우 Pinot은 현재 pinot.broker.tls.* 아래에 구성된 TLS 자료를 재사용해요. 즉 pinot.broker.grpc.tls.enabled와 pinot.broker.grpc.tls.port가 보안 리스너를 선택하고, 키스토어와 트러스트스토어는 일반 broker TLS 접두사에서 가져와요.

예시:

pinot.broker.grpc.port=8010
pinot.broker.grpc.tls.enabled=true
pinot.broker.grpc.tls.port=8020

pinot.broker.tls.keystore.path=/path/to/broker-keystore.p12
pinot.broker.tls.keystore.password=changeit
pinot.broker.tls.keystore.type=PKCS12
pinot.broker.tls.truststore.path=/path/to/broker-truststore.p12
pinot.broker.tls.truststore.password=changeit
pinot.broker.tls.truststore.type=PKCS12

pinot.broker.request.handler.type=grpc를 사용하면 broker의 서버로 향하는 아웃바운드 gRPC 채널을 위의 keepalive 및 shutdown 설정으로 튜닝할 수 있어요. channelKeepAliveTimeSeconds가 양수로 설정되지 않는 한 keepalive는 비활성화된 상태로 유지돼요.

예시:

pinot.broker.request.handler.type=grpc

channelKeepAliveTimeSeconds=60
channelKeepAliveTimeoutSeconds=20
channelKeepAliveWithoutCalls=true
channelShutdownTimeoutSeconds=10

더 알아보기 (Learn more)

• Multi-Stage 쿼리 엔진
• Broker gRPC API