아카이브 스토어 및 서비스 실행하기

The Archival Store and Service are part of the Sui data access infrastructure. The stack provides long-term storage and low-latency point lookups of historical onchain data through a gRPC service backed by Google Cloud Bigtable. This stack is optimized for operators and data providers who need to serve historical transactions, checkpoints, objects, and epoch data beyond the retention horizon of full nodes or indexer databases.

The Archival Service exposes the same gRPC LedgerService API as a Sui full node, so existing gRPC clients can query it by changing the endpoint. The service is powered by an indexer (sui-kvstore-alt) that reads checkpoints from the remote checkpoint store and writes processed data to Bigtable, and a gRPC server (sui-kv-rpc) that reads from Bigtable to serve client requests.

스택에 대한 자세한 내용은 아카이브 스토어 및 서비스를 참조하라.

아키텍처 개요

이 스택은 세 가지 구성 요소로 이루어진다:

1. Google Cloud Bigtable: 11개 테이블에 걸쳐 모든 과거 chain 데이터를 저장하는 백엔드 스토어이다.
2. sui-kvstore-alt (인덱서): remote 체크포인트 store에서 체크포인트를 읽고 처리된 데이터를 Bigtable에 기록한다.
3. sui-kv-rpc (아카이브 서비스): Bigtable에서 데이터를 읽고 클라이언트에 LedgerService API를 노출하는 gRPC 서버이다.

Prerequisites

• Bigtable API가 활성화된 Google Cloud Platform(GCP) 프로젝트.
• 두 개의 GCP 서비스 계정:
  • 인덱서용 읽기/쓰기 계정. roles/bigtable.user가 필요하다(인덱서는 파이프라인 데이터를 기록하고 자체 워터마크도 읽는다).
  • gRPC 서비스용 읽기 전용 계정. roles/bigtable.reader가 필요하다.
• 대상 네트워크용 Sui 체크포인트 bucket 접근:
  • Mainnet fallback endpoint: 최근 30일 전용 https://checkpoints.mainnet.sui.io.
  • Mainnet full-history backfill bucket: --remote-store-gcs mysten-mainnet-checkpoints-use4를 통한 gs://mysten-mainnet-checkpoints-use4. 이 bucket은 Requester Pays가 활성화되어 있다.
  • Testnet endpoint: 전체 이력을 제공하는 https://checkpoints.testnet.sui.io.
• gRPC가 활성화된 풀 노드. 설정 방법은 Sui 풀 노드 구성을 참조하라. 초기 백필 이후에는 더 낮은 지연 시간을 위해 bucket을 폴링하는 대신 풀 노드에서 체크포인트를 스트리밍할 수 있다. Steady-state operation을 참조하라.

인증

인덱서와 gRPC 서비스는 모두 Application Default Credentials (ADC)를 사용해 GCP에 인증한다. 동일한 자격 증명을 Bigtable 접근과 Google Cloud 스토리지(GCS) 체크포인트 bucket 읽기에 함께 사용한다.

Google Kubernetes Engine(GKE)에서: Workload Identity를 사용해 pod의 Kubernetes 서비스 계정을 GCP 서비스 계정에 바인딩하라. 키나 환경 변수는 필요 없으며, SDK가 metadata server에서 토큰을 자동으로 가져온다.

GKE 외부에서: GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 서비스 계정 JSON 키 파일 경로로 설정하라.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

공개 HTTPS checkpoint endpoint는 최근 30일 checkpoint만 보존한다. Mainnet에서 30일보다 오래된 backfill에는 --remote-store-gcs mysten-mainnet-checkpoints-use4를 사용한다. 이 bucket은 Requester Pays가 활성화되어 있다. 유효한 credential과 billing project로 --remote-store-gcs를 사용하면 throttling을 피할 수 있으며, 전체 이력 backfill에 지원되는 경로이다.

Bigtable 설정

Bigtable instance 생성

GCP 프로젝트에 Bigtable instance를 생성하라. 자세한 절차는 Bigtable documentation을 참조하라.

주요 결정 사항은 다음과 같다:

설정	권장 사항
스토리지 유형	SSD가 필요하다. HDD는 테스트되지 않았으며 권장하지 않는다.
노드 수	Mysten Labs는 현재 Mainnet에서 5개, Testnet에서 2개 노드를 시작점으로 운영한다. 백필에는 15개 노드까지 scale up하라. 정상 상태에서 필요한 노드 수는 read traffic에 따라 달라진다. autoscaling을 활성화하거나 CPU utilization을 모니터링하면서 수동으로 scale하라.

복제: 단일 클러스터 instance를 기본값으로 권장한다. 여러 리전에 read traffic을 제공해야 한다면 다른 zone에 클러스터를 추가할 수 있다. Bigtable은 클러스터 간에 데이터를 자동으로 복제하므로, 각 리전마다 별도의 indexing stack을 운영하지 않아도 추가 리전에서 저지연 읽기를 제공할 수 있다. 대신 스토리지 비용은 클러스터 수에 비례해 증가한다(데이터가 각 클러스터에 전체 복제되기 때문이다). 단일 클러스터 instance에는 app profile에서 single-클러스터 routing을 사용하고, multi-클러스터 routing이 필요한 경우에는 Bigtable이 가장 가까운 클러스터로 요청을 라우팅하도록 설정하라.

테이블 생성

다음 11개 테이블을 생성하라. 각 테이블은 sui라는 단일 column family를 가지며, 최신 cell version만 유지하는 GC policy를 사용한다:

테이블	설명
checkpoints	체크포인트 요약, 서명, 내용
checkpoints_by_digest	digest 기준 체크포인트 조회
transactions	트랜잭션 데이터, effects, 이벤트, balance changes
objects	객체 ID와 version을 키로 하는 객체 데이터
epochs	system state를 포함한 에포크 시작 및 종료 데이터
watermark_alt	내부 인덱서 워터마크 추적
protocol_configs	에포크별 프로토콜 구성
packages	원본 ID와 version을 키로 하는 패키지 메타데이터
packages_by_id	ID 기준 패키지 조회
packages_by_checkpoint	체크포인트 기준 패키지 조회
system_packages	system 패키지 데이터

cbt CLI 사용 예시는 다음과 같다:

for table in checkpoints checkpoints_by_digest transactions objects epochs \
    watermark_alt protocol_configs packages packages_by_id \
    packages_by_checkpoint system_packages; do
  cbt -project <GCP_PROJECT> -instance <INSTANCE_ID> createtable "$table"
  cbt -project <GCP_PROJECT> -instance <INSTANCE_ID> createfamily "$table" sui
  cbt -project <GCP_PROJECT> -instance <INSTANCE_ID> setgcpolicy "$table" sui maxversions=1
done

스토리지 요구 사항

아래 스토리지 footprint 추정치는 2026년 3월 초 기준 네트워크를 바탕으로 한 값이다. 이 수치는 방향성을 보여 주는 참고치이며, 네트워크 활동이 증가하면 함께 커진다.

Mainnet(Genesis부터 전체 이력):

테이블	크기
transactions	8.1 TB
objects	4.4 TB
checkpoints	832 GB
checkpoints_by_digest	15 GB
watermark_alt	1.5 GB
epochs	83 MB
packages	TBD (아직 백필되지 않음)
packages_by_id	TBD (아직 백필되지 않음)
packages_by_checkpoint	TBD (아직 백필되지 않음)
protocol_configs	TBD (아직 백필되지 않음)
system_packages	TBD (아직 백필되지 않음)
합계	~13.3 TB

Testnet(Genesis부터 전체 이력):

테이블	크기
transactions	2.5 TB
objects	1.2 TB
checkpoints	514 GB
checkpoints_by_digest	18 GB
watermark_alt	12 MB
epochs	97 MB
packages	TBD (아직 백필되지 않음)
packages_by_id	TBD (아직 백필되지 않음)
packages_by_checkpoint	TBD (아직 백필되지 않음)
protocol_configs	TBD (아직 백필되지 않음)
system_packages	TBD (아직 백필되지 않음)
합계	~4.3 TB

스토리지의 대부분은 transactions와 objects 테이블이 차지한다. packages, packages_by_id, packages_by_checkpoint, protocol_configs, system_packages 파이프라인은 새로 추가되었고 아직 백필되지 않았다. 백필이 완료되면 이들이 차지하는 스토리지 비중도 증가한다. 증가율은 네트워크 트랜잭션 volume에 따라 달라진다.

확장

Bigtable은 수동과 자동 node scaling을 모두 지원한다. Mysten Labs는 더 나은 운영 제어를 위해 CPU 모니터링과 함께 수동 scaling을 사용하지만, 운영 개입을 줄이고 싶다면 autoscaling도 합리적인 선택이다.

모니터링할 핵심 임계값은 다음과 같다:

• CPU utilization: 60%(혼합 read/write) 또는 90%(write-only)를 지속적으로 넘으면 scale up하라.
• 스토리지 utilization: 각 SSD 노드는 최대 5 TB를 지원하지만, Google은 급증 상황을 수용하기 위해 70%(node당 3.5 TB) 미만 유지를 권장한다. 클러스터가 compute와 스토리지 요구 사항을 모두 충족할 만큼 충분한 노드를 갖추도록 하라.

백업 정책

재해 복구를 위해 자동 백업을 구성하라. 일일 백업과 7일 보존 기간이 합리적인 기본값이다. 설정 방법은 Bigtable backup documentation을 참조하라.

인덱서 설정

인덱서(sui-kvstore-alt)는 remote 체크포인트 store에서 체크포인트를 읽고 12개의 병렬 파이프라인을 통해 데이터를 Bigtable에 기록한다.

하드웨어 요구 사항

정상 상태(네트워크 tip 기준):

• CPU: instance당 1 core(보수적 수치이며, 관측된 사용량은 약 0.1-0.2 cores이다)
• Memory: instance당 1 GB(보수적 수치이며, 관측된 사용량은 약 50 MB이다)

백필:

• CPU: 16 cores
• Memory: 32 GB

sui-kvstore-alt 실행

sui-kvstore-alt \
    --config <CONFIG_FILE> \
    --chain <CHAIN> \
    <INSTANCE_ID> \
    --remote-store-gcs <REMOTE_STORE_GCS_BUCKET>

CLI parameter	필수	설명
--config	아니오	TOML 구성 파일 경로이다. 생략하면 프레임워크 기본값을 사용한다. Indexer 구성을 참조하라.
<INSTANCE_ID>	예	Bigtable instance ID이다.
--chain	예	chain 식별자이다. mainnet, testnet, unknown 중 하나이다.
--remote-store-gcs	소스 1개 필수	체크포인트를 가져올 GCS bucket 이름이다(백필 권장). 다른 소스 플래그와 상호 배타적이다.
--remote-store-url	소스 1개 필수	remote 체크포인트 store의 HTTPS URL이다(--remote-store-gcs의 대안). 다른 소스 플래그와 상호 배타적이다.
--rpc-api-url	소스 1개 필수	체크포인트를 가져올 풀 노드 gRPC URL이다(정상 상태용). 다른 소스 플래그와 상호 배타적이다.
--streaming-url	아니오	live 체크포인트 스트리밍용 풀 노드 gRPC URL이다. 네트워크 tip에서 가장 낮은 지연 시간을 위해 --rpc-api-url과 함께 사용한다.
--bigtable-project	아니오	GCP 프로젝트 ID이다. 기본값은 서비스 계정 자격 증명과 연결된 프로젝트이다.
--app-profile-id	아니오	라우팅용 Bigtable app profile ID이다.
--write-legacy-data	아니오	설정하지 말라. deprecated 데이터 format 쓰기를 활성화하는 옵션이다.
--first-checkpoint	아니오	indexing을 시작할 체크포인트이다. 기본값은 0(Genesis)이다.
--last-checkpoint	아니오	indexing을 중지할 체크포인트이다. 범위가 제한된 백필 작업에 유용하다.
--metrics-address	아니오	Prometheus 메트릭 bind 주소이다. 기본값: 0.0.0.0:9184.

예시(GCS bucket에서 백필)

sui-kvstore-alt \
    --config kvstore.toml \
    --chain mainnet \
    my-bigtable-instance \
    --remote-store-gcs mysten-mainnet-checkpoints-use4

예시(fullnode에서 steady-state)

sui-kvstore-alt \
    --chain mainnet \
    my-bigtable-instance \
    --rpc-api-url http://my-fullnode:9000 \
    --streaming-url http://my-fullnode:9000

인덱서 구성

인덱서는 --config를 통해 선택적인 TOML 구성 파일을 받는다. chain tip indexing에서는 프레임워크 기본값이 좋은 출발점이므로, 플래그를 완전히 생략해도 된다. 구성 튜닝은 주로 백필 rate limit sizing에 설명된 백필 상황에서 필요하다.

최상위 옵션 설정

옵션	기본값	설명
total-max-rows-per-second	unlimited	모든 파이프라인이 공유하는 전역 속도 제한(rows/sec)이다. 백필 중 Bigtable에 과도한 부하를 주지 않도록 이 값을 설정하라.
max-rows-per-second	unlimited	파이프라인별 기본 속도 제한(rows/sec)이다. total-max-rows-per-second와 함께 모두 적용되므로, 특정 파이프라인이 다른 파이프라인을 굶기지 않도록 제한을 나눌 수 있다. 실제로는 대개 필요하지 않으므로 생략해도 된다.
bigtable-connection-pool-size	—	Deprecated. 대신 [bigtable-pool] section을 사용한다. 설정하면 bigtable-pool.initial-pool-size를 override한다.
bigtable-channel-timeout-ms	60000	Bigtable gRPC 호출에 대한 channel 수준 timeout(ms)이다.

Connection pool 설정([bigtable-pool])

Indexer는 load에 따라 자동으로 scaling되는 Bigtable용 gRPC channel dynamic pool을 관리한다. Pool은 initial-pool-size channel에서 시작해 channel당 in-flight RPC 수를 기준으로 min-pool-size와 max-pool-size 사이에서 scaling된다. Channel은 GFE가 disconnect하기 전(약 60분) 주기적으로 refresh된다.

옵션	기본값	설명
initial-pool-size	10	시작 시 생성할 gRPC channel 수이다.
min-pool-size	1	Pool이 유지하는 최소 channel 수이다.
max-pool-size	200	Pool이 scale할 수 있는 최대 channel 수이다.
min-rpcs-per-channel	5	이 값보다 평균 channel load가 낮으면 pool이 scale down을 고려한다.
max-rpcs-per-channel	50	이 값보다 평균 channel load가 높으면 pool이 scale up한다.
max-resize-delta	2	단일 scale-down에서 제거할 최대 channel 수이다. Scale-up에는 제한이 없다.
downscale-threshold	3	Scale down 전 필요한 연속 low-load observation 수이다.
maintenance-interval-ms	60000	Maintenance cycle(resize + channel refresh) 사이의 millisecond 간격이다.
refresh-age-ms	2700000	Channel이 refresh 대상이 되기 전까지의 age millisecond이다(45분).
refresh-jitter-ms	300000	교체 시점이 몰리지 않도록 refresh age에 더하는 random jitter이다(5분).

기본값은 일반적으로 잘 동작하며 별도 구성은 필요 없다.

Committer 설정([committer])

이 설정은 각 파이프라인이 Bigtable에 데이터를 flush하는 방식을 제어한다. 최상위에 설정하면 모든 파이프라인에 적용되고, 파이프라인별로 override할 수도 있다(아래 참조).

옵션	기본값	설명
write-concurrency	5	파이프라인당 동시 write task 수이다. 백필 중 고처리량 파이프라인에서는 값을 늘려라.
collect-interval-ms	500	버퍼링된 row를 flush하는 주기(ms)이다.
watermark-interval-ms	500	파이프라인 워터마크를 갱신하는 주기(ms)이다.

파이프라인별 override ([pipeline.<name>])

12개 파이프라인 각각은 전역 설정을 override할 수 있다. 파이프라인 수준 옵션은 [pipeline.<name>], committer override는 [pipeline.<name>.committer]를 사용하라.

[pipeline.objects]
max-rows-per-second = 50000

[pipeline.objects.committer]
write-concurrency = 40

옵션	설명
max-rows	이 파이프라인의 Bigtable batch당 최대 row 수이다.
max-rows-per-second	전역 max-rows-per-second를 override하는 파이프라인별 속도 제한이다.
committer.*	모든 committer 필드(write-concurrency, collect-interval-ms, watermark-interval-ms)를 파이프라인별로 설정할 수 있다.

15-node 클러스터에 권장되는 백필 구성은 백필 rate limit sizing을 참조하라.

추가적인 고급 옵션(channel size, fanout concurrency, backpressure threshold, ingestion setting 등)도 제공되지만, 드물게만 튜닝이 필요하다. 전체 참조는 파이프라인 architecture performance tuning을 참조하라.

파이프라인 목록

인덱서는 12개의 파이프라인을 병렬로 실행한다. 아카이브 서비스의 전체 기능을 사용하려면 모든 파이프라인이 필요하다:

파이프라인	대상 테이블	설명
kvstore_checkpoints	checkpoints	체크포인트 요약, 서명, 내용
kvstore_checkpoints_by_digest	checkpoints_by_digest	체크포인트 digest와 sequence number의 매핑
kvstore_transactions	transactions	effects, 이벤트, balance changes를 포함한 트랜잭션
kvstore_objects	objects	각 version에서 생성된 output 객체 데이터
kvstore_epochs_start	epochs	system state와 가스 가격를 포함한 에포크 시작 데이터
kvstore_epochs_end	epochs	에포크 종료 데이터
kvstore_protocol_configs	protocol_configs	에포크별 프로토콜 구성 스냅샷
kvstore_epoch_legacy	epochs	legacy 에포크 데이터 format(--write-legacy-data 필요)
kvstore_packages	packages	원본 패키지 ID와 version을 키로 하는 패키지 메타데이터
kvstore_packages_by_id	packages_by_id	패키지 ID 기준 패키지 조회
kvstore_packages_by_checkpoint	packages_by_checkpoint	각 체크포인트에서 게시된 패키지
kvstore_system_packages	system_packages	system 패키지 데이터

백필 실행

Genesis부터 indexing하려면 --first-checkpoint 없이 인덱서를 시작하라. 15-node SSD 클러스터와 16 CPU 인덱서 기준으로 Mainnet 전체 백필에는 약 2-3일이 걸린다.

백필에는 단일 인덱서 instance를 사용하라. 하나의 instance만으로도 15-node 클러스터를 완전히 포화시킬 만큼의 부하를 만들 수 있다. 16 CPU / 15-node 구성은 Mysten Labs가 테스트한 최대 규모이다. 더 큰 instance type과 클러스터 크기도 동작할 수 있지만, 아직 확인되지 않은 소프트웨어 병목에 부딪힐 수 있다.

권장 백필 전략

1. 백필을 시작하기 전에 Bigtable 클러스터를 15개 node로 scale up하라.
2. 더 큰 머신(16 CPU / 32 GB RAM)에서 인덱서 instance 하나를 실행하고, 체크포인트 bucket을 데이터 소스로 사용하면서 공격적인 속도 제한(약 150,000 rows/sec)을 설정하라.
3. 백필이 네트워크 tip에 도달하면 정상 상태로 전환하라(아래 Steady-state operation 참조).
4. Bigtable 클러스터를 5개 node로 scale down하라.

이후에는 클러스터 CPU utilization을 모니터링하면서 필요에 따라 node 수를 조정하라. Bigtable autoscaling을 사용해도 되고, 직접 모니터링하면서 수동으로 scale해도 된다.

백필 rate limit sizing

TOML 구성에 설정하는 속도 제한은 Bigtable 클러스터 크기에 맞춰야 한다. 각 Bigtable SSD 노드는 CPU utilization 1%당 약 111 rows/sec를 유지할 수 있다. Google 권장 목표는 다음과 같다:

• concurrent read traffic이 없는 write-only 백필은 CPU 90%
• 백필 중 클러스터가 읽기도 함께 처리한다면 CPU 60%

시나리오	목표 CPU	node당 rows/sec	5 nodes	10 nodes	15 nodes
Write-only 백필	90%	~10,000	~50,000	~100,000	~150,000
읽기를 제공하면서 백필	60%	~6,700	~33,500	~67,000	~100,000

이 수치는 가이드라인이다. 새 write-only 클러스터를 백필하는 경우 위 표의 값으로 속도 제한을 설정할 수 있다. 이미 read traffic을 처리 중인 클러스터라면 더 낮은 값에서 시작하고, CPU utilization을 모니터링하면서 점진적으로 속도 제한을 올려라.

이에 맞춰 TOML 구성에서 total-max-rows-per-second를 설정하라. 다음 내용을 백필 구성 파일(예: backfill.toml)로 저장한 뒤 --config backfill.toml로 전달하라. 아래 예시는 15-node write-only 백필을 대상으로 한다.

backfill.toml

# Assumes a 15-node cluster targeting 90% CPU utilization (write-only).
# Scale linearly for smaller clusters, e.g. 50000 for 5 nodes, 100000 for 10.
total-max-rows-per-second = 150000

[pipeline.objects.committer]
write-concurrency = 40

[pipeline.transactions.committer]
write-concurrency = 20

[pipeline.checkpoints.committer]
write-concurrency = 10

[pipeline.checkpoints_by_digest.committer]
write-concurrency = 10

기본 write-concurrency 값은 5이며, 더 작은 파이프라인에는 충분하다. 백필 중에는 고처리량 파이프라인인 objects, transactions, checkpoints, checkpoints_by_digest만 더 높은 concurrency가 필요하다.

체크포인트 범위 sharding

--first-checkpoint와 --last-checkpoint를 사용해 체크포인트 범위를 나누면 여러 인덱서 instance에 걸쳐 백필을 병렬화할 수 있다. 각 instance는 서로 다른 범위를 독립적으로 처리한다.

Steady-state operation

백필이 완료되고 인덱서가 네트워크 tip을 따라잡으면, 가장 낮은 지연 시간을 위해 체크포인트 bucket 대신 풀 노드 스트리밍으로 전환하라. 풀 노드의 gRPC 엔드포인트를 가리키도록 --remote-store-url을 --rpc-api-url과 --streaming-url로 바꾸면 된다.

sui-kvstore-alt \
    --chain mainnet \
    my-bigtable-instance \
    --rpc-api-url http://my-fullnode:9000 \
    --streaming-url http://my-fullnode:9000

--config는 필요 없다. 정상 상태 indexing에는 프레임워크 기본값이면 충분하다. 풀 노드는 gRPC만 활성화되어 있으면 된다. JSON-RPC는 필요 없다. Mysten Labs는 2주 리텐션 기간으로 풀 노드를 운영하며, 백필에만 체크포인트 bucket을 사용한다.

정상 상태에서 속도 제한을 설정하고 싶다면 tradeoff를 고려해야 한다. write 처리량은 chain 자체에 의해 자연스럽게 제한되지만, 인덱서가 중단됐다가 복구되면 풀 노드에서 가능한 한 빠르게 데이터를 따라잡는다. 속도 제한이 없으면 더 빨리 따라잡지만, 오래된 데이터를 기록하는 동안 read 지연 시간에 잠시 영향을 줄 수 있다. 속도 제한이 있으면 read 지연 시간는 안정적이지만 복구 시간이 더 길어진다.

정보

Mysten Labs는 앞으로 공개 체크포인트 bucket에 requester-pays를 활성화할 계획이다. 자체 풀 노드에서 스트리밍하면 이러한 비용을 피할 수 있다.

여러 instance 실행

Bigtable write는 멱등적이므로 여러 인덱서 instance가 동일한 데이터를 안전하게 처리할 수 있다. Mysten Labs는 chain 업데이트가 지연되지 않도록 정상 상태에서 3개의 인덱서 instance를 실행해 rolling deployment를 지원한다.

백필 중에는 단일 instance면 충분하다. 하나의 instance로 15-node 클러스터를 포화시킬 수 있다.

아카이브 서비스 setup 구성

아카이브 서비스(sui-kv-rpc)는 Bigtable에서 데이터를 읽고 LedgerService API를 노출하는 gRPC 서버이다.

리소스 요구 사항은 read traffic에 따라 달라진다. CPU와 memory utilization을 모니터링하면서 그에 맞게 scale하라.

sui-kv-rpc 실행

sui-kv-rpc \
    <INSTANCE_ID> \
    <ADDRESS>

CLI parameter	필수	설명
<INSTANCE_ID>	예	Bigtable instance ID이다.
<ADDRESS>	아니오	gRPC listen 주소이다. 기본값: [::1]:8000.
--credentials	아니오	GCP 서비스 계정 JSON 키 파일 경로이다. 제공하지 않으면 Application Default Credentials를 사용한다.
--tls-cert	아니오	TLS certificate PEM 파일 경로이다.
--tls-key	아니오	TLS 개인 키 PEM 파일 경로이다.
--bigtable-project	아니오	GCP 프로젝트 ID이다. 기본값은 서비스 계정 자격 증명과 연결된 프로젝트이다.
--app-profile-id	아니오	Bigtable app profile ID이다.
--checkpoint-bucket	아니오	전체 체크포인트 데이터용 GCS bucket이다(더 풍부한 체크포인트 응답을 활성화한다).
--bigtable-channel-timeout-ms	아니오	Bigtable gRPC 호출의 channel 수준 timeout(밀리초)이다. 기본값: 60000.
--bigtable-initial-pool-size	아니오	시작 시 생성할 gRPC channel 수이다. 기본값: 10.
--bigtable-min-pool-size	아니오	Pool이 유지하는 최소 channel 수이다. 기본값: 1.
--bigtable-max-pool-size	아니오	Pool이 scale할 수 있는 최대 channel 수이다. 기본값: 200.

예시

sui-kv-rpc \
    my-bigtable-instance \
    "[::]:8000" \
    --credentials /etc/sui-kv-rpc/bigtable-ro-sa.json \
    --tls-cert /secrets/cert.pem \
    --tls-key /secrets/key.pem

gRPC API 설정

아카이브 서비스는 Sui 풀 노드가 노출하는 것과 동일한 LedgerService gRPC API를 구현한다. 기존 gRPC client는 엔드포인트 URL만 바꾸면 아카이브 서비스를 조회할 수 있다.

Method	설명	Batch limit
GetServiceInfo	chain ID, 현재 에포크, 최신 체크포인트, server version을 반환한다.	-
GetObject	ID로 객체를 조회한다. 필요하면 특정 version을 지정할 수 있다.	-
BatchGetObjects	객체 일괄 조회이다. 정확한 version이 필요하다.	1000
GetTransaction	digest로 트랜잭션을 조회한다.	-
BatchGetTransactions	트랜잭션 일괄 조회이다.	200
GetCheckpoint	sequence number 또는 digest로 체크포인트를 조회한다.	-
GetEpoch	에포크 number로 에포크 데이터를 조회한다.	-

모든 method는 응답 크기를 줄이기 위해 read_mask parameter를 통한 필드 masking을 지원한다.

gRPC server reflection은 활성화되어 있으며(v1, v1alpha 모두), grpcurl과 Postman 같은 도구가 API schema를 발견할 수 있다.

헬스 체크

이 서비스는 8081 포트에서 GET /health HTTP 헬스 체크 엔드포인트를 노출한다.

TLS 설정

프로덕션 배포에서는 --tls-cert와 --tls-key를 제공해 TLS를 활성화하라. 서비스는 PEM 형식의 certificate와 개인 키 파일을 기대한다.

모니터링 모니터링

인덱서와 아카이브 서비스는 모두 9184 포트의 /metrics에서 Prometheus 메트릭을 노출한다.

인덱서는 General-purpose Postgres 인덱서와 동일한 indexer 프레임워크 메트릭(ingestion, 파이프라인, 워터마크, commit 메트릭)를 사용하며, kvstore_alt_ prefix와 파이프라인별 label을 추가한다. 이미 Postgres 인덱서 스택을 운영하고 있다면 동일한 dashboard와 alert를 적용할 수 있다.

Prometheus scrape 구성

scrape_configs:
  - job_name: sui-kvstore
    static_configs:
      - targets: ['<INDEXER_HOST>:9184']
  - job_name: sui-kv-rpc
    static_configs:
      - targets: ['<RPC_HOST>:9184']

아카이브 서비스 메트릭

아카이브 서비스는 다음 메트릭을 노출한다:

메트릭	Type	설명
rpc_request_latency	histogram	end-to-end 요청 지연 시간
rpc_requests	counter	status label이 붙은 요청 수
rpc_inflight_requests	gauge	path label이 붙은 동시 진행 중 요청 수
kv_get_latency_ms	histogram	table label이 붙은 batch 요청당 Bigtable read 지연 시간
kv_get_latency_ms_per_key	histogram	table label이 붙은, batch 크기로 나눈 Bigtable read 지연 시간
kv_scan_latency_ms	histogram	table label이 붙은 Bigtable scan 지연 시간
kv_bt_chunk_latency_ms	histogram	table label이 붙은 응답 chunk당 Bigtable 내부 처리 시간
kv_get_success	counter	table label이 붙은 성공한 Bigtable read 수
kv_scan_success	counter	table label이 붙은 성공한 Bigtable scan 수
bt_pool_pool_size	gauge	connection pool의 현재 channel 수
bt_pool_channels_replaced	counter	age refresh로 교체된 총 channel 수
bt_pool_rpcs_completed	counter	pool을 통해 완료된 총 RPC 수
thread_stall_duration_sec	histogram	Tokio thread stall duration

권장 log level

환경	RUST_LOG
프로덕션	info
디버깅	info,sui_kvstore=debug,sui_indexer_alt_framework=debug