import { Code } from '@astrojs/starlight/components';
import tracingSubscriber from '/../examples/src/tracing_subscriber.rs?raw'
import readTracing from '/../examples/src/read_tracing.rs?raw'
Tracing in SlateDB#
SlateDB uses the tracing library for logging and diagnostics. This provides structured, contextual logging that helps debug and monitor your database operations.
Here's a basic example showing how to consume tracing logs with tracing_subscriber and SlateDB:
Tracing Read Operation#
SlateDB provides structured tracing spans for read operations, allowing you to track and measure the performance of individual reads. When enabled, SlateDB creates a hierarchy of spans that wrap different parts of the read path:
Span Description Fields slatedb.readRoot span for a read operation (get, scan, or scan_prefix_by_recency). trace_idslatedb.read.memtableRecords each memtable lookup. trace_idslatedb.read.read_filtersRecords reading filters for an SST. trace_id, sst_id, sst_level, cachedslatedb.read.evaluate_filterRecords evaluating a named filter for an SST. trace_id, sst_id, sst_level, filter_name, resultslatedb.read.read_indexRecords reading the index for an SST. trace_id, sst_id, sst_level, cachedslatedb.read.read_blocksRecords reading data blocks for an SST. trace_id, sst_id, sst_level, cache_hits, cache_missesslatedb.read.mergeRecords a call to the merge operator during a read. trace_id, num_operands
All slatedb.read.* spans are child spans of the root slatedb.read span.
Field meanings:
trace_id — The value from TracingOptions, used to correlate spans from the same read operation.sst_id — The identifier of the SST involved in the span.sst_level: The level that contains the SST is l0 or sorted_run:{id}.cached: true if the filter or index came from the cache or a concurrent cache lookup fetched it. Otherwise, the value is false. The field can be absent if the read stops before the filter or index is read.cache_hits: The number of requested data blocks that the cache supplied, including blocks from a concurrent fetch.cache_misses: The number of requested data blocks that SlateDB read from object storage.filter_name: The name of the filter policy being evaluated.result — The boolean result of evaluating the filter.num_operands: The number of input values for the merge.
A merge batch is a group of merge operands processed together. SlateDB creates one slatedb.read.merge span for each batch.
SlateDB creates a final span when it combines the batch results with an optional base value.
In the final span, num_operands includes the base value when the base value is present.
These spans are only created when you provide TracingOptions to the read operation.
All spans listed above are created at tracing level INFO, except for slatedb.read.memtable.
Due to the potential huge number of spans slatedb.read.memtable created during scan operations, slatedb.read.memtable spans are created at tracing level DEBUG.
Configuring TracingOptions#
Read operations (get, scan, scan_prefix_by_recency) can be traced by passing TracingOptions via the corresponding options struct. Use ReadOptions::with_tracing_options() for point reads and ScanOptions::with_tracing_options() for scans.
The trace_id field in TracingOptions allows you to correlate spans of the same read operation.
Here's an example of enabling tracing for a get operation: