원격 스토어 실행하기

원격 스토어는 protobuf로 인코딩된 checkpoint blob을 담는 객체 스토어(S3 또는 GCS)이다. 풀 노드는 여기서 상태 동기화를 위해 읽고, indexer는 백필을 위해 읽는다. sui-checkpoint-blob-indexer는 source에서 체크포인트를 읽고 destination에 압축된 protobuf blob을 기록하여 이 store를 채운다.

아키텍처 개요

Prerequisites

체크포인트 source에 접근할 수 있어야 한다:
- Mysten's public checkpoint endpoints: https://checkpoints.mainnet.sui.io 및 https://checkpoints.testnet.sui.io. Mainnet HTTPS endpoint는 최근 30일 checkpoint만 보존하므로 fallback source로만 사용해야 한다. Testnet은 여전히 전체 이력을 제공한다.
- Mainnet full-history backfill bucket: gs://mysten-mainnet-checkpoints-use4. 이 bucket은 Requester Pays가 활성화되어 있으며 --remote-store-gcs mysten-mainnet-checkpoints-use4로 접근해야 한다.
- Your own 풀 노드: steady-state streaming을 위해 gRPC가 활성화되어 있어야 한다.
쓰기 자격 증명이 있는 destination 객체 스토어(S3 또는 GCS).
sui-checkpoint-blob-indexer 바이너리.

파이프라인

indexer는 세 개의 파이프라인을 실행한다. 활성화해야 하는 것은 앞의 두 개뿐이다:

파이프라인	Output	설명
`checkpoint_blob`	`{seq}.binpb.zst`	protobuf로 인코딩된 checkpoint blob. 이 형식을 사용해야 한다.
`epochs`	`epochs.json`	에포크 경계 체크포인트 sequence number의 정렬된 목록. 필수 metadata이다.
`checkpoint_bcs`	`{seq}.chk`	BCS로 인코딩된 체크포인트. 더 이상 사용되지 않으며 제거 중이다. 이 파이프라인은 활성화하지 말라.

기존 bucket에서 백필

자체 원격 스토어를 채우는 가장 쉬운 방법은 Mysten의 공개 GCS bucket에서 백필하는 것이다. source로 --remote-store-gcs를 사용하고, destination flag(--s3 또는 --gcs)로 자신의 store에 기록한다.

예시: Mysten의 GCS bucket에서 S3 bucket으로 백필(Mainnet)

sui-checkpoint-blob-indexer \
    --pipeline checkpoint_blob --pipeline epochs \
    --remote-store-gcs mysten-mainnet-checkpoints-use4 \
    --s3 my-checkpoint-bucket \
    --compression-level 3

Mainnet bucket은 gs://mysten-mainnet-checkpoints-use4이며 Requester Pays가 활성화되어 있다.

전체 이력 backfill에는 --remote-store-url https://checkpoints.mainnet.sui.io를 사용하지 않는다. 공개 HTTPS endpoint는 최근 30일 checkpoint만 보존한다. Mainnet backfill에는 대신 --remote-store-gcs mysten-mainnet-checkpoints-use4를 사용한다.

정보

gs://mysten-mainnet-checkpoints-use4는 Requester Pays가 활성화되어 있다. 이 bucket에서 읽을 때 credential과 billing project를 구성한다. steady-state의 비용과 지연 시간을 가장 낮추려면 backfill이 완료된 뒤 자체 풀 노드에서 스트리밍한다.

대안: 풀 노드에서 백필

pruning되지 않은 풀 노드가 있다면 bucket 대신 이를 체크포인트 source로 사용할 수 있다:

sui-checkpoint-blob-indexer \
    --pipeline checkpoint_blob --pipeline epochs \
    --rpc-api-url http://my-fullnode:9000 \
    --s3 my-checkpoint-bucket \
    --compression-level 3

Steady-state operation 구성

백필이 네트워크 tip을 따라잡으면 가장 낮은 지연 시간을 위해 풀 노드 gRPC 스트리밍으로 전환한다. 체크포인트를 가져올 때는 --rpc-api-url을, 실시간 스트리밍에는 --streaming-url을 사용한다:

sui-checkpoint-blob-indexer \
    --pipeline checkpoint_blob --pipeline epochs \
    --rpc-api-url http://my-fullnode:9000 \
    --streaming-url http://my-fullnode:9000 \
    --s3 my-checkpoint-bucket \
    --compression-level 3

풀 노드에는 gRPC만 활성화되어 있으면 된다. JSON-RPC는 필요하지 않다.

여러 instance 실행

쓰기 작업은 멱등적이므로 여러 indexer instance가 같은 bucket에 안전하게 기록할 수 있다. 정상 상태에서는 체인의 업데이트를 지연시키지 않고 롤링 배포를 가능하게 하려면 2-3개의 instance를 실행한다. 백필 중에는 instance 하나면 충분하다.

CLI reference 요약

Destination flag(상호 배타적, 하나 필요)

Flag	설명
`--s3 <BUCKET>`	AWS S3에 기록한다. Env: `AWS_ENDPOINT`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`.
`--gcs <BUCKET>`	Google Cloud 스토리지에 기록한다. Env: `GOOGLE_SERVICE_ACCOUNT_PATH`.
`--http <URL>`	HTTP 엔드포인트에 기록한다.

Source flag(상호 배타적, 하나 필요)

Flag	설명
`--remote-store-gcs <BUCKET>`	GCS bucket에서 체크포인트를 가져온다. 백필에 권장된다.
`--remote-store-url <URL>`	HTTPS 원격 스토어 URL에서 체크포인트를 가져온다.
`--remote-store-s3 <BUCKET>`	S3 bucket에서 체크포인트를 가져온다.
`--rpc-api-url <URL>`	풀 노드 gRPC 엔드포인트에서 체크포인트를 가져온다.

기타 flag

Flag	Default	설명
`--config <PATH>`	—	선택적 TOML 구성 파일 경로. 대부분의 배포에는 프레임워크 기본값이면 충분하다. 구성을 참고한다.
`--compression-level <LEVEL>`	없음(압축하지 않음)	Zstd 압축 레벨. 강력히 권장한다. 이 플래그가 없으면 파일은 `.binpb.zst` 대신 `.binpb`로 기록된다. indexer 프레임워크는 원격 스토어에서 읽을 때 `.binpb.zst`를 기대하므로 압축되지 않은 파일은 downstream consumer가 찾지 못한다. `3`이 좋은 기본값이다.
`--streaming-url <URL>`	—	실시간 체크포인트 스트리밍용 풀 노드 gRPC URL. 네트워크 tip에서 가장 낮은 지연 시간을 위해 `--rpc-api-url`과 함께 사용한다.
`--first-checkpoint <N>`	0	인덱싱을 시작할 체크포인트.
`--last-checkpoint <N>`	—	인덱싱을 중지할 체크포인트(포함). 범위가 있는 백필 작업에 유용하다.
`--pipeline <NAME>`	모든 파이프라인	지정한 파이프라인만 실행한다. 반복 지정할 수 있다.
`--request-timeout <DURATION>`	`30s`	객체 스토어 작업에 대한 HTTP 요청 timeout.
`--metrics-address <ADDR>`	`0.0.0.0:9184`	Prometheus 메트릭 바인드 주소.

구성 (TOML)

권장되는 두 개의 파이프라인만 실행하고 deprecated된 BCS 파이프라인을 제외하려면 --pipeline을 사용한다:

--pipeline checkpoint_blob --pipeline epochs

객체 스토어 워크로드에 맞게 committer를 조정하려면 다음 TOML 구성 파일을 --config로 전달한다:

[committer]
write-concurrency = 500
watermark-interval-ms = 120000
watermark-interval-jitter-ms = 120000

write-concurrency: 객체 store에 최대 500개의 동시 쓰기를 허용한다. 스토리지 provider에서 강한 throttling이 관찰되면 이 값을 낮춘다.
watermark-interval-ms: 객체 store의 워터마크 파일에서 hot-키 문제가 발생하지 않도록 프레임워크 기본값보다 워터마크 update 빈도를 낮춘다.
watermark-interval-jitter-ms: 워터마크 interval에 무작위 jitter를 더해 여러 indexer instance를 실행할 때 동시에 같은 키에 기록하지 않도록 한다.

구성 옵션([ingestion], [committer], [pipeline.<name>])은 indexer 프레임워크의 표준 설정과 동일하다. 전체 참조는 파이프라인 architecture performance tuning을 참고한다.

출력 형식

indexer는 destination 객체 store에 다음 파일을 기록한다:

Path	설명
`{seq}.binpb.zst`	Zstd로 압축된 protobuf checkpoint blob(`--compression-level`이 설정된 경우). 기대되는 형식이다.
`{seq}.binpb`	압축되지 않은 protobuf checkpoint blob(`--compression-level`이 없는 경우). 권장되지 않는다. indexer 프레임워크는 원격 스토어에서 수집할 때 `.binpb.zst`를 찾는다.
`epochs.json`	정렬된 에포크 경계 체크포인트 sequence number의 JSON 배열.
`_metadata/watermarks/`	진행 상황을 추적하기 위해 indexer가 사용하는 내부 워터마크 파일.

모니터링

indexer는 port 9184의 /metrics에서 Prometheus 메트릭을 노출하며(--metrics-address로 구성 가능), 메트릭은 checkpoint_blob_ 접두어를 사용한다. indexer는 다른 indexer와 동일한 indexer 프레임워크 메트릭를 사용하며(ingestion, 파이프라인, 워터마크, commit 메트릭), 여기에 파이프라인별 label이 추가된다.

scrape_configs:
  - job_name: sui-checkpoint-blob-indexer
    static_configs:
      - targets: ['<HOST>:9184']

아키텍처 개요​

파이프라인​

기존 bucket에서 백필​

예시: Mysten의 GCS bucket에서 S3 bucket으로 백필(Mainnet)​

대안: 풀 노드에서 백필​

Steady-state operation 구성​

여러 instance 실행​

CLI reference 요약​

Destination flag(상호 배타적, 하나 필요)​

Source flag(상호 배타적, 하나 필요)​

기타 flag​

구성 (TOML)​

출력 형식​

모니터링​