@harperfast/rocksdb-js 0.1.8 → 0.1.9

package/README.md

@@ -10,6 +10,7 @@ A Node.js binding for the RocksDB library.
 - Transaction log system for recording transaction related data
 - Custom stores provide ability to override default database interactions
 - Efficient binary key and value encoding
+- Access to internal RocksDB statistics
 - Designed for Node.js and Bun on Linux, macOS, and Windows
 
 ## Example
@@ -42,7 +43,10 @@ Creates a new database instance.
 - `path: string` The path to write the database files to. This path does not need to exist, but the
   parent directories do.
 - `options: object` [optional]
-  - `disableWAL: boolean` Whether to disable the RocksDB write ahead log.
+  - `disableWAL: boolean` Whether to disable the RocksDB write ahead log. Defaults to `false`.
+  - `enableStats: boolean` When `true` and the database is open, RocksDB will captures stats that
+    are retrieved by calling `db.getStats()`. Enabling statistics imposes 5-10% in overhead.
+    Defaults to `false`.
   - `name: string` The column family name. Defaults to `"default"`.
   - `noBlockCache: boolean` When `true`, disables the block cache. Block caching is enabled by
     default and the cache is shared across all database instances.
@@ -50,6 +54,8 @@ Creates a new database instance.
     Defaults to `1`.
   - `pessimistic: boolean` When `true`, throws conflict errors when they occur instead of waiting
     until commit. Defaults to `false`.
+  - `statsLevel: StatsLevel` Controls which type of statistics to skip and reduce statistic
+    overhead. Defaults to `StatsLevel.ExceptDetailedTimers`.
   - `store: Store` A custom store that handles all interaction between the `RocksDatabase` or
     `Transaction` instances and the native database interface. See [Custom Store](#custom-store) for
     more information.
@@ -599,6 +605,99 @@ db.notify(1234);
 db.notify({ key: 'bar' }, { value: 'baz' });
 ```
 
+## Statistics
+
+Retrieve RocksDB statistics at runtime. You must set `enableStats: true` when calling `db.open()`.
+Statistics are captured at the database level and include all column families.
+
+RocksDB has two types of statistics: tickers and histograms. Tickers are 64-bit unsigned integers
+that measure counters. Histograms are objects containing various measurements of statistic
+distribution across all operations.
+
+```typescript
+import { RocksDatabase, stats } from '@harperfast/rocksdb-js';
+const db = RocksDatabase.open('/path/to/db', {
+	enableStats: true,
+	statsLevel: stats.StatsLevel.ExceptDetailedTimers, // default
+});
+console.log(db.getStats());
+```
+
+### `db.getStat(statName: string): number`
+
+Retrieves a single statistic value.
+
+```typescript
+console.log(db.getStat('rocksdb.block.cache.miss'));
+```
+
+### `db.getStats(all?: boolean): Object<string, number | StatsHistogramData>`
+
+Returns an object containing a curated list of column family-level properties, internal tickers
+stats, and internal histogram stats.
+
+By default, it only returns the most meaningful internal stats. When `all = true`, it returns the
+same column family-level properties, but includes all internal tickers and histogram stats.
+
+Column family and ticker stat values are 64-bit unsigned integers and histogram values are
+`StatsHistogramData` objects.
+
+```typescript
+// get essential stats
+console.log(db.getStats());
+
+// get all stats
+console.log(db.getStats(true));
+```
+
+### `stats`
+
+An object containing stat specific constants including ticker and histogram names.
+
+#### `stats.histograms`
+
+An array of internal histogram stat names.
+
+```typescript
+import { stats } from '@harperfast/rocksdb-js';
+console.log(stats.histograms);
+```
+
+#### `stats.tickers`
+
+An array of internal ticker stat names.
+
+```typescript
+import { stats } from '@harperfast/rocksdb-js';
+console.log(stats.tickers);
+```
+
+#### `stats.StatsLevel`
+
+The `stats.StatsLevel` contains constants used to set which types of skip and reduce statistic overhead.
+
+- `StatsLevel.DisableAll` Disable all metrics.
+- `StatsLevel.ExceptTickers` Disable all tickers.
+- `StatsLevel.ExceptHistogramOrTimers` Disable timer stats and skip histogram stats.
+- `StatsLevel.ExceptTimers` Skip timer stats
+- `StatsLevel.ExceptDetailedTimers` Skip time waiting for mutex locks and compression.
+- `StatsLevel.ExceptTimeForMutex` Skip time waiting for mutex locks.
+- `StatsLevel.All` Collects all stats.
+
+### `type StatsHistogramData`
+
+An object is a record with the following properties:
+
+- `average: number` A double containing the average value.
+- `count: number` An unsigned 64-bit integer containing the number of values.
+- `max: number` A double containing the maximum value.
+- `median: number` A double containing the median value.
+- `min: number` A double containing the minimum value.
+- `percentile95: number` A double containing the 95th percentile value.
+- `percentile99: number` A double containing the 99th percentile value.
+- `standardDeviation: number` A double containing the standard deviation.
+- `sum: number` An unsigned 64-bit integer containing the sum of all values.
+
 ## Exclusive Locking
 
 `rocksdb-js` includes a handful of functions for executing thread-safe mutually exclusive functions.

package/dist/index.cjs

@@ -87,6 +87,7 @@ const NativeTransaction = binding.Transaction;
 const TransactionLog = binding.TransactionLog;
 const registryStatus = binding.registryStatus;
 const shutdown = binding.shutdown;
+const stats = binding.stats;
 const version = binding.version;
 
 //#endregion
@@ -595,6 +596,10 @@ var Store = class {
 	*/
 	disableWAL;
 	/**
+	* Whether to enable RocksDB statistics.
+	*/
+	enableStats;
+	/**
 	* Reusable buffer for encoding values using `writeKey()` when the custom
 	* encoder does not provide a `encode()` method.
 	*/
@@ -661,6 +666,10 @@ var Store = class {
 	*/
 	sharedStructuresKey;
 	/**
+	* The level of statistics to capture.
+	*/
+	statsLevel;
+	/**
 	* The threshold for the transaction log file's last modified time to be
 	* older than the retention period before it is rotated to the next sequence
 	* number. A threshold of 0 means ignore age check.
@@ -699,6 +708,7 @@ var Store = class {
 		this.db = new NativeDatabase();
 		this.decoder = options?.decoder ?? null;
 		this.disableWAL = options?.disableWAL ?? false;
+		this.enableStats = options?.enableStats ?? false;
 		this.encodeBuffer = createFixedBuffer(SAVE_BUFFER_SIZE);
 		this.encoder = options?.encoder ?? null;
 		this.encoding = options?.encoding ?? null;
@@ -714,6 +724,7 @@ var Store = class {
 		this.randomAccessStructure = options?.randomAccessStructure ?? false;
 		this.readKey = readKey;
 		this.sharedStructuresKey = options?.sharedStructuresKey;
+		this.statsLevel = options?.statsLevel;
 		this.transactionLogMaxAgeThreshold = options?.transactionLogMaxAgeThreshold;
 		this.transactionLogMaxSize = options?.transactionLogMaxSize;
 		this.transactionLogRetention = options?.transactionLogRetention;
@@ -915,10 +926,12 @@ var Store = class {
 		if (this.db.opened) return true;
 		this.db.open(this.path, {
 			disableWAL: this.disableWAL,
+			enableStats: this.enableStats,
 			mode: this.pessimistic ? "pessimistic" : "optimistic",
 			name: this.name,
 			noBlockCache: this.noBlockCache,
 			parallelismThreads: this.parallelismThreads,
+			statsLevel: this.statsLevel,
 			transactionLogMaxAgeThreshold: this.transactionLogMaxAgeThreshold,
 			transactionLogMaxSize: this.transactionLogMaxSize,
 			transactionLogRetentionMs: this.transactionLogRetention ? parseDuration(this.transactionLogRetention) : void 0,
@@ -1170,22 +1183,36 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.encoder;
 	}
 	/**
-	* Returns the current timestamp as a monotonically increasing timestamp in
-	* milliseconds represented as a decimal number.
+	* Flushes the underlying database by performing a commit or clearing any buffered operations.
 	*
-	* @returns The current monotonic timestamp in milliseconds.
+	* @return {void} Does not return a value.
 	*/
-	getMonotonicTimestamp() {
-		return this.store.db.getMonotonicTimestamp();
+	flush() {
+		return new Promise((resolve, reject) => this.store.db.flush(resolve, reject));
 	}
 	/**
-	* Returns a number representing a unix timestamp of the oldest unreleased
-	* snapshot.
+	* Synchronously flushes the underlying database by performing a commit or clearing any buffered operations.
 	*
-	* @returns The oldest snapshot timestamp.
+	* @return {void} Does not return a value.
 	*/
-	getOldestSnapshotTimestamp() {
-		return this.store.db.getOldestSnapshotTimestamp();
+	flushSync() {
+		return this.store.db.flushSync();
+	}
+	/**
+	* Gets a RocksDB database property as an integer.
+	*
+	* @param propertyName - The name of the property to retrieve (e.g., 'rocksdb.num-blob-files').
+	* @returns The property value as a number.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* const blobFiles = db.getDBIntProperty('rocksdb.num-blob-files');
+	* const numKeys = db.getDBIntProperty('rocksdb.estimate-num-keys');
+	* ```
+	*/
+	getDBIntProperty(propertyName) {
+		return this.store.db.getDBIntProperty(propertyName);
 	}
 	/**
 	* Gets a RocksDB database property as a string.
@@ -1204,42 +1231,43 @@ var RocksDatabase = class RocksDatabase extends DBI {
 		return this.store.db.getDBProperty(propertyName);
 	}
 	/**
-	* Gets a RocksDB database property as an integer.
-	*
-	* @param propertyName - The name of the property to retrieve (e.g., 'rocksdb.num-blob-files').
-	* @returns The property value as a number.
+	* Returns the current timestamp as a monotonically increasing timestamp in
+	* milliseconds represented as a decimal number.
 	*
-	* @example
-	* ```typescript
-	* const db = RocksDatabase.open('/path/to/database');
-	* const blobFiles = db.getDBIntProperty('rocksdb.num-blob-files');
-	* const numKeys = db.getDBIntProperty('rocksdb.estimate-num-keys');
-	* ```
+	* @returns The current monotonic timestamp in milliseconds.
 	*/
-	getDBIntProperty(propertyName) {
-		return this.store.db.getDBIntProperty(propertyName);
+	getMonotonicTimestamp() {
+		return this.store.db.getMonotonicTimestamp();
 	}
 	/**
-	* Flushes the underlying database by performing a commit or clearing any buffered operations.
+	* Returns a number representing a unix timestamp of the oldest unreleased
+	* snapshot.
 	*
-	* @return {void} Does not return a value.
+	* @returns The oldest snapshot timestamp.
 	*/
-	flush() {
-		return new Promise((resolve, reject) => this.store.db.flush(resolve, reject));
+	getOldestSnapshotTimestamp() {
+		return this.store.db.getOldestSnapshotTimestamp();
 	}
 	/**
-	* Synchronously flushes the underlying database by performing a commit or clearing any buffered operations.
+	* Gets a RocksDB statistic.
 	*
-	* @return {void} Does not return a value.
+	* @param statName - The name of the statistic to retrieve.
+	* @returns The statistic value.
 	*/
-	flushSync() {
-		return this.store.db.flushSync();
+	getStat(statName) {
+		return this.store.db.getStat(statName);
 	}
-	getStats() {
-		return {
-			free: {},
-			root: {}
-		};
+	/**
+	* Gets the RocksDB statistics. Requires statistics to be enabled.
+	*
+	* @example
+	* ```typescript
+	* const db = RocksDatabase.open('/path/to/database');
+	* const stats = db.getStats();
+	* ```
+	*/
+	getStats(all = false) {
+		return this.store.db.getStats(all);
 	}
 	/**
 	* Gets or creates a buffer that can be shared across worker threads.
@@ -1816,7 +1844,7 @@ function loadLastPosition(transactionLog, readUncommitted) {
 //#region src/index.ts
 const versions = {
 	rocksdb: version,
-	"rocksdb-js": "0.1.8"
+	"rocksdb-js": "0.1.9"
 };
 
 //#endregion
@@ -1830,5 +1858,6 @@ exports.constants = constants;
 exports.parseTransactionLog = parseTransactionLog;
 exports.registryStatus = registryStatus;
 exports.shutdown = shutdown;
+exports.stats = stats;
 exports.versions = versions;
 //# sourceMappingURL=index.cjs.map