history-expiry: RocksDB BlobDB GC tuning CLI Config (#8599)

- --Xplugin-rocksdb-blob-garbage-collection-age-cutoff configures blob_garbage_collection_age_cutoff
- --Xplugin-rocksdb-blob-garbage-collection-force-threshold configures blob_garbage_collection_force_threshold
- --Xplugin-rocksdb-blockchain-blob-garbage-collection-enabled to configure BLOCKCHAIN BlobDB GC specifically
- Unspecified GC settings should default to RocksDB defaults (rather than hardcoding RocksDB defaults in Besu)
- Display BlobDB GC settings in config overview

---------

Signed-off-by: Simon Dudley <[email protected]>

Author: siladu

CHANGELOG.md

@@ -6,6 +6,8 @@
 
 ### Upcoming Breaking Changes
 ### Additions and Improvements
+- `--Xplugin-rocksdb-blockchain-blob-garbage-collection-enabled` Adds ability to enabled BlobDB GC for BLOCKCHAIN column family [#8599](https://github.com/hyperledger/besu/pull/8599)
+- `--Xplugin-rocksdb-blob-garbage-collection-age-cutoff`, `--Xplugin-rocksdb-blob-garbage-collection-force-threshold` BlobDB GC config options [#8599](https://github.com/hyperledger/besu/pull/8599)
 
 ## 25.5.0
 ### Breaking Changes

besu/src/main/java/org/hyperledger/besu/cli/BesuCommand.java

@@ -2817,18 +2817,19 @@ private String generateConfigurationOverview() {
       final PathBasedExtraStorageConfiguration subStorageConfiguration =
           getDataStorageConfiguration().getPathBasedExtraStorageConfiguration();
       if (subStorageConfiguration.getLimitTrieLogsEnabled()) {
-        builder.setLimitTrieLogsEnabled();
-        builder.setTrieLogRetentionLimit(subStorageConfiguration.getMaxLayersToLoad());
-        builder.setTrieLogsPruningWindowSize(subStorageConfiguration.getTrieLogPruningWindowSize());
+        builder
+            .setLimitTrieLogsEnabled()
+            .setTrieLogRetentionLimit(subStorageConfiguration.getMaxLayersToLoad())
+            .setTrieLogsPruningWindowSize(subStorageConfiguration.getTrieLogPruningWindowSize());
       }
     }
 
-    builder.setSnapServerEnabled(this.unstableSynchronizerOptions.isSnapsyncServerEnabled());
-
-    builder.setTxPoolImplementation(buildTransactionPoolConfiguration().getTxPoolImplementation());
-    builder.setWorldStateUpdateMode(unstableEvmOptions.toDomainObject().worldUpdaterMode());
-
-    builder.setPluginContext(this.besuPluginContext);
+    builder
+        .setSnapServerEnabled(this.unstableSynchronizerOptions.isSnapsyncServerEnabled())
+        .setTxPoolImplementation(buildTransactionPoolConfiguration().getTxPoolImplementation())
+        .setWorldStateUpdateMode(unstableEvmOptions.toDomainObject().worldUpdaterMode())
+        .setPluginContext(this.besuPluginContext)
+        .setBlobDBSettings(rocksDBPlugin.getBlobDBSettings());
 
     return builder.build();
   }

besu/src/main/java/org/hyperledger/besu/cli/ConfigurationOverviewBuilder.java

@@ -16,6 +16,7 @@
 
 import org.hyperledger.besu.ethereum.eth.transactions.TransactionPoolConfiguration;
 import org.hyperledger.besu.evm.internal.EvmConfiguration;
+import org.hyperledger.besu.plugin.services.storage.rocksdb.configuration.RocksDBCLIOptions;
 import org.hyperledger.besu.services.BesuPluginContextImpl;
 import org.hyperledger.besu.util.BesuVersionUtils;
 import org.hyperledger.besu.util.log.FramedLogMessage;
@@ -61,6 +62,7 @@ public class ConfigurationOverviewBuilder {
   private EvmConfiguration.WorldUpdaterMode worldStateUpdateMode;
   private Map<String, String> environment;
   private BesuPluginContextImpl besuPluginContext;
+  private RocksDBCLIOptions.BlobDBSettings blobDBSettings;
 
   /**
    * Create a new ConfigurationOverviewBuilder.
@@ -302,6 +304,30 @@ public ConfigurationOverviewBuilder setEnvironment(final Map<String, String> env
     return this;
   }
 
+  /**
+   * set the plugin context
+   *
+   * @param besuPluginContext the plugin context
+   * @return the builder
+   */
+  public ConfigurationOverviewBuilder setPluginContext(
+      final BesuPluginContextImpl besuPluginContext) {
+    this.besuPluginContext = besuPluginContext;
+    return this;
+  }
+
+  /**
+   * Sets the blob db settings.
+   *
+   * @param blobDBSettings the blob db settings
+   * @return the builder
+   */
+  public ConfigurationOverviewBuilder setBlobDBSettings(
+      final RocksDBCLIOptions.BlobDBSettings blobDBSettings) {
+    this.blobDBSettings = blobDBSettings;
+    return this;
+  }
+
   /**
    * Build configuration overview.
    *
@@ -364,16 +390,8 @@ public String build() {
 
     lines.add("Using " + txPoolImplementation + " transaction pool implementation");
 
-    if (isHighSpec) {
-      lines.add("Experimental high spec configuration enabled");
-    }
-
     lines.add("Using " + worldStateUpdateMode + " worldstate update mode");
 
-    if (isSnapServerEnabled) {
-      lines.add("Experimental Snap Sync server enabled");
-    }
-
     if (isLimitTrieLogsEnabled) {
       final StringBuilder trieLogPruningString = new StringBuilder();
       trieLogPruningString
@@ -385,6 +403,34 @@ public String build() {
       lines.add(trieLogPruningString.toString());
     }
 
+    if (isSnapServerEnabled) {
+      lines.add("Experimental Snap Sync server enabled");
+    }
+
+    if (isHighSpec) {
+      lines.add("Experimental high spec configuration enabled");
+    }
+
+    if (blobDBSettings != null && blobDBSettings.isBlockchainGarbageCollectionEnabled()) {
+      lines.add("Experimental BlobDB BLOCKCHAIN Garbage Collection enabled");
+    }
+    if (hasCustomBlobDBSettings()) {
+      final StringBuilder blobDBString = new StringBuilder();
+      blobDBString.append("Experimental BlobDB GC ");
+      if (blobDBSettings.blobGarbageCollectionAgeCutoff().isPresent()) {
+        blobDBString
+            .append("age cutoff: ")
+            .append(blobDBSettings.blobGarbageCollectionAgeCutoff().get())
+            .append("; ");
+      }
+      if (blobDBSettings.blobGarbageCollectionForceThreshold().isPresent()) {
+        blobDBString
+            .append("force threshold: ")
+            .append(blobDBSettings.blobGarbageCollectionForceThreshold().get());
+      }
+      lines.add(blobDBString.toString());
+    }
+
     lines.add("");
     lines.add("Host:");
 
@@ -415,6 +461,12 @@ public String build() {
     return FramedLogMessage.generate(lines);
   }
 
+  private boolean hasCustomBlobDBSettings() {
+    return blobDBSettings != null
+        && (blobDBSettings.blobGarbageCollectionAgeCutoff().isPresent()
+            || blobDBSettings.blobGarbageCollectionForceThreshold().isPresent());
+  }
+
   private void detectJemalloc(final List<String> lines) {
     Optional.ofNullable(Objects.isNull(environment) ? null : environment.get("BESU_USING_JEMALLOC"))
         .ifPresentOrElse(
@@ -447,13 +499,4 @@ private void detectJemalloc(final List<String> lines) {
   private String normalizeSize(final long size) {
     return String.format("%.02f", (double) (size) / 1024 / 1024 / 1024) + " GB";
   }
-
-  /**
-   * set the plugin context
-   *
-   * @param besuPluginContext the plugin context
-   */
-  public void setPluginContext(final BesuPluginContextImpl besuPluginContext) {
-    this.besuPluginContext = besuPluginContext;
-  }
 }

besu/src/test/java/org/hyperledger/besu/RunnerTest.java

@@ -424,7 +424,10 @@ private StorageProvider createKeyValueStorageProvider(
                         DEFAULT_MAX_OPEN_FILES,
                         DEFAULT_BACKGROUND_THREAD_COUNT,
                         DEFAULT_CACHE_CAPACITY,
-                        DEFAULT_IS_HIGH_SPEC),
+                        DEFAULT_IS_HIGH_SPEC,
+                        false,
+                        Optional.empty(),
+                        Optional.empty()),
                 Arrays.asList(KeyValueSegmentIdentifier.values()),
                 RocksDBMetricsFactory.PUBLIC_ROCKS_DB_METRICS))
         .withCommonConfiguration(besuConfiguration)

besu/src/test/java/org/hyperledger/besu/components/PrivacyTestModule.java

@@ -34,6 +34,7 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.Arrays;
+import java.util.Optional;
 import javax.inject.Named;
 import javax.inject.Singleton;
 
@@ -101,7 +102,10 @@ PrivacyStorageProvider provideKeyValueStorageProvider(
                             DEFAULT_MAX_OPEN_FILES,
                             DEFAULT_BACKGROUND_THREAD_COUNT,
                             DEFAULT_CACHE_CAPACITY,
-                            DEFAULT_IS_HIGH_SPEC),
+                            DEFAULT_IS_HIGH_SPEC,
+                            false,
+                            Optional.empty(),
+                            Optional.empty()),
                     Arrays.asList(KeyValueSegmentIdentifier.values()),
                     RocksDBMetricsFactory.PRIVATE_ROCKS_DB_METRICS)))
         .withCommonConfiguration(besuConfiguration)

ethereum/core/src/test/java/org/hyperledger/besu/ethereum/trie/pathbased/bonsai/AbstractIsolationTests.java

@@ -202,7 +202,10 @@ protected StorageProvider createKeyValueStorageProvider() {
                         1024 /* MAX_OPEN_FILES*/,
                         4 /*BACKGROUND_THREAD_COUNT*/,
                         8388608 /*CACHE_CAPACITY*/,
-                        false),
+                        false,
+                        false,
+                        Optional.empty(),
+                        Optional.empty()),
                 Arrays.asList(KeyValueSegmentIdentifier.values()),
                 RocksDBMetricsFactory.PUBLIC_ROCKS_DB_METRICS))
         .withCommonConfiguration(

ethereum/eth/src/jmh/java/org/hyperledger/besu/ethereum/eth/sync/worldstate/WorldStateDownloaderBenchmark.java

@@ -178,7 +178,10 @@ private StorageProvider createKeyValueStorageProvider(final Path dataDir, final
                         DEFAULT_MAX_OPEN_FILES,
                         DEFAULT_BACKGROUND_THREAD_COUNT,
                         DEFAULT_CACHE_CAPACITY,
-                        DEFAULT_IS_HIGH_SPEC),
+                        DEFAULT_IS_HIGH_SPEC,
+                        false,
+                        Optional.empty(),
+                        Optional.empty()),
                 Arrays.asList(KeyValueSegmentIdentifier.values()),
                 RocksDBMetricsFactory.PUBLIC_ROCKS_DB_METRICS))
         .withCommonConfiguration(besuConfiguration)

plugins/rocksdb/src/main/java/org/hyperledger/besu/plugin/services/storage/rocksdb/RocksDBPlugin.java

@@ -117,6 +117,15 @@ public boolean isHighSpecEnabled() {
     return options.isHighSpec();
   }
 
+  /**
+   * Gets blob db settings.
+   *
+   * @return the blob db settings
+   */
+  public RocksDBCLIOptions.BlobDBSettings getBlobDBSettings() {
+    return options.getBlobDBSettings();
+  }
+
   private void createAndRegister(final StorageService service) {
     final List<SegmentIdentifier> segments = service.getAllSegmentIdentifiers();
 

plugins/rocksdb/src/main/java/org/hyperledger/besu/plugin/services/storage/rocksdb/configuration/RocksDBCLIOptions.java

@@ -14,6 +14,8 @@
  */
 package org.hyperledger.besu.plugin.services.storage.rocksdb.configuration;
 
+import java.util.Optional;
+
 import com.google.common.base.MoreObjects;
 import picocli.CommandLine;
 
@@ -45,6 +47,18 @@ public class RocksDBCLIOptions {
   /** The constant IS_HIGH_SPEC. */
   public static final String IS_HIGH_SPEC = "--Xplugin-rocksdb-high-spec-enabled";
 
+  /** Key name for configuring blockchain_blob_garbage_collection_enabled */
+  public static final String BLOB_BLOCKCHAIN_GARBAGE_COLLECTION_ENABLED =
+      "--Xplugin-rocksdb-blockchain-blob-garbage-collection-enabled";
+
+  /** Key name for configuring blob_garbage_collection_age_cutoff */
+  public static final String BLOB_GARBAGE_COLLECTION_AGE_CUTOFF =
+      "--Xplugin-rocksdb-blob-garbage-collection-age-cutoff";
+
+  /** Key name for configuring blob_garbage_collection_force_threshold */
+  public static final String BLOB_GARBAGE_COLLECTION_FORCE_THRESHOLD =
+      "--Xplugin-rocksdb-blob-garbage-collection-force-threshold";
+
   /** The Max open files. */
   @CommandLine.Option(
       names = {MAX_OPEN_FILES_FLAG},
@@ -81,6 +95,39 @@ public class RocksDBCLIOptions {
           "Use this flag to boost Besu performance if you have a 16 GiB RAM hardware or more (default: ${DEFAULT-VALUE})")
   boolean isHighSpec;
 
+  /** The Blob blockchain garbage collection enabled. */
+  @CommandLine.Option(
+      names = {BLOB_BLOCKCHAIN_GARBAGE_COLLECTION_ENABLED},
+      hidden = true,
+      paramLabel = "<BOOLEAN>",
+      description =
+          "Enable garbage collection for the BLOCKCHAIN column family (default: ${DEFAULT-VALUE})")
+  boolean isBlockchainGarbageCollectionEnabled = false;
+
+  /**
+   * The Blob garbage collection age cutoff. The fraction of file age to be considered eligible for
+   * GC; e.g. 0.25 = oldest 25% of files eligible; e.g. 1 = all files eligible When unspecified, use
+   * RocksDB default
+   */
+  @CommandLine.Option(
+      names = {BLOB_GARBAGE_COLLECTION_AGE_CUTOFF},
+      hidden = true,
+      paramLabel = "<DOUBLE>",
+      description = "Blob garbage collection age cutoff (default: ${DEFAULT-VALUE})")
+  Optional<Double> blobGarbageCollectionAgeCutoff = Optional.empty();
+
+  /**
+   * The Blob garbage collection force threshold. The fraction of garbage inside eligible blob files
+   * to trigger GC; e.g. 1 = trigger when eligible file contains 100% garbage; e.g. 0 = trigger for
+   * all eligible files; When unspecified, use Rocksdb default
+   */
+  @CommandLine.Option(
+      names = {BLOB_GARBAGE_COLLECTION_FORCE_THRESHOLD},
+      hidden = true,
+      paramLabel = "<DOUBLE>",
+      description = "Blob garbage collection force threshold (default: ${DEFAULT-VALUE})")
+  Optional<Double> blobGarbageCollectionForceThreshold = Optional.empty();
+
   private RocksDBCLIOptions() {}
 
   /**
@@ -104,6 +151,9 @@ public static RocksDBCLIOptions fromConfig(final RocksDBConfiguration config) {
     options.cacheCapacity = config.getCacheCapacity();
     options.backgroundThreadCount = config.getBackgroundThreadCount();
     options.isHighSpec = config.isHighSpec();
+    options.isBlockchainGarbageCollectionEnabled = config.isBlockchainGarbageCollectionEnabled();
+    options.blobGarbageCollectionAgeCutoff = config.getBlobGarbageCollectionAgeCutoff();
+    options.blobGarbageCollectionForceThreshold = config.getBlobGarbageCollectionForceThreshold();
     return options;
   }
 
@@ -114,7 +164,13 @@ public static RocksDBCLIOptions fromConfig(final RocksDBConfiguration config) {
    */
   public RocksDBFactoryConfiguration toDomainObject() {
     return new RocksDBFactoryConfiguration(
-        maxOpenFiles, backgroundThreadCount, cacheCapacity, isHighSpec);
+        maxOpenFiles,
+        backgroundThreadCount,
+        cacheCapacity,
+        isHighSpec,
+        isBlockchainGarbageCollectionEnabled,
+        blobGarbageCollectionAgeCutoff,
+        blobGarbageCollectionForceThreshold);
   }
 
   /**
@@ -126,13 +182,40 @@ public boolean isHighSpec() {
     return isHighSpec;
   }
 
+  /**
+   * Gets blob db settings.
+   *
+   * @return the blob db settings
+   */
+  public BlobDBSettings getBlobDBSettings() {
+    return new BlobDBSettings(
+        isBlockchainGarbageCollectionEnabled,
+        blobGarbageCollectionAgeCutoff,
+        blobGarbageCollectionForceThreshold);
+  }
+
   @Override
   public String toString() {
     return MoreObjects.toStringHelper(this)
         .add("maxOpenFiles", maxOpenFiles)
         .add("cacheCapacity", cacheCapacity)
         .add("backgroundThreadCount", backgroundThreadCount)
         .add("isHighSpec", isHighSpec)
+        .add("isBlockchainGarbageCollectionEnabled", isBlockchainGarbageCollectionEnabled)
+        .add("blobGarbageCollectionAgeCutoff", blobGarbageCollectionAgeCutoff)
+        .add("blobGarbageCollectionForceThreshold", blobGarbageCollectionForceThreshold)
         .toString();
   }
+
+  /**
+   * A container type BlobDBSettings
+   *
+   * @param isBlockchainGarbageCollectionEnabled the is blockchain garbage collection enabled
+   * @param blobGarbageCollectionAgeCutoff the blob garbage collection age cutoff
+   * @param blobGarbageCollectionForceThreshold the blob garbage collection force threshold
+   */
+  public record BlobDBSettings(
+      boolean isBlockchainGarbageCollectionEnabled,
+      Optional<Double> blobGarbageCollectionAgeCutoff,
+      Optional<Double> blobGarbageCollectionForceThreshold) {}
 }