Documentation
¶
Overview ¶
reader.go implements trace file reading for operation replay.
TraceReader in RocksDB reads traces one operation at a time. FileTraceReader is the file-based implementation with Reset support.
Reference: RocksDB v10.7.5
- include/rocksdb/trace_reader_writer.h (TraceReader interface)
- utilities/trace/file_trace_reader_writer.h (FileTraceReader)
- utilities/trace/file_trace_reader_writer.cc
replayer.go implements trace replay functionality.
Replayer in RocksDB replays captured traces against a database, supporting timing preservation and operation statistics.
Reference: RocksDB v10.7.5
- include/rocksdb/utilities/replayer.h
- trace_replay/trace_replay.h
- trace_replay/trace_replay.cc
Package trace implements operation tracing and replay for debugging.
Trace files record all database operations with timestamps, allowing users to replay workloads, debug issues, and analyze performance.
Trace File Format:
[Header] [Trace Record 1] [Trace Record 2] ...
Header (16 bytes):
Magic Number (8 bytes): "ROCKSTRC" Version (4 bytes) Reserved (4 bytes)
Trace Record:
Timestamp (8 bytes, nanoseconds) Type (1 byte) Payload Length (4 bytes, varint) Payload (variable)
Reference: RocksDB v10.7.5
- include/rocksdb/trace_record.h
- trace_replay/trace_replay.cc
writer.go implements trace file writing for operation tracing.
TraceWriter in RocksDB exports traces one operation at a time. FileTraceWriter is the file-based implementation.
Reference: RocksDB v10.7.5
- include/rocksdb/trace_reader_writer.h (TraceWriter interface)
- utilities/trace/file_trace_reader_writer.h (FileTraceWriter)
- utilities/trace/file_trace_reader_writer.cc
Index ¶
- Constants
- Variables
- type GetPayload
- type Header
- type Reader
- func (tr *Reader) ComputeStats() (*TraceStats, error)
- func (tr *Reader) Count() uint64
- func (tr *Reader) DecodeWritePayload(data []byte) (*WritePayload, error)
- func (tr *Reader) Header() *Header
- func (tr *Reader) Iterate(fn func(*Record) error) error
- func (tr *Reader) Read() (*Record, error)
- func (tr *Reader) ReadAll() ([]*Record, error)
- func (tr *Reader) Version() uint32
- type Record
- type RecordType
- type ReplayHandler
- type ReplayHandlerV2
- type ReplayStats
- type Replayer
- type ReplayerOptions
- type TraceStats
- type WritePayload
- type Writer
- func (tw *Writer) BytesWritten() int64
- func (tw *Writer) Close() error
- func (tw *Writer) Count() uint64
- func (tw *Writer) Truncated() bool
- func (tw *Writer) Write(recordType RecordType, payload []byte) error
- func (tw *Writer) WriteAt(timestamp time.Time, recordType RecordType, payload []byte) error
- func (tw *Writer) WriteCompaction() error
- func (tw *Writer) WriteFlush() error
- func (tw *Writer) WriteGet(cfID uint32, key []byte) error
- func (tw *Writer) WriteIterSeek(cfID uint32, key []byte) error
- func (tw *Writer) WriteWrite(cfID uint32, batchData []byte) error
- type WriterOption
Constants ¶
const ( // HeaderSize is the size of the trace file header HeaderSize = 16 // MagicNumber identifies a trace file MagicNumber uint64 = 0x524F434B53545243 // "ROCKSTRC" // CurrentVersion is the current trace format version. // Version 2 adds SequenceNumber to WritePayload for seqno-prefix verification. CurrentVersion uint32 = 2 // Version1 is the legacy format without sequence numbers. Version1 uint32 = 1 )
Constants for trace file format
Variables ¶
var ( // ErrInvalidTraceFile indicates the file is not a valid trace file ErrInvalidTraceFile = errors.New("trace: invalid trace file") // ErrUnsupportedVersion indicates an unsupported trace format version ErrUnsupportedVersion = errors.New("trace: unsupported version") )
Functions ¶
This section is empty.
Types ¶
type GetPayload ¶
GetPayload encodes a Get operation payload
func DecodeGetPayload ¶
func DecodeGetPayload(data []byte) (*GetPayload, error)
DecodeGetPayload decodes a get payload
type Header ¶
Header represents the trace file header
func DecodeHeader ¶
DecodeHeader reads a header from the given reader
type Reader ¶
type Reader struct {
// contains filtered or unexported fields
}
Reader reads trace records from an input stream.
func (*Reader) ComputeStats ¶
func (tr *Reader) ComputeStats() (*TraceStats, error)
ComputeStats computes statistics from the trace file.
func (*Reader) DecodeWritePayload ¶ added in v0.2.0
func (tr *Reader) DecodeWritePayload(data []byte) (*WritePayload, error)
DecodeWritePayload decodes a write payload using the correct version decoder. For version 2+, this includes the sequence number. For version 1, sequence number will be 0.
func (*Reader) Read ¶
Read reads the next trace record. Returns io.EOF when there are no more records.
type Record ¶
type Record struct {
Timestamp time.Time
Type RecordType
Payload []byte
}
Record represents a single trace record
func DecodeRecord ¶
DecodeRecord reads a record from the given reader
type RecordType ¶
type RecordType uint8
RecordType identifies the type of trace record
const ( // TypeWrite is a write batch operation TypeWrite RecordType = iota + 1 // TypeGet is a get operation TypeGet // TypeIterSeek is an iterator seek TypeIterSeek // TypeIterSeekForPrev is an iterator seek for prev TypeIterSeekForPrev // TypeFlush is a flush operation TypeFlush // TypeCompaction is a compaction operation TypeCompaction // TypeMultiGet is a multi-get operation TypeMultiGet // TypeNewIterator is creating a new iterator TypeNewIterator )
func (RecordType) String ¶
func (t RecordType) String() string
String returns the string representation of the record type
type ReplayHandler ¶
type ReplayHandler interface {
// HandleWrite handles a write operation
HandleWrite(cfID uint32, batchData []byte) error
// HandleGet handles a get operation
HandleGet(cfID uint32, key []byte) error
// HandleIterSeek handles an iterator seek operation
HandleIterSeek(cfID uint32, key []byte) error
// HandleFlush handles a flush operation
HandleFlush() error
// HandleCompaction handles a compaction operation
HandleCompaction() error
}
ReplayHandler handles replayed operations.
type ReplayHandlerV2 ¶ added in v0.2.0
type ReplayHandlerV2 interface {
ReplayHandler
// HandleWriteWithSeqno handles a write operation with its assigned sequence number.
// seqno is the sequence number assigned by the DB after the write completed.
// For version 1 traces, seqno will be 0.
HandleWriteWithSeqno(cfID uint32, seqno uint64, batchData []byte) error
}
ReplayHandlerV2 extends ReplayHandler with sequence number support. Used for seqno-prefix verification during crash recovery testing.
type ReplayStats ¶
type ReplayStats struct {
TotalRecords uint64
SuccessfulOps uint64
FailedOps uint64
Duration time.Duration
OperationCounts map[RecordType]uint64
}
ReplayStats contains statistics about the replay
type Replayer ¶
type Replayer struct {
// contains filtered or unexported fields
}
Replayer replays trace records against a database.
func NewReplayer ¶
func NewReplayer(reader *Reader, handler ReplayHandler, opts ReplayerOptions) *Replayer
NewReplayer creates a new replayer
func (*Replayer) Replay ¶
func (r *Replayer) Replay() (*ReplayStats, error)
Replay replays all trace records
type ReplayerOptions ¶
type ReplayerOptions struct {
// PreserveTiming delays operations to match original timing
PreserveTiming bool
// SpeedMultiplier speeds up or slows down replay (1.0 = original speed)
SpeedMultiplier float64
}
ReplayerOptions configures the replayer
func DefaultReplayerOptions ¶
func DefaultReplayerOptions() ReplayerOptions
DefaultReplayerOptions returns default replayer options
type TraceStats ¶
type TraceStats struct {
TotalRecords uint64
Duration int64 // nanoseconds between first and last record
RecordCounts map[RecordType]uint64
}
TraceStats represents statistics about a trace file.
type WritePayload ¶
type WritePayload struct {
ColumnFamilyID uint32
SequenceNumber uint64 // Seqno assigned by DB after Write() - for seqno-prefix verification
Data []byte // WriteBatch data
}
WritePayload encodes a Write operation payload.
Version 2 format (current):
ColumnFamilyID (4 bytes) SequenceNumber (8 bytes) - seqno assigned by DB after Write() Data (variable) - WriteBatch bytes
Version 1 format (legacy):
ColumnFamilyID (4 bytes) Data (variable) - WriteBatch bytes
func DecodeWritePayload ¶
func DecodeWritePayload(data []byte) (*WritePayload, error)
DecodeWritePayload decodes a write payload. Supports both version 1 (no seqno) and version 2 (with seqno) formats.
func DecodeWritePayloadV2 ¶ added in v0.2.0
func DecodeWritePayloadV2(data []byte) (*WritePayload, error)
DecodeWritePayloadV2 decodes a version 2 write payload with sequence number.
func (*WritePayload) Encode ¶
func (p *WritePayload) Encode() []byte
Encode encodes the write payload (version 2 format with sequence number).
type Writer ¶
type Writer struct {
// contains filtered or unexported fields
}
Writer writes trace records to an output stream.
func NewWriter ¶
func NewWriter(w io.Writer, opts ...WriterOption) (*Writer, error)
NewWriter creates a new trace writer.
func (*Writer) BytesWritten ¶ added in v0.3.0
BytesWritten returns the approximate number of bytes written.
func (*Writer) Truncated ¶ added in v0.3.0
Truncated returns true if the writer stopped accepting records due to size limit.
func (*Writer) Write ¶
func (tw *Writer) Write(recordType RecordType, payload []byte) error
Write writes a trace record with the current timestamp.
func (*Writer) WriteAt ¶
WriteAt writes a trace record with a specific timestamp. If a max size is configured and exceeded, the write is silently dropped.
func (*Writer) WriteCompaction ¶
WriteCompaction writes a Compaction trace record.
func (*Writer) WriteFlush ¶
WriteFlush writes a Flush trace record.
func (*Writer) WriteIterSeek ¶
WriteIterSeek writes an iterator seek trace record.
type WriterOption ¶ added in v0.3.0
type WriterOption func(*Writer)
WriterOption configures a Writer.
func WithMaxBytes ¶ added in v0.3.0
func WithMaxBytes(maxBytes int64) WriterOption
WithMaxBytes sets the maximum bytes to write before stopping. When the limit is reached, subsequent writes are silently dropped. Use 0 (default) for unlimited.