Class PerfContext

Namespace

RocksDbNet

Assembly

RocksDb.Net.dll

Per-operation profiling counters for the current thread. Maps to rocksdb_perfcontext_t.

public sealed class PerfContext : RocksDbHandle, IDisposable

Inheritance

object

RocksDbHandle

PerfContext

Implements

IDisposable

Inherited Members

RocksDbHandle.Handle

RocksDbHandle.Owned

RocksDbHandle.IsDisposed

RocksDbHandle.ThrowIfDisposed()

RocksDbHandle.Dispose()

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Answers a question the database-wide statistics cannot: where the time and I/O went inside one operation. EnableStatistics() aggregates across every thread for the life of the database; this measures a single thread's work since the last Reset().

The usual shape is to set a level, reset, perform one operation, then read the counters:

PerfContext.SetLevel(PerfLevel.EnableCount);
using var perf = PerfContext.CreateForCurrentThread();
perf.Reset();
_ = db.GetString("key");
long comparisons = (long)perf.GetMetric(PerfMetric.UserKeyComparisonCount);

This is bound to the thread that created it. RocksDb keeps the counters in thread-local storage, so an instance created on one thread reports nothing useful about another. Every member therefore throws if used from a different thread, which turns undefined behaviour into a diagnosable exception. In practice that means it cannot survive an await, because the continuation may resume on another thread. SetLevel(PerfLevel) is thread-local for the same reason.

Methods

CreateForCurrentThread()

Returns the calling thread's perf context.

public static PerfContext CreateForCurrentThread()

Returns

PerfContext

Remarks

Dispose it on the same thread. Disposal only releases a small wrapper; the counters themselves belong to the thread, not to this object, so disposing does not reset them.

DisposeHandle()

Releases the native handle. Called during disposal.

protected override void DisposeHandle()

Remarks

Protected rather than public: it destroys the native object without marking this instance disposed or clearing the handle, so calling it from outside and then disposing normally would free the same pointer twice. It was the most Dispose-looking member on the type. Callers want Dispose().

GetMetric(PerfMetric)

Reads one counter.

public ulong GetMetric(PerfMetric metric)

Parameters

metric PerfMetric

The counter to read.

Returns

ulong

The counter's value, or zero if the current PerfLevel does not populate it.

Exceptions

ArgumentOutOfRangeException

The value is not a defined PerfMetric.

Report(bool)

Renders every counter as text, for logging or a dump.

public string Report(bool excludeZeroCounters = true)

Parameters

excludeZeroCounters bool

When true, the default, counters still at zero are left out.

Returns

string

Reset()

Zeroes every counter for this thread.

public void Reset()

SetLevel(PerfLevel)

Sets how much detail RocksDb collects, for the calling thread only.

public static void SetLevel(PerfLevel level)

Parameters

level PerfLevel

Exceptions

ArgumentOutOfRangeException

The value is not a defined PerfLevel. RocksDb casts it without checking, so an out-of-range value would reach native code as a garbage enum.