Node.js 클라이언트 구성

Node.js 클라이언트 구성 (Node.js client configs)

Pulsar Node.js 클라이언트에서 사용할 수 있는 구성 파라미터를 정리했어요. 클라이언트, 프로듀서, 컨슈머, 리더 각각의 설정을 살펴볼게요. 기본값이 잘 잡혀 있어서 특별한 경우가 아니면 건드릴 일이 적지만, 어느 값이 어느 기본값을 쓰는지 알아두면 도움이 돼요.

출처: 문서

본문

다음은 Pulsar Node.js 클라이언트에서 사용할 수 있는 구성 파라미터들이에요.

클라이언트 구성 (Client configs)

파라미터 설명 기본값
serviceUrl Pulsar 클러스터의 연결 URL.
authentication 인증 프로바이더 구성. (기본: 인증 없음). mTLS 인증에서 자세히. 인증 없음
operationTimeoutSeconds Node.js 클라이언트 연산(프로듀서 만들기, 토픽 구독·구독 해제)의 타임아웃. 이 임계값에 도달할 때까지 재시도하고, 그러면 연산이 실패해요. 30
ioThreads Pulsar 브로커와의 연결을 처리하는 데 사용할 스레드 수. 1
messageListenerThreads 메시지 리스너(컨슈머와 리더)가 사용하는 스레드 수. 1
concurrentLookupRequest 각 브로커 연결에서 보낼 수 있는 동시 lookup 요청 수. 최댓값을 설정하면 브로커가 과부하되는 것을 막아줘요. 클라이언트가 수천 개의 Pulsar 토픽을 생산 및/또는 구독해야 할 때만 기본 50000 이상으로 설정해야 해요. 50000
tlsTrustCertsFilePath 신뢰하는 TLS 인증서의 파일 경로. 설정하지 않으면 패키지에 번들된 cert.pem 파일로 폴백하는데, 이 파일은 설치 시 Node.js 런타임의 루트 CA에서 시드된 거예요. 번들된 cert.pem
tlsCertificateFilePath mTLS에 사용하는 클라이언트 TLS 인증서의 파일 경로.
tlsPrivateKeyFilePath mTLS에 사용하는 클라이언트 TLS 개인 키의 파일 경로.
tlsValidateHostname TLS 호스트네임 검증을 활성화할지 여부. false
tlsAllowInsecureConnection Pulsar 클라이언트가 브로커의 신뢰되지 않은 TLS 인증서를 수락할지 여부. false
statsIntervalInSeconds 각 통계 정보 사이의 간격. 양수 statsInterval로 통계가 활성화돼요. 값을 최소 1초로 설정해야 해요. 600
listenerName 클라이언트가 브로커에 연결할 때 사용할 리스너 이름. 여러 엔드포인트를 광고할 때 유용해요.
log 로깅에 사용하는 함수. (level, file, line, message) 인자를 받아요. console.log
logLevel 클라이언트가 내보내는 로그의 로그 레벨. LogLevel.DEBUG(0), LogLevel.INFO(1), LogLevel.WARN(2), LogLevel.ERROR(3)를 받아요. LogLevel.INFO
connectionTimeoutMs 브로커 연결이 확립될 때까지 기다렸다가 실패할 시간(밀리초).

프로듀서 구성 (Producer configs)

파라미터 설명 기본값
topic 프로듀서가 메시지를 게시하는 Pulsar 토픽. 토픽 형식은 <topic-name> 또는 <tenant-name>/<namespace-name>/<topic-name>. 예: sample/ns1/my-topic.
producerName 프로듀서의 이름. 명시적으로 지정하지 않으면 Pulsar가 전역적으로 고유한 이름을 자동 생성해요. 명시적으로 이름을 지정한다면 모든 Pulsar 클러스터에서 고유해야 해요. 그렇지 않으면 생성 연산이 오류를 던져요.
sendTimeoutMs 토픽에 메시지를 게시할 때 프로듀서는 해당 Pulsar 브로커의 ack를 기다려요. 이 파라미터가 설정한 임계값 안에 메시지가 ack되지 않으면 오류가 발생해요. sendTimeoutMs를 -1로 설정하면 타임아웃이 무한대가 돼요(제거됨). 메시지 중복 제거 기능을 사용할 때는 send 타임아웃을 제거하는 것을 권장해요. 30000
initialSequenceId 메시지의 초기 시퀀스 ID. 프로듀서가 메시지를 보낼 때 메시지에 시퀀스 ID를 추가하고, 보낼 때마다 증가해요.
maxPendingMessages 보류 중인 메시지(즉 브로커의 ack를 기다리는 메시지)를 보관하는 큐의 최대 크기. 기본적으로 큐가 가득 차면 blockIfQueueFull이 true가 아닌 한 모든 send 호출이 실패해요. 1000
maxPendingMessagesAcrossPartitions 파티션들의 보류 중인 큐 합계의 최대 크기. 50000
blockIfQueueFull true로 설정하면 발신 메시지 큐가 가득 찼을 때 실패하고 오류를 던지는 대신 프로듀서의 send 메서드가 기다려요(큐 크기는 maxPendingMessages 파라미터로 결정). false(기본)면 큐가 가득 찼을 때 send 연산이 실패하고 오류를 던져요. false
messageRoutingMode (파티셔닝된 토픽의 프로듀서용) 메시지 라우팅 로직. 이 로직은 메시지에 키가 설정되지 않았을 때만 적용돼요. 사용 가능한 옵션: 라운드 로빈(RoundRobinDistribution), 또는 모든 메시지를 단일 파티션에 게시(UseSinglePartition, 기본). UseSinglePartition
hashingScheme 특정 메시지가 게시될 파티션을 결정하는 해시 함수(파티셔닝된 토픽만). 사용 가능한 옵션: JavaStringHash(Java의 String.hashCode()와 동일), Murmur3_32Hash(Murmur3 해시 함수 적용), BoostHash(C++의 Boost 라이브러리 해시 함수 적용). BoostHash
compressionType 프로듀서가 사용하는 메시지 데이터 압축 타입. 사용 가능한 옵션은 LZ4, Zlib, ZSTD, SNAPPY. 압축 없음
batchingEnabled true로 설정하면 프로듀서가 메시지를 배치로 보내요. true
batchingMaxPublishDelayMs 배치에서 메시지를 보내는 최대 지연 시간. 10
batchingMaxMessages 각 배치에서 보내는 메시지의 최대 크기. 1000
properties 프로듀서의 메타데이터.

컨슈머 구성 (Consumer configs)

파라미터 설명 기본값
topic 컨슈머가 서브스크립션을 만들고 메시지를 듣는 Pulsar 토픽.
topics 토픽의 배열.
topicsPattern 토픽의 정규식.
subscription 이 컨슈머의 서브스크립션 이름.
subscriptionType 사용 가능한 옵션은 Exclusive, Shared, Key_Shared, Failover. Exclusive
subscriptionInitialPosition 처음으로 토픽에 구독할 때 커서를 설정할 초기 위치. SubscriptionInitialPosition.Latest
ackTimeoutMs ack 타임아웃(밀리초). 0
nAckRedeliverTimeoutMs 처리에 실패한 메시지를 재전달하기 전에 기다리는 지연. 60000
receiverQueueSize 컨슈머의 수신 큐 크기, 즉 애플리케이션이 receive를 호출하기 전에 컨슈머가 누적할 수 있는 메시지 수. 기본 1000보다 높은 값은 메모리 사용량이 늘어나지만 컨슈머 처리량을 높일 수 있어요. 1000
receiverQueueSizeAcrossPartitions 파티션 전체에서 최대 총 수신 큐 크기. 이 값을 초과하면 개별 파티션의 수신 큐 크기를 줄이는 데 사용돼요. 50000
consumerName 컨슈머의 이름. (v2.4.1) 현재 failover 모드는 순서 결정에 컨슈머 이름을 사용해요.
properties 컨슈머의 메타데이터.
listener 수신된 메시지에 대해 호출되는 리스너.
readCompacted readCompacted를 활성화하면 컨슈머가 토픽의 전체 메시지 백로그 대신 컴팩션된 토픽에서 메시지를 읽어요. 컨슈머는 컴팩션된 토픽에서 각 키의 최신 값만 볼 수 있어요(compacting backlog 시점까지). 그 지점 이후로는 평소처럼 메시지를 보내요. readCompacted는 단일 활성 컨슈머를 가진 영속 토픽(failover 또는 exclusive 서브스크립션 같은)의 서브스크립션에서만 활성화할 수 있어요. 비영속 토픽의 서브스크립션 또는 공유 서브스크립션에서 활성화하려 하면 서브스크립션 호출이 PulsarClientException을 던져요. false

리더 구성 (Reader configs)

파라미터 설명 기본값
topic 리더가 서브스크립션을 만들고 메시지를 듣는 Pulsar 토픽.
startMessageId 초기 리더 위치, 즉 리더가 메시지 처리를 시작하는 메시지. 옵션은 Pulsar.MessageId.earliest(토픽에서 가장 이른 사용 가능 메시지), Pulsar.MessageId.latest(토픽에서 가장 최근 사용 가능 메시지), 또는 earliest/latest가 아닌 위치의 메시지 ID 객체.
receiverQueueSize 리더의 수신 큐 크기, 즉 애플리케이션이 readNext를 호출하기 전에 리더가 누적할 수 있는 메시지 수. 기본 1000보다 높은 값은 메모리 사용량이 늘어나지만 리더 처리량을 높일 수 있어요. 1000
readerName 리더의 이름.
subscriptionRolePrefix 서브스크립션 역할 접두사.
readCompacted readCompacted를 활성화하면 리더가 토픽의 전체 메시지 백로그 대신 컴팩션된 토픽에서 메시지를 읽어요. 리더는 컴팩션된 토픽에서 각 키의 최신 값만 볼 수 있어요(compacting backlog 시점까지). 그 지점 이후로는 평소처럼 메시지를 보내요. readCompacted는 단일 활성 컨슈머를 가진 영속 토픽(failover 또는 exclusive 서브스크립션 같은)의 서브스크립션에서만 활성화할 수 있어요. 비영속 토픽의 서브스크립션 또는 공유 서브스크립션에서 활성화하려 하면 서브스크립션 호출이 PulsarClientException을 던져요. false

더 알아보기 (Learn more)