Class RocksDbMetrics

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

Exports a database's statistics and key properties as System.Diagnostics.Metrics instruments, which OpenTelemetry, Prometheus exporters and dotnet-counters all read.

public sealed class RocksDbMetrics : IDisposable

Inheritance

object

RocksDbMetrics

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Everything is observable: nothing is read until a listener collects, and each collection reads the current values, at about one native call per instrument. With nothing listening the export costs nothing.

Instruments are named as RocksDb names them, so rocksdb.block.cache.miss here is the same counter as in RocksDb's statistics dump, its documentation and existing dashboards. They live on a meter called MeterName, tagged db.name when DatabaseName is set.

• Each ticker is an ObservableCounter<T>: tickers only grow.
• Each histogram is an ObservableGauge<T> reporting its 0.5, 0.95 and 0.99 quantiles and its maximum (1.0), tagged quantile, with counters <name>.count and <name>.sum. RocksDb keeps summaries rather than samples, so they are exported as summaries.
• Each property is an ObservableGauge<T> under its RocksDb property name, such as rocksdb.estimate-num-keys. Totals are summed over every column family; database-wide values, such as the shared block cache, are read once.

A collection can arrive at any moment, including while the database is being disposed, which host shutdown makes likely. Reads are coordinated with the close: a collection either completes before the database closes or finds it closed and reports nothing. Dispose this object to remove the instruments; disposing the database alone leaves them reporting nothing.

Fields

MeterName

The meter every instrument is created on.

public const string MeterName = "RocksDb.Net"

Field Value

string

Methods

Dispose()

Stops exporting. The database is left as it is.

public void Dispose()

Remarks

Without MeterFactory, this disposes the meter, which removes the instruments. A meter from a factory belongs to the factory, and the factory hands the same meter to everything that asks for the same name and tags, so it is left alone: its instruments stay registered until the factory is disposed, but report nothing and no longer reference the database.

Register(RocksDb, RocksDbMetricsOptions?)

Starts exporting db's statistics and properties.

public static RocksDbMetrics Register(RocksDb db, RocksDbMetricsOptions? options = null)

Parameters

db RocksDb

The database to observe.

options RocksDbMetricsOptions

What to export, or null for everything.

Returns

RocksDbMetrics

The export. Dispose it to stop exporting.

Remarks

Tickers and histograms need statistics, which must be enabled with EnableStatistics() before the database is opened. Without them, the default of exporting everything exports the properties only, since every ticker would read zero.

Exceptions

InvalidOperationException

Specific tickers or histograms were asked for and statistics are not enabled, so each would report a misleading zero.