Project Oxygen & Ideo-LabIDEO LAB Dashboard 2026

đŸȘš RocksDB – Architecture, Tuning, OpĂ©rations

LSM-tree, WAL, memtables, SSTables, compaction, column families, Bloom/prefix, backup/checkpoint, perf & troubleshooting.

1.1

Vue d’ensemble

Key‑value store embarquĂ©, LSM‑tree.

LSMEmbedded
1.2

Architecture

WAL, memtable, SST, compactions.

WALSST
1.3

Installation

Linux/Windows, CMake, Java, Python.

C++Python
2.1

Column Families

Isolation logique, options dédiées.

CFTTL
2.2

Options clés

Block cache, write buffers, filters.

CacheBloom
2.3

Compaction

Leveled, Universal, RateLimiter.

L0→L1Rate
3.1

Performance

Read/Write amp, prefix, IO.

AmpIO
3.2

Monitoring

Statistics, perf_context, logs.

StatsPerf
3.3

Backup & Restore

Checkpoints, backup engine.

SnapshotS3
4.1

Troubleshooting

Stalls, L0 flush, corruption.

StallL0
4.2

Cas d’usage

State store, cache, queues.

StreamsEdge
4.3

Références

Docs, tuning, wiki.

Docs
1.1 Vue d’ensemble – Qu’est‑ce que RocksDB ?
Objectif & Positionnement

RocksDB est un moteur clé‑valeur embarquĂ© basĂ© sur une structure LSM‑Tree, optimisĂ© pour SSD/NVMe, utilisĂ© dans Kafka Streams, Flink StateBackend, MySQL/MyRocks, TiKV et de nombreux systĂšmes distribuĂ©s. Il ne fournit ni SQL, ni rĂ©seau : c’est une brique bas niveau performante Ă  intĂ©grer comme stockage local.

Caractéristiques clés
  • Write‑ahead log (WAL) + memtables -> flush -> fichiers SST.
  • Compaction multi‑niveaux pour maintenir l’ordre des clĂ©s.
  • Block cache unifiĂ© (LRU/GDSF) pour rĂ©duire l’I/O disque.
  • Prefix filters + Bloom pour accĂ©lĂ©rer les recherches.
  • Column Families pour sĂ©parer les workloads et les stratĂ©gies de compaction.
  • Compression ZSTD / LZ4 / Snappy → compromis place/perf.
Forces
  • Écritures sĂ©quentielles trĂšs rapides, idĂ©al ingestion/streaming.
  • AdaptĂ© aux workloads append-heavy et clĂ© ordonnĂ©e.
  • Permet des optimisations trĂšs fines via Options.
Faiblesses
  • ComplexitĂ© : tuning indispensable.
  • Write/Read Amplification → gestion compactions critique.
  • Pas de queries complexes, pas d’index secondaires avancĂ©s.
CritùreLSM (RocksDB)B‑Tree
WritesAppend (WAL) + memtable → flushRandom pages
ReadsFiltres + block cacheIndex/arbre
CompactionOui (amp. write/read)Non
Put → WAL append → Memtable insert → Flush → SST L0 → Compaction L0→L1→

Get → Memtable → Block cache → Bloom → SST read
  • Quand vous voulez un **KV embarquĂ©** trĂšs rapide, sans rĂ©seau : moteurs analytics, caches locaux, state store (Flink/Samza).
  • Éviter si besoin **SQL** riche, ou **requĂȘtes distribuĂ©es**.
1.2 Architecture – WAL, Memtables, SSTables, Compaction
  • WAL (write‑ahead log) sĂ©quentiel + memtable (skiplist/hash) ; flush quand plein → SST L0.
  • ParallĂ©liser avec plusieurs memtables (write_buffer_number) et subcompactions.
  • SSTable = blocks + index + filter (Bloom/prefix) + footer. Taille block typique 4–16 KB.
  • Block cache unifiĂ© (LRU) pour data + index + filter.
StyleUsageEffet
Leveledpar dĂ©fautFaible read‑amp, write‑amp modĂ©rĂ©e
UniversalGrandes valeurs/TTLMoins d’overwrites, merges sĂ©lectifs
FIFOLog/time seriesEviction par Ăąge
Memtable →[flush]→ L0.sst ──â–ș Compaction L0→L1 (tri/merge)
L1..Ln plus grands, non chevauchants (leveling)
1.3 Installation – Build C++, Bindings Java/Python
sudo apt-get update && sudo apt-get install -y build-essential cmake libsnappy-dev zlib1g-dev libbz2-dev libzstd-dev liblz4-dev
git clone https://github.com/facebook/rocksdb && cd rocksdb
cmake -S . -B build -DPORTABLE=1 -DWITH_ZSTD=1 -DWITH_BZ2=1 -DWITH_LZ4=1
cmake --build build -j
sudo cmake --install build

pip install python-rocksdb
# Exemple Python
import rocksdb
opts=rocksdb.Options()
opts.create_if_missing=True
opts.write_buffer_size=64*1024*1024
opts.target_file_size_base=64*1024*1024
opts.max_background_compactions=4
opts.table_factory=rocksdb.BlockBasedTableFactory(
  block_cache=rocksdb.LRUCache(512*1024*1024),
  filter_policy=rocksdb.BloomFilterPolicy(10)
)
db=rocksdb.DB('data.db', opts)
db.put(b'k1', b'v1')
print(db.get(b'k1'))

# Java (Maven)

  org.rocksdbrocksdbjni9.0.0


# Dockerfile simple
FROM python:3.12-slim
RUN apt-get update && apt-get install -y libsnappy1v5 libzstd1 liblz4-1 && pip install python-rocksdb
WORKDIR /app
COPY app.py .
CMD ["python","app.py"]
2.1 Column Families – Isolation & Options dĂ©diĂ©es
  • Chaque Column Family a ses propres options/compactions.
  • Isoler par domaine : cf_users, cf_orders, etc.
opts=rocksdb.Options(create_if_missing=True)
cf_names=[b'default', b'cf_users', b'cf_orders']
# Créer CF
rocksdb.DB.create_column_family('data.db', opts, b'cf_users')
# Ouvrir avec CFs
cf_opts=[(b'default', opts),(b'cf_users', opts),(b'cf_orders', opts)]
db=rocksdb.DB('data.db', opts, column_families=cf_opts)
wo=rocksdb.WriteOptions(); ro=rocksdb.ReadOptions()
db.put((b'cf_users', b'u:1'), b'Alice')
  • TTL DB : expiration automatique (sur compactions).
  • Options par CF : block_cache, prefix_extractor, compression.
2.2 Options clĂ©s – Cache, Write Buffers, Bloom/Prefix
cache=rocksdb.LRUCache(1*1024*1024*1024)  # 1GB
factory=rocksdb.BlockBasedTableFactory(block_cache=cache, cache_index_and_filter_blocks=True)
opts.table_factory=factory

Dimensionner ~ 50–70% de la RAM disponible (selon workload).

opts.write_buffer_size=128*1024*1024  # memtable
opts.max_write_buffer_number=3
opts.min_write_buffer_number_to_merge=1

opts.prefix_extractor=rocksdb.FixedPrefixTransform(8)
opts.memtable_prefix_bloom_size_ratio=0.1
factory=rocksdb.BlockBasedTableFactory(filter_policy=rocksdb.BloomFilterPolicy(10))

RequĂȘtes par prĂ©fixe (scans/sauts rapides), rĂ©duit read‑amp.

opts.compression=rocksdb.CompressionType.zstd_compression
opts.bottommost_compression=rocksdb.CompressionType.zstd_compression
2.3 Compaction – Leveled, Universal, Throttling
  • Level‑based : L0 chevauchants → tri en L1..Ln, faible read‑amp.
  • Universal : merge basĂ© sur taille/age, utile pour gros blobs/TTL.
  • FIFO : purge par Ăąge/bytes, pour logs.
opts.rate_limiter=rocksdb.RateLimiter(100*1024*1024)  # 100MB/s compaction/flush

opts.enable_pipelined_write=True
opts.max_background_compactions=8
opts.max_background_flushes=2
3.1 Performance – Amplifications, I/O, Skips & TTL
Principes
  • Write‑amp : rĂ©glĂ© par taille memtable/compaction.
  • Read‑amp : caches, bloom, prefix, index perf.
  • Space‑amp : compression, leveled.
Recettes rapides
# OLTP key‑value
write_buffer_size=64‑256MB, LRU 1‑4GB, bloom=10
# Time‑series
universal compaction, TTL, bottommost zstd
3.2 Monitoring – Statistics & perf_context
opts.statistics=rocksdb.Statistics()
print(opts.statistics)

Activer perf_context pour décomposer un GET (block cache hit, table open, etc.).

Analyser le fichier LOG pour compactions/flush, stalles, erreurs.

3.3 Backup & Restore – Checkpoint, BackupEngine
import rocksdb, os
cp=rocksdb.Checkpoint.create(db)
os.makedirs('snap', exist_ok=True)
cp.create_checkpoint('snap')

# C++/Java: BackupEngine vers répertoire/S3 (monté)

# Restaurer: fermer DB, remplacer répertoire par snapshot, rouvrir
4.1 Troubleshooting – Stalls, L0 overflow, Corruption
  • Augmenter max_background_compactions, rate_limiter.
  • Élargir write_buffer_size, rĂ©duire flushs frĂ©quents.
  • Limiter chevauchements : niveau L0 → L1 plus agressif.
  • VĂ©rifier taille de SST/compaction triggers.
  • VĂ©rifier disque/FS, corriger avec backup/restore.
4.2 Cas d’usage – State Store, Cache, Queues locales
State store streaming
  • Flink, Spark, Samza : opĂ©rateurs d’état locaux.
Cache/Edge
  • KV rapide pour dĂ©dup/idempotence, files locales.
Références officielles & tuning guides
  • RocksDB Wiki & Docs : options, formats, tuning.
  • Facebook RocksDB GitHub : issues, examples.
  • Tuning guides (block cache, compaction, bloom/prefix).
Cheat‑sheet – Recettes & Extraits Python/C++
Recettes
# KV OLTP
write_buffer_size=128MB
LRU cache 1‑2GB
Bloom bits=10
compression=zstd
# Time‑series
universal compaction
TTL
C++ init (idée)
rocksdb::Options o; o.create_if_missing=true;
o.write_buffer_size = 128<<20; // 128MB
rocksdb::BlockBasedTableOptions t; t.block_cache = rocksdb::NewLRUCache(1<<30);
o.table_factory.reset(NewBlockBasedTableFactory(t));
rocksdb::DB* db; rocksdb::Status s = rocksdb::DB::Open(o, "data", &db);