Diagnostics

ZoneTree diagnostics start with the storage shape: mutable segment, read-only segments, DiskSegment, bottom segments, WAL, caches, and maintenance activity.

Use this page to decide what to measure before tuning or troubleshooting.

Core Counters

Maintenance exposes the fastest view of the current LSM shape.

Counter What It Tells You
MutableSegmentRecordCount records currently in the writable mutable segment
ReadOnlySegmentsCount frozen in-memory segments waiting for merge
ReadOnlySegmentsRecordCount records waiting in read-only in-memory segments
InMemoryRecordCount mutable plus read-only segment records
TotalRecordCount physical records across segment layers
IsMerging normal merge is running
IsBottomSegmentsMerging bottom segment merge is running
BottomSegments.Count number of bottom disk segments

TotalRecordCount is a physical storage-shape counter. It can include older versions and deletion markers until merge removes them. Use Count() or CountFullScan() when you need live-record count.

Segment Movement Events

Events are the cleanest way to log segment movement without polling.

Event Use
OnMutableSegmentMovedForward mutable segment became read-only
OnMergeOperationStarted / OnMergeOperationEnded normal merge timing and result
OnBottomSegmentsMergeOperationStarted / OnBottomSegmentsMergeOperationEnded bottom merge timing and result
OnDiskSegmentCreated new disk segment files were created
OnDiskSegmentActivated new disk segment became part of the tree shape
OnCanNotDropReadOnlySegment cleanup could not drop a read-only segment
OnCanNotDropDiskSegment cleanup could not drop a disk segment
OnCanNotDropDiskSegmentCreator temporary merge output cleanup failed 
zoneTree.Maintenance.OnMergeOperationEnded += (_, result) =>
{
    Console.WriteLine($"Merge ended: {result}");
};

zoneTree.Maintenance.OnMutableSegmentMovedForward += tree =>
{
    Console.WriteLine(
        $"read-only segments={tree.ReadOnlySegmentsCount}, " +
        $"in-memory records={tree.InMemoryRecordCount}");
};

Failed drop events mean ZoneTree could not delete obsolete segment files, WAL files, or temporary merge output after the logical tree shape had moved forward. Keep the exception details and investigate the storage/provider error; the event usually indicates cleanup debt rather than a corrupted active tree.

Logger Signals

Configure a logger in production and retain logs around:

  • failed merges,
  • failed drops,
  • WAL read errors,
  • recovery warnings,
  • live backup failures,
  • unusually long maintenance operations.
using ZoneTree.Logger;

using var zoneTree = new ZoneTreeFactory<int, string>()
    .SetDataDirectory("data/app")
    .SetLogger(new ConsoleLogger(LogLevel.Info))
    .OpenOrCreate();

Write Pressure

Watch these when write throughput or memory changes:

Signal Meaning
rising MutableSegmentRecordCount current mutable segment is filling
rising ReadOnlySegmentsCount maintenance is not merging as fast as segments move forward
long merge duration merge IO, compression, serialization, or payload size is expensive
large WAL files in-memory segments are not yet merged, or WAL history is intentionally retained

Useful context:

  • MutableSegmentMaxItemCount,
  • value size,
  • WAL mode,
  • serializer cost,
  • storage write throughput,
  • maintainer settings.

Read Path

For disk reads, inspect:

Signal Meaning
segment counts how many layers may be searched
DefaultSparseArrayStepSize sparse index density
BlockCacheLifeTime how long inactive decompressed disk blocks stay cached
InactiveBlockCacheCleanupInterval how often inactive cache cleanup runs
disk compression block size random-read granularity and cache unit size
iterator cache contribution whether scans populate the shared block cache
circular key/value cache settings repeated same-record key/value reuse

For compressed disk segments, decompressed block cache behavior is usually more important than circular key/value caches.

See read-path caching.

Memory

OS process memory is not the same thing as live ZoneTree data. .NET may keep freed memory available for reuse.

Measure:

  • live managed object size,
  • allocation rate,
  • large object heap usage,
  • retained references,
  • iterator lifetimes,
  • mutable/read-only segment sizes,
  • decompressed block cache lifetime.

Common ZoneTree levers:

  • MutableSegmentMaxItemCount,
  • value size,
  • maintainer cleanup,
  • BlockCacheLifeTime,
  • iterator lifetime.

WAL And Recovery

Track:

  • WAL directory size,
  • recovery duration,
  • incomplete WAL tail reports,
  • checksum or deserialization failures,
  • serializer/comparer compatibility.

An incomplete tail after process termination is a normal recovery boundary. Checksum and deserialization failures are integrity signals and should be investigated.

See recovery and WAL modes.

Backup

For live backup, measure:

  • generation duration,
  • failed generation logs,
  • file transfer duration,
  • record batch size,
  • local retention behavior,
  • restore test results.

Live backup is generation based. A generation contains disk segment files and optional in-memory records for that backup point.

See backups.

Benchmark Shape

When recording benchmark or incident data, include:

  • key and value type,
  • serializers,
  • comparer,
  • WAL mode,
  • disk segment mode,
  • compression settings,
  • mutable segment size,
  • multipart min/max record count,
  • DiskSegmentMaxItemCount,
  • sparse array step size,
  • block cache lifetime,
  • storage hardware,
  • maintainer settings,
  • backup activity.

Without the shape, numbers are hard to compare.