Troubleshooting Sharding

Sharded cluster yang sehat hampir diam: data tersebar, balancer bekerja di latar, query meluncur. Ketika performa menurun, sumbernya hampir selalu berpola dan bisa dilacak dengan alat yang sudah kita kenal — sh.status(), database config, dan explain. Chapter penutup section ini merangkum gejala paling umum dalam satu tabel diagnosis, lalu membedah tiga yang teratas: hotspot, jumbo chunk, dan orphaned documents.

Tabel Diagnosis Cepat #

Gejala	Diagnosis	Tindakan
Tulis menumpuk di satu shard	Shard key monotonic pada ranged sharding	Reshard ke hashed, atau `refineCollectionShardKey`
Chunk terlalu besar dan tak bisa dipindah	Jumbo chunk — cardinality/frequency buruk	`refineCollectionShardKey` atau reshard; cek pengaturan `attemptToBalanceJumboChunks`
Ukuran data antar shard timpang terus	Balancer mati, jendela terlalu sempit, atau zones menahan	Periksa `sh.getBalancerState()`, jendela `activeWindow`, dan rentang zone
Query makin lambat seiring cluster tumbuh	Scatter-gather — query tanpa shard key	Masukkan shard key ke query umum; verifikasi dengan `explain`
Terindikasi document rangkap/usang pada satu shard	Orphaned documents sisa migrasi	Biarkan range deleter bekerja; verifikasi dengan `$shardedDataDistribution`
`sh.addShard()` gagal terhubung	Hostname tidak konsisten atau tak terselesaikan DNS	Seragamkan hostname; patuhi aturan `localhost`
Error `stale config detected`	Cache metadata mongos tertinggal	Jalankan `flushRouterConfig` pada mongos terkait

Tiga gejala pertama bermuara ke satu akar yang sama: shard key yang kurang baik. Kita bedah satu per satu.

Hotspot: Tulis yang Menumpuk #

Kasus klasiknya: collection orders di-shard ranged menurut order_id bertambah satu setiap pesanan. Semua insert mendarat di chunk dengan batas atas MaxKey di satu shard — shard itu menjadi hot, sisanya menganggur. Dokumentasi resmi mencatat bahwa hot shard bisa berpindah seiring split chunk, tetapi pada satu saat selalu ada tepat satu shard yang menampung hampir seluruh tulis baru; bila pembaca aplikasi condong ke data terbaru, shard tersebut menerima dobel pukulan.

Uji diagnosisnya sederhana: bandingkan operasi tulis per shard (bagian shardingStatistics pada serverStatus, atau ringkasan sh.status()). Solusinya dua arah — reshard collection ke shard key ber-hashed bila pola akses memungkinkan, atau refineCollectionShardKey untuk menaikkan cardinality kunci lama tanpa memindahkan ulang seluruh data.

Jumbo Chunk: Potongan yang Tak Bisa Dipecah #

Chunk yang melebihi ukuran range tetapi tidak bisa dipecah diberi label jumbo. Penyebab paling umum: chunk mewakili satu nilai shard key (nilai tunggal tidak bisa terbelah) — artinya cardinality terlalu rendah atau satu nilai terlalu dominan frekuensinya. Balancer menolak memigrasikan chunk jumbo, sehingga ketimpangannya bertahan dan menjadi bottleneck.

Jalan keluarnya mengikuti akar masalah: refineCollectionShardKey menambahkan field di akhir kunci sehingga nilai yang tadinya tunggal kini bisa terbagi; reshardCollection mengganti kunci total bila masalahnya struktural. Pengaturan balancer attemptToBalanceJumboChunks juga bisa mengizinkan migrasi chunk berukuran melampaui batas selama belum berlabel jumbo — opsi banding, bukan obat.

Orphaned Documents: Sisa Migrasi #

Migrasi chunk yang gagal di tengah jalan (misalnya proses mati sebelum fase penghapusan) bisa meninggalkan document yang seharusnya sudah tidak dimiliki shard tersebut — inilah orphaned documents, dan definisinya persis begitu di dokumentasi resmi: document di satu shard yang juga tercatat dimiliki chunk di shard lain. MongoDB membersihkannya otomatis lewat range deleter di latar belakang.

Perintah cleanupOrphaned dari dokumentasi lawas kini deprecated sejak 8.0 — dan ia memang tidak pernah langsung membersihkan, hanya menunggu proses pembersihan selesai. Cara verifikasi modern adalah aggregation dengan stage $shardedDataDistribution untuk memastikan tidak ada sisa orphan pada collection.

Kegagalan Konektivitas dan Metadata #

Dua keluhan administratif menutup daftar. Pertama, sh.addShard() yang gagal nyaris selalu soal hostname: dokumentasi deployment mewajibkan DNS hostname (bukan IP mentah), dan bila satu komponen memakai localhost, semua komponen lain harus memakai localhost juga. Kedua, pesan could not initialize cursor across all shards because : stale config detected (tercantum di dokumentasi troubleshooting) menandakan cache metadata seorang mongos tertinggal; paksa refresh dengan flushRouterConfig pada mongos tersebut.

Untuk kecurigaan korupsi metadata — misalnya setelah intervensi manual ke database config — MongoDB 7.0 menyediakan checkMetadataConsistency yang memindai inkonsistensi penempatan collection. Seperti alat cluster lainnya, perintah ini hanya dikenal mongos; kita buktikan di server latihan:

js
db.adminCommand({ checkMetadataConsistency: 1 })

Output yang Dihasilkan:

text

Uncaught 
MongoServerError[CommandNotFound]: no such command: 'checkMetadataConsistency'

Begitu pula pemeriksaan apakah balancer sedang berputar:

js
sh.isBalancerRunning()

Output yang Dihasilkan:

text
Warning: MongoshWarning: [SHAPI-10003] You are not connected to a mongos. This command may not work as expected.
Uncaught 
MongoServerError[CommandNotFound]: no such command: 'balancerStatus'

Kedua error menegaskan posisi kita sepanjang section ini: peralatan diagnosis sharding hidup di mongos pada cluster sungguhan. Untuk inspeksi harian, dua titik awal standar: sh.status() (distribusi chunk, status balancer, zone) dan database config — misalnya config.collections untuk memastikan shard key yang tercatat memang yang kita niatkan.

Rangkuman #

Tiga gejala paling umum — hotspot, jumbo chunk, ketimpangan — bermuara pada kualitas shard key: monotonicity, cardinality, dan frequency.
Orphaned documents dibersihkan otomatis oleh range deleter; verifikasi modernnya $shardedDataDistribution, bukan cleanupOrphaned yang deprecated.
Kegagalan addShard hampir selalu hostname; error stale config dijawab flushRouterConfig; korupsi metadata diperiksa checkMetadataConsistency (7.0+).
Titik inspeksi andalan tetap sh.status() dan database config — keduanya hanya bermakna lewat mongos.

Dengan itu, peta lengkap sharding sudah kita jelajahi: dari alasan scale-out, arsitektur tiga komponen, pemilihan shard key, sampai perawatan harian cluster-nya.