티어드 스토리지 설정

티어드 스토리지 설정 (Tiered Storage Configs)

티어드 스토리지(Tiered Storage)는 로컬 디스크뿐 아니라 외부 원격 저장소(예: 오브젝트 스토리지)까지 데이터를 계층적으로 저장하는 기능이에요. 이 문서는 그와 관련된 브로커·매니저 설정을 정리해요.

출처: 문서

본문

아래는 티어드 스토리지 설정 항목들이에요.

• log.local.retention.bytes — 파티션의 로컬 로그 세그먼트가 삭제 대상이 되기 전까지 커질 수 있는 최대 크기. 기본값 -2는 log.retention.bytes 값을 사용하라는 뜻이에요. 유효 값은 항상 log.retention.bytes 값보다 작거나 같아야 해요.
  • 유형: long / 기본값: -2 / 유효 값: [-2,...] / 중요도: medium
• log.local.retention.ms — 로컬 로그 세그먼트가 삭제 대상이 되기 전까지 보관하는 밀리초 수. 기본값 -2는 log.retention.ms 값을 사용하라는 뜻이에요. 유효 값은 항상 log.retention.ms 값보다 작거나 같아야 해요.
  • 유형: long / 기본값: -2 / 유효 값: [-2,...] / 중요도: medium
• remote.fetch.max.wait.ms — 원격 파티션을 포함한 fetch 요청에 응답하기 전에 서버가 기다리는 최대 시간. 모든 원격 파티션 페치가 성공했거나, 실패했거나, 이 타임아웃을 초과한 뒤에만 요청에 응답한다는 점을 알아두는 게 중요해요.
  • 유형: int / 기본값: 500 / 유효 값: [1,...] / 중요도: medium
• remote.list.offsets.request.timeout.ms — 원격 list offsets 요청이 완료되기를 서버가 기다리는 최대 시간.
  • 유형: long / 기본값: 30000 (30초) / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.copier.thread.pool.size — 세그먼트를 복사하는 작업을 스케줄링하는 데 쓰는 스레드 풀 크기.
  • 유형: int / 기본값: 10 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.copy.max.bytes.per.second — 초당 로컬 저장소에서 원격 저장소로 복사할 수 있는 최대 바이트 수. 로컬에서 원격으로 복사되는 모든 파티션에 대한 전역 제한이에요. 기본값은 Long.MAX_VALUE로, 초당 복사 바이트 수 제한이 없음을 뜻해요.
  • 유형: long / 기본값: 9223372036854775807 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.copy.quota.window.num — 원격 복사 쿼터(할당량) 관리를 위해 메모리에 보관할 샘플 수. 기본값 11은 10개의 완전한 윈도우 + 1개의 현재 윈도우를 뜻해요.
  • 유형: int / 기본값: 11 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.copy.quota.window.size.seconds — 원격 복사 쿼터 관리를 위한 각 샘플의 시간 간격. 기본값은 1초.
  • 유형: int / 기본값: 1 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.expiration.thread.pool.size — 만료된 원격 로그 세그먼트를 정리하는 작업을 스케줄링하는 데 쓰는 스레드 풀 크기.
  • 유형: int / 기본값: 10 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.fetch.max.bytes.per.second — 초당 원격 저장소에서 로컬 저장소로 가져올 수 있는 최대 바이트 수. 원격에서 로컬로 가져오는 모든 파티션에 대한 전역 제한이에요. 기본값은 Long.MAX_VALUE로, 제한이 없음을 뜻해요.
  • 유형: long / 기본값: 9223372036854775807 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.fetch.quota.window.num — 원격 fetch 쿼터 관리를 위해 메모리에 보관할 샘플 수. 기본값 11은 10개의 완전한 윈도우 + 1개의 현재 윈도우를 뜻해요.
  • 유형: int / 기본값: 11 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.fetch.quota.window.size.seconds — 원격 fetch 쿼터 관리를 위한 각 샘플의 시간 간격. 기본값은 1초.
  • 유형: int / 기본값: 1 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.follower.thread.pool.size — 팔로워 파티션의 가장 높게 업로드된 원격 오프셋을 읽는 팔로워 작업을 스케줄링하는 데 쓰는 스레드 풀 크기.
  • 유형: int / 기본값: 2 / 유효 값: [1,...] / 중요도: medium
• remote.log.manager.thread.pool.size — 팔로워 파티션의 가장 높게 업로드된 원격 오프셋을 읽는 팔로워 작업을 스케줄링하는 데 쓰는 스레드 풀 크기. 이 구성은 4.2부터 비권장(deprecated)이며, 대신 remote.log.manager.follower.thread.pool.size를 사용해요.
  • 유형: int / 기본값: 2 / 유효 값: [1,...] / 중요도: medium
• remote.log.metadata.manager.class.name — RemoteLogMetadataManager 구현의 완전한(fully qualified) 클래스 이름.
  • 유형: string / 기본값: org.apache.kafka.server.log.remote.metadata.storage.TopicBasedRemoteLogMetadataManager / 유효 값: 비어 있지 않은 문자열 / 중요도: medium
• remote.log.metadata.manager.class.path — RemoteLogMetadataManager 구현의 클래스 경로. 지정하면 RemoteLogMetadataManager 구현과 그 의존 라이브러리를 Kafka 브로커 클래스 경로보다 먼저 이 클래스 경로를 검색하는 전용 클래스로더로 로드해요. 문법은 표준 Java 클래스 경로 문자열과 동일해요.
  • 유형: string / 기본값: null / 유효 값: — / 중요도: medium
• remote.log.metadata.manager.impl.prefix — RemoteLogMetadataManager 구현에 전달할 속성에 붙는 접두사. 예를 들어 이 값은 rlmm.config.이 될 수 있어요.
  • 유형: string / 기본값: rlmm.config. / 유효 값: 비어 있지 않은 문자열 / 중요도: medium
• remote.log.metadata.manager.listener.name — RemoteLogMetadataManager 구현이 필요하면 연결할 로컬 브로커의 리스너 이름.
  • 유형: string / 기본값: null / 유효 값: 비어 있지 않은 문자열 / 중요도: medium
• remote.log.reader.max.pending.tasks — 원격 로그 리더 스레드 풀 태스크 큐 최대 크기. 큐가 가득 차면 fetch 요청이 오류로 응답돼요.
  • 유형: int / 기본값: 100 / 유효 값: [1,...] / 중요도: medium
• remote.log.reader.threads — 원격 로그 읽기를 처리하기 위해 할당된 스레드 풀 크기.
  • 유형: int / 기본값: 10 / 유효 값: [1,...] / 중요도: medium
• remote.log.storage.manager.class.name — RemoteStorageManager 구현의 완전한 클래스 이름.
  • 유형: string / 기본값: null / 유효 값: 비어 있지 않은 문자열 / 중요도: medium
• remote.log.storage.manager.class.path — RemoteStorageManager 구현의 클래스 경로. 지정하면 RemoteStorageManager 구현과 그 의존 라이브러리를 Kafka 브로커 클래스 경로보다 먼저 이 클래스 경로를 검색하는 전용 클래스로더로 로드해요. 문법은 표준 Java 클래스 경로 문자열과 동일해요.
  • 유형: string / 기본값: null / 유효 값: — / 중요도: medium
• remote.log.storage.manager.impl.prefix — RemoteStorageManager 구현에 전달할 속성에 붙는 접두사. 예를 들어 이 값은 rsm.config.이 될 수 있어요.
  • 유형: string / 기본값: rsm.config. / 유효 값: 비어 있지 않은 문자열 / 중요도: medium
• remote.log.storage.system.enable — 브로커에서 티어드 스토리지 기능을 활성화할지 여부. true면 브로커가 티어드 스토리지 기능에 필요한 모든 서비스를 시작해요.
  • 유형: boolean / 기본값: false / 유효 값: — / 중요도: medium
• remote.log.index.file.cache.total.size.bytes — 원격 저장소에서 가져온 인덱스 파일을 로컬 저장소에 저장하기 위해 할당한 공간의 총 크기.
  • 유형: long / 기본값: 1073741824 (1 gibibyte) / 유효 값: [1,...] / 중요도: low
• remote.log.manager.task.interval.ms — 원격 로그 매니저가 세그먼트 복사, 원격 로그 세그먼트 정리 같은 예약 작업을 실행하는 간격.
  • 유형: long / 기본값: 30000 (30초) / 유효 값: [1,...] / 중요도: low
• remote.log.metadata.custom.metadata.max.bytes — 브로커가 원격 스토리지 플러그인으로부터 받아들일 커스텀 메타데이터의 최대 크기(바이트). 커스텀 메타데이터가 이 한도를 넘으면 갱신된 세그먼트 메타데이터는 저장되지 않고, 복사된 데이터는 삭제가 시도되며, 해당 토픽-파티션의 원격 복사 작업은 오류와 함께 중단돼요.
  • 유형: int / 기본값: 128 / 유효 값: [0,...] / 중요도: low

RLMM 설정 (RLMM Configs)

아래는 RemoteLogMetadataManager의 기본 구현인 TopicBasedRemoteLogMetadataManager의 설정이에요. 여기의 모든 설정은 remote.log.metadata.manager.impl.prefix로 정의된 접두사로 시작해야 해요. 예를 들어 rlmm.config.remote.log.metadata.consume.wait.ms처럼요.

• remote.log.metadata.consume.wait.ms — 로컬 컨슈머가 발행된 이벤트를 받을 때까지 기다리는 시간(밀리초).
  • 유형: long / 기본값: 120000 (2분) / 유효 값: [0,...] / 중요도: low
• remote.log.metadata.initialization.retry.interval.ms — RemoteLogMetadataManager 리소스 초기화를 재시도하는 간격(밀리초).
  • 유형: long / 기본값: 100 / 유효 값: [0,...] / 중요도: low
• remote.log.metadata.initialization.retry.max.timeout.ms — RemoteLogMetadataManager 리소스 초기화를 재시도하는 최대 시간(밀리초). TopicBasedRemoteLogMetadataManager 초기화의 경우, 이 로컬 브로커가 요청 처리 준비가 된 후(주로 메타데이터가 내부 토픽으로 로컬에 저장될 때 로컬 클러스터가 준비되도록 보장) 타이머가 시작돼요. 이 타임아웃 안에 초기화가 실패하면 이 브로커 프로세스는 종료돼요.
  • 유형: long / 기본값: 120000 (2분) / 유효 값: [0,...] / 중요도: low
• remote.log.metadata.topic.min.isr — 원격 로그 메타데이터 토픽에 대한 쓰기를 승인해야 하는 최소 복제본 수.
  • 유형: short / 기본값: 2 / 유효 값: [1,...] / 중요도: low
• remote.log.metadata.topic.num.partitions — 원격 로그 메타데이터 토픽의 파티션 수.
  • 유형: int / 기본값: 50 / 유효 값: [1,...] / 중요도: low
• remote.log.metadata.topic.replication.factor — 원격 로그 메타데이터 토픽의 복제 팩터.
  • 유형: short / 기본값: 3 / 유효 값: [1,...] / 중요도: low
• remote.log.metadata.topic.retention.ms — 원격 로그 메타데이터 토픽의 보존 기간(밀리초). 기본값은 -1로 무제한을 뜻해요. 사용자는 용도에 따라 이 값을 구성할 수 있어요. 데이터 손실을 피하려면 이 값은 클러스터에서 티어드 스토리지가 활성화된 어떤 토픽의 최대 보존 기간보다 커야 해요.
  • 유형: long / 기본값: -1 / 유효 값: — / 중요도: low

TopicBasedRemoteLogMetadataManager 구현은 내부 토픽 __remote_log_metadata를 위해 admin, producer, consumer 클라이언트를 만들어야 해요. 클라이언트 유형별로 다음 구성 속성을 사용해 추가 설정을 제공할 수 있어요.

# Configs for admin, producer, and consumer clients
<rlmm.prefix>.remote.log.metadata.common.client.<kafka.property> = <value>

# Configs only for admin client
<rlmm.prefix>.remote.log.metadata.admin.<kafka.property> = <value>

# Configs only for producer client
<rlmm.prefix>.remote.log.metadata.producer.<kafka.property> = <value>

# Configs only for consumer client
<rlmm.prefix>.remote.log.metadata.consumer.<kafka.property> = <value>

더 알아보기 (Learn more)

• 티어드 스토리지는 로컬 저장소와 원격 저장소를 함께 쓰는 기능이라서, remote.log.storage.system.enable을 켜고 RemoteStorageManager·RemoteLogMetadataManager 구현을 연결해야 해요.
• 로컬 보존(log.local.retention.ms/bytes)은 원격 보존보다 짧게 잡는 게 원칙이에요.