확장 가능한 토픽 관리
확장 가능한 토픽 관리 (Manage scalable topics)
확장 가능한(scalable) 토픽은 부하에 따라 세그먼트를 자동으로 분할·병합하는 토픽 유형이에요. 이 페이지는 확장 가능한 토픽을 관리하는 방법을 다뤄요. 생산·소비(produce and consume)는 V5 API를 지원하는 클라이언트를 사용하고, 이 페이지는 토픽 자체를 만들고 운영하는 방법에 초점을 맞춰요.
출처: 문서
본문
note
이 기능의 배경 개념은 Scalable topics을 참고해요.
이 페이지는 확장 가능한 토픽을 관리하는 방법을 다뤄요. produce와 consume은 V5 API 지원 클라이언트를 사용하고, 이 페이지는 토픽 자체를 만들고 운영하는 방법이에요.
모든 연산은 세 가지 방식으로 가능해요: pulsar-admin scalable-topics CLI, /admin/v2/scalable 아래의 REST API, Java admin 클라이언트(PulsarAdmin.scalableTopics()). 아래 예제는 CLI를 먼저 보여주고요, REST API reference에 모든 엔드포인트가 나열돼 있어요.
아래 명령들에서 토픽은 tenant/namespace/topic 이름(URL 스킴 없이)으로 식별해요.
확장 가능한 토픽 생성 (Create a scalable topic)
확장 가능한 토픽은 초기 세그먼트 수로 생성돼요. 작게 시작하세요 — 세그먼트 1개가 기본값이에요 — 그러면 auto split/merge가 부하에 맞게 키워줘요.
bin/pulsar-admin scalable-topics create my-tenant/my-namespace/my-topic --segments 1
| Option | Description | Default |
|---|---|---|
-s, --segments |
초기 세그먼트 수 | 1 |
-p, --property |
key=value 프로퍼티. 여러 개는 반복 | -- |
Java admin 클라이언트:
admin.scalableTopics().createScalableTopic("my-tenant/my-namespace/my-topic", 1);
확장 가능한 토픽 나열 (List scalable topics)
네임스페이스의 모든 확장 가능한 토픽을 나열해요.
bin/pulsar-admin scalable-topics list my-tenant/my-namespace
특정 프로퍼티를 가진 토픽으로 필터링(여러 필터를 AND하려면 -p 반복)해요.
bin/pulsar-admin scalable-topics list my-tenant/my-namespace -p team=ingest -p tier=gold
확장 가능한 토픽 검사 (Inspect a scalable topic)
토픽 메타데이터 — 각 세그먼트의 해시 범위와 상태를 포함한 세그먼트 DAG — 를 가져와요.
bin/pulsar-admin scalable-topics get-metadata my-tenant/my-namespace/my-topic
집계된 런타임 통계를 가져와요.
bin/pulsar-admin scalable-topics stats my-tenant/my-namespace/my-topic
구독 관리 (Manage subscriptions)
확장 가능한 토픽의 구독은 DAG의 모든 세그먼트에 걸쳐 있어요. 관리 명령은 구독 전체에 대해 동작해요.
구독을 과거 시점으로 리셋(오프셋은 현재 기준 상대적이며, 30m, 1h, 5d 같은 단위를 받아요)해요.
bin/pulsar-admin scalable-topics seek my-tenant/my-namespace/my-topic \
--subscription my-sub --time 1h
구독의 모든 미전달 메시지(backlog)를 모든 세그먼트에 걸쳐 건너뛰어요.
bin/pulsar-admin scalable-topics clear-backlog my-tenant/my-namespace/my-topic \
--subscription my-sub
세그먼트 분할과 병합 (Split and merge segments)
뜨거운(hot) 세그먼트를 분할하고 차가운(cold) 인접 세그먼트를 병합하는 것은 보통 자동으로(auto split/merge) 일어나요. 아래 명령은 수동으로 트리거하게 해주는데, 테스트나 예정된 트래픽 이벤트 전에 미리 확장할 때 사용해요.
한 세그먼트를 해시 범위의 두 절반으로 분할해요.
bin/pulsar-admin scalable-topics split-segment my-tenant/my-namespace/my-topic --segment-id 3
두 인접 세그먼트를 하나로 병합해요.
bin/pulsar-admin scalable-topics merge-segments my-tenant/my-namespace/my-topic \
--segment-id-1 3 --segment-id-2 4
세그먼트 ID는 get-metadata에서 얻어요. 병합하려면 두 세그먼트가 인접한 해시 범위를 소유해야 해요.
자동 분할/병합 구성 (Configure auto split/merge)
자동 분할/병합은 기본적으로 켜져 있어요: 각 토픽의 컨트롤러는 분할 임계값을 넘는 로드의 세그먼트를 분할하고, 병합 임계값 아래로 차가운 상태인 인접 세그먼트를 병합해요. 세 단계로 구성되며 설정마다 가장 구체적인 값이 우선해요.
broker.conf의 브로커 기본값(클러스터 전체).- 네임스페이스별 재정의(override).
- 토픽별 재정의.
재정의는 변경한 필드만 설정하고, 설정하지 않은 필드는 상위 수준에서 상속해요.
브로커 기본값 (broker.conf)
| Setting | Description | Default |
|---|---|---|
scalableTopicAutoScaleEnabled |
자동 분할/병합의 마스터 스위치. false면 세그먼트는 수동 split-segment / merge-segments로만 변경돼요 | true |
scalableTopicMaxSegments |
활성 세그먼트의 상한. 도달하면 분할이 멈춰요 | 64 |
scalableTopicMinSegments |
활성 세그먼트의 하한. 도달하면 병합이 멈춰요 | 1 |
scalableTopicMaxDagDepth |
세그먼트 계보(lineage)에서의 최대 병합 수. 분할/병합 플립플로핑을 제한해요(병합만 제한 — 분할은 영향 없음) | 10 |
scalableTopicSplitCooldownSeconds |
토픽에서 자동 분할 사이의 최소 시간(짧음 — 거의 동시에 발생한 트리거 버스트만 합쳐줘요) | 60 |
scalableTopicMergeCooldownSeconds |
토픽에서 자동 병합 사이의 최소 시간 | 300 |
scalableTopicMergeWindowSeconds |
세그먼트가 병합 자격을 얻기 전에 모든 병합 임계값 아래로 연속적으로 유지되어야 하는 시간 | 300 |
scalableTopicSplitMsgRateInThreshold |
세그먼트가 분할되는 초당 인바운드 메시지 수 초과 | 10000 |
scalableTopicSplitBytesRateInThreshold |
세그먼트가 분할되는 초당 인바운드 바이트 초과 | 50000000 (50 MB/s) |
scalableTopicSplitMsgRateOutThreshold |
세그먼트가 분할되는 초당 아웃바운드(디스패치된) 메시지 수 초과 | 50000 |
scalableTopicSplitBytesRateOutThreshold |
세그먼트가 분할되는 초당 아웃바운드 바이트 초과 | 250000000 (250 MB/s) |
scalableTopicMergeMsgRateInThreshold |
병합을 위해 세그먼트가 차갑다고 간주되는 초당 인바운드 메시지 수 미만 | 1000 |
scalableTopicMergeBytesRateInThreshold |
세그먼트가 차갑다고 간주되는 초당 인바운드 바이트 미만 | 5000000 (5 MB/s) |
scalableTopicMergeMsgRateOutThreshold |
세그먼트가 차갑다고 간주되는 초당 아웃바운드 메시지 수 미만 | 5000 |
scalableTopicMergeBytesRateOutThreshold |
세그먼트가 차갑다고 간주되는 초당 아웃바운드 바이트 미만 | 25000000 (25 MB/s) |
scalableTopicAutoScaleIntervalSeconds |
컨트롤러의 주기적 트래픽 기반 평가 주기. 컨슈머 수 변화는 이 간격과 무관하게 즉시 처리돼요 | 60 |
scalableTopicLoadReportIntervalSeconds |
세그먼트 소유 브로커가 자동 확장을 위해 세그먼트 로드를 샘플링하는 빈도 | 10 |
scalableTopicLoadReportRateChangeThreshold |
마지막 보고 이후 세그먼트 비율의 최소 상대 변화(0.25 = 25%). 새 로드 기록을 트리거하며 메타데이터 쓰기량을 제한해요 | 0.25 |
tip
분할 임계값은 의도적으로 대응하는 병합 임계값보다 훨씬 위에 있어요. 둘 사이의 간격이 방금 분할된 세그먼트가 즉시 다시 병합되는 것을 막는 히스테리시스(hysteresis)예요. 튜닝할 때 이 순서를 유지하세요.
이 설정의 대부분은 동적이에요. 재시작 없이 pulsar-admin brokers update-dynamic-config로 런타임에 적용할 수 있어요. 브로커 시작 시에만 읽는 두 개는 scalableTopicAutoScaleIntervalSeconds와 scalableTopicLoadReportIntervalSeconds예요.
네임스페이스별·토픽별 재정의 (Per-namespace and per-topic overrides)
두 재정의 수준 모두 브로커 설정과 같은 필드를 사용해요(각각 선택사항이고, 설정하지 않으면 상속):
enabled, maxSegments, minSegments, maxDagDepth, splitCooldownSeconds, mergeCooldownSeconds, mergeWindowSeconds, 그리고 8개의 split*/merge* 비율 임계값.
재정의는 Java admin 클라이언트 또는 REST로 설정돼요 — 아직 pulsar-admin 하위 명령은 없어요.
AutoScalePolicyOverride override = AutoScalePolicyOverride.builder()
.maxSegments(128)
.splitMsgRateInThreshold(20_000.0)
.build();
// Namespace level -- applies to every scalable topic in the namespace
admin.namespaces().setScalableTopicAutoScalePolicy("my-tenant/my-namespace", override);
// Topic level -- narrowest scope, wins over namespace and broker
admin.scalableTopics().setAutoScalePolicy("my-tenant/my-namespace/my-topic", override);
재정의를 읽거나 지우려면 대응하는 getScalableTopicAutoScalePolicy / removeScalableTopicAutoScalePolicy(네임스페이스)와 getAutoScalePolicy / removeAutoScalePolicy(토픽) 메서드를 사용해요.
자동 확장 비활성화 (Disable auto-scaling)
토픽을 수동 분할/병합으로만 운영하려면 클러스터 전체에 scalableTopicAutoScaleEnabled=false를 설정하거나, 네임스페이스 또는 토픽 수준에서 enabled=false 재정의를 적용해요. 그러면 컨트롤러가 레이아웃을 건드리지 않고 split-segment / merge-segments로 직접 운영해요.
일반 토픽 마이그레이션 (Migrate a regular topic)
기존의 파티션 또는 비-파티션 토픽을 데이터 복사 없이 제자리에서 확장 가능한 토픽으로 마이그레이션할 수 있어요.
bin/pulsar-admin scalable-topics migrate my-tenant/my-namespace/my-topic
레거시(비-V5) 클라이언트가 아직 연결되어 있으면 --force를 전달하지 않는 한 마이그레이션이 거부돼요. 마이그레이션은 일방향이에요 — 확장 가능한 토픽을 다시 되돌릴 수 없어요. 클라이언트를 먼저 업그레이드하는 권장 순서를 포함한 전체 워크스루는 마이그레이션 가이드에서 다뤄요.
확장 가능한 토픽 삭제 (Delete a scalable topic)
bin/pulsar-admin scalable-topics delete my-tenant/my-namespace/my-topic
토픽에 활성 구독이 있더라도 삭제하려면 --force를 전달해요.
REST API 참고서 (REST API reference)
OpenAPI documentation
모든 엔드포인트는 /admin/v2/scalable 아래에 있고 tenant, namespace, 그리고(list 제외)topic을 경로 파라미터로 받아요.
| Method & path | Operation |
|---|---|
GET /{tenant}/{namespace} |
네임스페이스의 확장 가능한 토픽 나열 |
PUT /{tenant}/{namespace}/{topic} |
확장 가능한 토픽 생성 |
GET /{tenant}/{namespace}/{topic} |
토픽 메타데이터(세그먼트 DAG) 가져오기 |
GET /{tenant}/{namespace}/{topic}/stats |
집계 통계 가져오기 |
DELETE /{tenant}/{namespace}/{topic} |
확장 가능한 토픽 삭제 |
POST /{tenant}/{namespace}/{topic}/migrate |
일반 토픽을 확장 가능으로 마이그레이션 |
POST /{tenant}/{namespace}/{topic}/split/{segmentId} |
세그먼트 분할 |
POST /{tenant}/{namespace}/{topic}/merge/{segmentId1}/{segmentId2} |
두 인접 세그먼트 병합 |
GET /{tenant}/{namespace}/{topic}/autoScalePolicy |
토픽의 자동 분할/병합 재정의 가져오기 |
POST /{tenant}/{namespace}/{topic}/autoScalePolicy |
토픽의 자동 분할/병합 재정의 설정 |
DELETE /{tenant}/{namespace}/{topic}/autoScalePolicy |
토픽의 자동 분할/병합 재정의 제거 |
PUT /{tenant}/{namespace}/{topic}/subscriptions/{subscription} |
구독 생성 |
DELETE /{tenant}/{namespace}/{topic}/subscriptions/{subscription} |
구독 삭제 |
POST /{tenant}/{namespace}/{topic}/subscriptions/{subscription}/seek |
구독을 타임스탬프로 seek |
POST /{tenant}/{namespace}/{topic}/subscriptions/{subscription}/skip-all |
구독의 백로그 정리 |
더 알아보기 (Learn more)
- 확장 가능한 토픽의 배경 개념은 Scalable topics 문서를 참고해요.
- V5 API 클라이언트로 produce·consume하는 방법은 클라이언트 문서를 참고해요.
- 일반 토픽을 마이그레이션하는 전체 순서는 마이그레이션 가이드를 참고해요.
- REST API 전체 엔드포인트는 /admin/v2/scalable 문서와 OpenAPI 스펙을 참고해요.