Server 구성
Server 구성
Apache Pinot Server의 구성 속성 레퍼런스 문서예요.
출처: 문서
본문
공유 MSE 사서함 keep-alive 속성(pinot.query.runner.channel.keep.alive.* 및 pinot.query.runner.mailbox.server.permit.keep.alive.*)은 Mailbox channel keep-alive를 참고하세요.
Server 구성은 server 시작 매개변수의 일부로 제공할 수 있어요.
bin/pinot-admin.sh StartServer -configFileName /path/to/server.conf
구성 파일의 중복 키 (Duplicate Keys)
Apache Pinot 1.3.0부터 구성 파일의 중복 키는 시작 시
ConfigurationException을 발생시켜요. 이전에는 중복 키가 목록으로 조용히 병합됐어요. 이 오류가 발생하면 각 구성 속성이 구성 파일에 한 번만 나타나는지 확인하세요.예시 오류:
ConfigurationException: Duplicate key found in /path/to/server.conf at line 10 and line 15: pinot.server.netty.port
server.conf는 다음 속성을 가질 수 있어요.
Server 구성 속성 테이블
| 속성 | 기본값 | 설명 |
|---|---|---|
| pinot.server.netty.port | 8098 | Pinot Server를 쿼리하는 포트 |
| pinot.server.netty.host | Pinot server 호스트 이름 | |
| pinot.server.adminapi.port | 8097 | Pinot Server Admin UI 포트 |
| pinot.server.grpc.enable | true | 서버 측 gRPC 쿼리 서비스를 활성화해요. 이 리스너는 gRPC 쿼리 전송에 사용되며 Netty 및 Admin API 리스너와 분리돼 있어요. |
| pinot.server.grpc.port | 8090 | 서버 측 gRPC 쿼리 서비스 포트 |
| pinot.server.grpctls.enabled | false | 서버 측 gRPC 쿼리 서비스에 TLS를 활성화해요. 활성화하면 pinot.server.grpctls.* 아래에 TLS 자료를 구성하세요. |
| pinot.server.instance.id | 기본적으로 Helix가 사용하는 서버 인스턴스 ID는 Server_hostname_port예요. 이 config는 기본 설정을 덮어써요. | |
| pinot.server.instance.dataDir | java.io.tmpdir + /PinotServer/index |
모든 데이터를 담는 디렉터리 |
| pinot.server.instance.consumerDir | 소비 디렉터리 | |
| pinot.server.instance.segmentTarDir | java.io.tmpdir + /PinotServer/segmentTar |
Controller나 Deep Store에서 다운로드한 임시 세그먼트를 담는 디렉터리 |
| pinot.tar.compression.codec.name | gzip |
세그먼트 tar 아카이브 업로드/다운로드에 사용되는 압축 코덱. 지원 값: gzip(기본), lz4_framed(빠르고 압축률 낮음), zstandard(속도와 비율 균형). 1.3.0에서 도입. 파일 확장자: 각각 .tar.gz, .tar.lz4, .tar.zst. |
| pinot.server.instance.readMode | mmap |
세그먼트 읽기 모드 |
| pinot.server.instance.reload.consumingSegment | true | reload 세그먼트 API가 소비 중 세그먼트를 reload할지 지정해요. 대응하는 스키마가 업데이트되고 그 변경이 소비 세그먼트에 반영되길 원할 때 유용해요. |
| pinot.server.instance.data.manager.class | org.apache.pinot.server.starter.helix.HelixInstanceDataManager |
데이터 관리자 클래스 |
| pinot.query.scheduler.name | fcfs |
현재 FCFS(first-come-first-serve)만 지원 |
| pinot.query.scheduler.query_runner_threads | CPU 코어 수 | 쿼리를 실행하는 메인 스레드(쿼리당 스레드 하나). Helix 클러스터 config로 런타임에 서버 재시작 없이 동적으로 업데이트할 수 있어요. |
| pinot.query.scheduler.query_worker_threads | 2 × CPU 코어 수 | 세그먼트를 처리하는 워커 스레드(쿼리당 여러 스레드). 런타임에 동적으로 업데이트할 수 있어요. |
| queryWorkerThreads | max(2, min(8, 2 * CPU cores)) |
서버 측 gRPC 쿼리 서비스가 사용하는 워커 풀용 최상위 server.conf 키. pinot.query.scheduler.query_worker_threads(서버 쿼리 스케줄러와 Lucene 검색 풀 크기 제어)와 구분돼요. |
| maxInboundMessageSizeBytes | 134217728 (128 MB) |
서버 측 gRPC 쿼리 서비스가 수락하는 최대 인바운드 gRPC 메시지 크기용 최상위 키 |
| requestThrottlingMemoryThresholdBytes | 17179869184 (16 GiB) |
서버 측 gRPC 쿼리 서비스에서 요청 제한을 트리거하는 직접 메모리 임계값 |
| pinot.query.scheduler.query.log.maxRatePerSecond | unlimited | (Deprecated: pinot.server.query.log.maxRatePerSecond 사용) 초당 로깅되는 최대 쿼리 수. 예외 쿼리와 비용이 큰 쿼리는 항상 로깅돼요. |
| pinot.server.query.executor.class | org.apache.pinot.core.query.executor.ServerQueryExecutorV1Impl |
쿼리 실행기 클래스 |
| pinot.server.query.executor.pruner.class | ValidSegmentPruner,DataSchemaSegmentPruner,ColumnValueSegmentPruner,SelectionQuerySegmentPruner |
세그먼트 프루너 클래스 |
| pinot.server.query.executor.timeout | 15000 |
Server가 쿼리를 처리하는 타임아웃 (밀리초) |
| pinot.server.query.executor.max.execution.threads | -1 (무제한) |
쿼리에 허용되는 최대 실행 스레드 수. 이를 제한하면 하나의 비싼 쿼리가 모든 실행 스레드를 차지하는 것을 막을 수 있어요. |
| pinot.server.query.executor.default.execution.threads | -1 (미설정; max.execution.threads로 폴백) |
SET maxExecutionThreads를 설정하지 않은 쿼리에 할당되는 기본 실행 스레드 수. |
| pinot.server.query.executor.max.init.group.holder.capacity | 10000 |
그룹 키 홀더의 초기 용량. 이 값을 늘리면 그룹 키 홀더의 재조정을 줄일 수 있지만, 작은 group-by 쿼리의 힙 사용량은 늘어나요. |
| pinot.server.query.executor.min.init.indexed.table.capacity | 128 |
group-by 결과를 병합하는 동안 Pinot이 사용하는 서버 측 IndexedTable의 최소 초기 용량. |
| pinot.server.query.executor.num.groups.limit | 100000 |
쿼리 실행 중 각 세그먼트에서 유지되는 최대 그룹 수. 이 한도에 도달하면 더 이상 그룹을 가져오지 않아요(기존 그룹에는 계속 집계). |
| pinot.server.query.executor.num.groups.warn.limit | 150000 |
쿼리 실행 중 누적된 그룹 수의 경고 임계값. 도달하면 Pinot이 경고를 로깅하고 응답 메타데이터에 numGroupsWarningLimitReached=true를 설정하되 쿼리를 중단하지 않아요. |
| pinot.server.query.executor.min.segment.group.trim.size | -1 (트림 안 함) |
쿼리 실행 중 세그먼트 수준에서 유지되는 최소 그룹 수. |
| pinot.server.query.executor.min.server.group.trim.size | 5000 |
쿼리 실행 중 서버 수준에서 유지되는 최소 그룹 수. |
| pinot.server.query.executor.groupby.trim.threshold | 1000000 |
서버 그룹 트리밍을 트리거할 그룹 수의 임계값. |
| pinot.server.requestHandlerFactory.class | org.apache.pinot.server.request.SimpleRequestHandlerFactory |
요청 핸들러 팩토리 |
| pinot.server.instance.segment.format.version | 세그먼트 형식 버전 | |
| pinot.server.instance.enable.split.commit | (Deprecated) 실시간 세그먼트 커밋용 분할 커밋 프로토콜 활성화 | |
| pinot.server.instance.enable.commitend.metadata | (Deprecated) 세그먼트 커밋 종료 시 메타데이터 커밋 활성화 | |
| pinot.server.instance.segment.upload.to.deep.store | false | 실시간 세그먼트 커밋이 완료된 세그먼트를 controller를 거치지 않고 딥 스토어에 직접 업로드해야 하는지의 기본값. |
| pinot.server.instance.offset.lag.tracking.enable | true | 실시간 수집용 REALTIME_INGESTION_OFFSET_LAG server 게이지 추적 활성화. |
| pinot.server.instance.offset.lag.tracking.update.interval | 60000 | REALTIME_INGESTION_OFFSET_LAG에 사용되는 업스트림 오프셋 새로고침 간격(밀리초). 1000보다 커야 해요. |
| pinot.server.instance.max.parallel.refresh.threads | 1 | 한 서버에서 동시에 새로고침할 수 있는 세그먼트 수 |
| pinot.server.instance.realtime.max.parallel.segment.builds | 0 | 병렬로 구축할 수 있는 실시간 세그먼트 수. <= 0이면 무제한을 의미해요. |
| pinot.server.instance.realtime.alloc.offheap | true | 실시간 소비 세그먼트의 메모리를 오프힙으로 할당할지 제어하는 불리언 값 |
| pinot.server.instance.realtime.alloc.offheap.direct | false | real-time.alloc.offheap이 true이면 이 값은 할당이 direct인지 여부를 제어해요(false는 mmap 할당). |
| pinot.server.startup.minResourcePercent | 100 | server가 쿼리 서빙용으로 STARTED로 표시되기 전 ONLINE 상태여야 하는 테이블의 비율 |
| pinot.server.startup.timeoutMs | 10분 | server가 STARTED로 표시되기 전 모든 상태 검사를 기다리는 총 시간 |
| pinot.server.starter.realtimeConsumptionCatchupWaitMs | 0 | 소비 세그먼트를 기다리는 정적 시간. 상태 체커와 함께 사용할 때 세그먼트가 GOOD이 될 때까지 기다리는 시간. |
| pinot.server.starter.enableRealtimeOffsetBasedConsumptionStatusChecker | false | true이면 server가 모든 소비 세그먼트의 현재 최신 오프셋을 수집하고 해당 오프셋을 따라잡으면 세그먼트를 GOOD으로 표시해요. |
| pinot.server.starter.enableRealtimeFreshnessBasedConsumptionStatusChecker | false | true이면 server가 최신 오프셋을 따라잡거나 각 세그먼트의 최신 소비 이벤트가 pinot.server.starter.realtimeMinFreshnessMs 내에 있을 때까지, 또는 pinot.server.startup.timeoutMs가 경과할 때까지 STARTED로 표시되거나 쿼리를 서빙하지 않아요. |
| pinot.server.starter.realtimeMinFreshnessMs | 10초 | freshness 기반 체커가 세그먼트를 GOOD으로 간주하기 위한 최소 freshiness(now - last_event_time). |
| pinot.server.starter.realtimeFreshnessIdleTimeoutMs | 0 | freshness 기반 체커가 이벤트를 소비하지 않은 세그먼트를 이 타임아웃 후 GOOD으로 표시해요. |
| pinot.server.startup.exitOnServiceStatusCheckFailure | false | true이면 상태가 GOOD으로 바뀌지 않으면 pinot.server.shutdown.timeoutMs 후 shutdown해요. |
| pinot.server.startup.enableServiceStatusCheck | true | true - 모든 구성된 검사 실행, false - 시작 검사 없이 STARTED로 표시 |
| pinot.server.startup.serviceStatusCheckIntervalMs | 10초 | server가 상태 검사를 수행하는 간격 |
| pinot.server.shutdown.timeoutMs | 10분 | 종료 체크 타임아웃 |
| pinot.server.shutdown.enableQueryCheck | true | 인플라이트 쿼리가 완료될 때까지 대기 |
| pinot.server.shutdown.noQueryThresholdMs | 15초 | 이 시간 동안 쿼리가 수신되지 않을 때까지 대기 후 종료 진행 |
| pinot.server.shutdown.enableResourceCheck | false | 종료 전 외부 가시성(예: Helix 라우팅 테이블) 업데이트 확인 |
| pinot.server.shutdown.resourceCheckIntervalMs | 10초 | 종료 중 리소스 검사 간격 |
| pinot.server.admin.access.control.factory.class | org.apache.pinot.server.access.AllowAllAccessFactory |
server admin 리스너용 액세스 제어 팩토리. AllowAllAccessFactory는 기본 공개 동작을 유지하고, BasicAuthAccessFactory로 설정하면 권한 라우트에 명시적 admin 권한이 필요해요. |
| pinot.server.adminapi.access.protocols | http | server admin api에 접근하는 인그레스 프로토콜 (http 또는 https 또는 http,https) |
| pinot.server.adminapi.access.protocols.http.port | http로 server admin api에 접근하는 포트 | |
| pinot.server.adminapi.broker.protocols.https.port | https로 server admin api에 접근하는 포트 | |
| pinot.server.tls.keystore.path | 서버 TLS 키스토어 경로 | |
| pinot.server.tls.keystore.password | 키스토어 암호 | |
| pinot.server.tls.truststore.path | 서버 TLS 트러스트스토어 경로 | |
| pinot.server.tls.truststore.password | 트러스트스토어 암호 | |
| inot.server.tls.client.auth | false | TLS 클라이언트 인증 요구 토글 |
| pinot.server.netty.enabled | true | server에 비보안 netty 연결 활성화 토글 |
| pinot.server.netty.port | 비보안 netty로 pinot server에 접근하는 포트 | |
| pinot.server.nettytls.enabled | TLS netty 사용 여부 | |
| pinot.server.nettytls.port | TLS 보안 netty로 pinot server에 접근하는 포트 | |
| pinot.server.http.server.thread.pool.corePoolSize | 2 × 코어 수 | pinot-server의 http-server가 사용하는 스레드 풀 config |
| pinot.server.http.server.thread.pool.maxPoolSize | 2 × 코어 수 | pinot-server의 http-server가 사용하는 스레드 풀 config |
| pinot.server.http.server.max.http.header.size | unset (Grizzly 기본) | server admin API의 Grizzly HTTP/HTTPS 리스너가 수락하는 최대 HTTP 헤더 총 크기. Netty 데이터 평면이나 gRPC 쿼리 전송에는 영향 없음. |
| pinot.server.http.server.max.request.headers | unset (Grizzly 기본) | server admin API의 Grizzly 리스너가 수락하는 최대 HTTP 헤더 수. |
| pinot.server.segment.fetcher.http.client.maxConnTotal | 세그먼트 다운로드용 HttpSegmentFetcher가 사용하는 http-client config | |
| pinot.server.segment.fetcher.http.client.maxConnPerRoute | http-client config | |
| pinot.server.segment.fetcher.http.client.connectionTimeoutMs | 세그먼트 페처가 연결을 맺기 위해 기다리는 config | |
| pinot.server.segment.fetcher.http.request.socketTimeoutMs | 세그먼트 페처가 세그먼트 다운로드를 기다리는 config | |
| pinot.server.segment.fetcher.http.request.connectionRequestTimeoutMs | 세그먼트 페처가 풀에서 연결을 기다리는 config | |
| pinot.server.instance.max.segment.preload.threads | 0 | upsert 테이블에서 세그먼트를 프리로드하기 위해 생성할 스레드 수. 0보다 커야 하며 그렇지 않으면 preload는 동기적으로 수행돼요. |
| pinot.server.instance.dedup.default.ignore.non.default.tiers | false | dedupConfig.ignoreNonDefaultTiers가 DEFAULT인 dedup 테이블의 기본 동작. true이면 Pinot이 dedup 메타데이터 구축 시 비기본 티어의 불변 세그먼트를 건너뛰어요. |
| pinot.server.instance.upsert.default.allow.partial.upsert.consumption.during.commit | false | 부분 upsert 테이블의 커밋 중 소비 허용에서 deprecated upsert 폴백. 새 배포는 streamIngestionConfig의 parallelSegmentConsumptionPolicy를 선호해야 해요. |
| pinot.server.consuming.segment.consistency.mode | RESTRICTED |
부분 upsert 테이블과 dropOutOfOrder=true 테이블에 대해 서버가 세그먼트 reload와 force commit을 처리하는 방법 제어. RESTRICTED(안전, 기본), PROTECTED, UNSAFE. |
| pinot.server.query.regex.class | JAVA_UTIL | 쿼리 실행에 사용되는 정규식 클래스. 유효 옵션은 JAVA_UTIL과 RE2J. |
| pinot.server.instance.consumer.client.id.suffix | 소비자 인스턴스를 구분하는 접미사 구성. 동일 클라이언트 ID를 가진 실시간 소비 세그먼트의 여러 복제본에서 고유한 서버 수준 정체성을 추가하는 데 사용. | |
| pinot.server.segment.uploader.protocol | http | server가 세그먼트를 controller에 업로드할 때 http 프로토콜 구성. 필수. |
| pinot.server.segment.uploader.https.enabled | false | 서버 업로드 프로토콜에 https 활성화. pinot.server.segment.uploader.protocol=https도 구성해야 해요. |
| pinot.server.segment.uploader.upload.request.timeout.ms | 300_000 | 기본 300초/5분 |
| pinot.server.segment.uploader.auth.xxx | 인증 관련 config | |
| pinot.server.segment.uploader.http.client.maxConnTotal | 업로더 http 클라이언트 config | |
| pinot.server.lucene.min.refresh.interval.ms | 10 | Lucene 인덱스 새로고침 전 대기 시간 config |
| pinot.server.lucene.max.refresh.threads | 1 | Lucene 인덱스를 동시에 새로고침하는 스레드 수 |
| pinot.server.query.executor.mse.max.execution.threads | -1 | 이 서버의 동시 multi-stage 실행기 작업 고정 하드 한도. 양수면 클러스터 파생 하드 한도를 덮어써요. |
| pinot.server.query.executor.mse.max.execution.threads.exceed.strategy | ERROR | 서버 측 multi-stage 실행기 하드 한도 초과 시 동작. ERROR(즉시 거부) 및 LOG(실행 허용하되 경고) 지원. |
| pinot.query.mse.stats.mode | ALWAYS | multi-stage 쿼리 워커가 응답에 스테이지 통계를 포함할지 제어. ALWAYS, SAFE, NEVER. |
| pinot.query.multistage.query.server.permit.keep.alive.time.ms | 300000 | MSE QueryServer gRPC 서버가 수락하는 broker keep-alive ping 간 최소 간격(밀리초). |
| pinot.query.multistage.query.server.permit.keep.alive.without.calls | false | 활성 RPC가 없는 동안 broker keep-alive ping이 허용되는지 여부. |
| pinot.server.max.segment.preprocess.parallelism | Integer.MAX_VALUE | 로드 시 병렬로 전처리(인덱스 구축)할 수 있는 최대 세그먼트 수. 0으로 설정하면 재조정될 때까지 새 전처리 작업 차단. |
| pinot.server.max.segment.download.parallelism | Integer.MAX_VALUE | 딥 스토어 또는 피어에서 병렬로 다운로드할 수 있는 최대 세그먼트 수. |
| pinot.server.peer.download.enabled | false | true이면 PredownloadScheduler가 실패한 불변 세그먼트 predownload를 딥 스토어 실패에서 멈추는 대신 피어 서버에서 재시도해요. |
| pinot.server.instance.peer.download.scheme | 피어 서버에서 세그먼트를 다운로드할 때 Pinot이 사용할 프로토콜. http, https 유효. |
|
| pinot.server.predownload.parallelism | numProcessors * 3 |
대체 서버가 트래픽을 받기 전에 불변 세그먼트를 predownload할 때 PredownloadScheduler가 사용하는 스레드 수. |
| pinot.server.max.segment.startree.preprocess.parallelism | Integer.MAX_VALUE | 세그먼트 전처리 중 병렬로 구축할 수 있는 star-tree 인덱스 최대 수. |
| pinot.server.consumption.rate.limit | 0.0 (제한 없음) | 이 서버에서 모든 실시간 테이블에 걸쳐 초당 소비할 수 있는 최대 행 수. 0은 서버 수준 행/초 제한 없음. |
| pinot.server.consumption.rate.limit.bytes | 0.0 (제한 없음) | 이 서버에서 모든 실시간 테이블에 걸쳐 초당 소비할 수 있는 최대 바이트 수. |
| pinot.server.instance.enableThreadCpuTimeMeasurement | false | 쿼리 실행용 스레드당 CPU 시간 측정 활성화. 상세 메트릭 제공하지만 오버헤드 추가. |
| pinot.server.instance.enableThreadAllocatedBytesMeasurement | false | 스레드당 메모리 할당 측정 활성화. 쿼리당 상세 메모리 할당 메트릭 제공하지만 오버헤드 추가. |
| pinot.server.query.executor.enableThrottlingOnHeapUsage | false | 힙 사용량이 위험할 때 제한 활성화. 활성화하면 메모리 압박 시 즉시 거부하는 대신 query-executor 작업을 큐에 넣어요. |
| pinot.server.query.executor.heap.usage.throttle.queue.maxSize | 1000 | 힙 사용량 제한 큐에서 대기할 수 있는 최대 query-executor 작업 수. <= 0이면 무제한. |
| pinot.server.query.executor.heap.usage.throttle.queue.timeoutMs | 30000 | 큐에 들어간 query-executor 작업이 타임아웃 전에 힙 압력이 해소되기를 기다리는 기본 최대 시간(밀리초). |
| pinot.server.query.executor.heap.usage.throttle.monitorIntervalMs | 1000 | 큐에 들어간 작업이 재개 가능한지 결정하는 힙 사용량 검사 간격(밀리초). |