trace

package
v0.3.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 2, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

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

View Source
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

View Source
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

type GetPayload struct {
	ColumnFamilyID uint32
	Key            []byte
}

GetPayload encodes a Get operation payload

func DecodeGetPayload

func DecodeGetPayload(data []byte) (*GetPayload, error)

DecodeGetPayload decodes a get payload

func (*GetPayload) Encode

func (p *GetPayload) Encode() []byte

Encode encodes the get payload

type Header struct {
	Magic   uint64
	Version uint32
}

Header represents the trace file header

func DecodeHeader

func DecodeHeader(r io.Reader) (*Header, error)

DecodeHeader reads a header from the given reader

func (*Header) Encode

func (h *Header) Encode(w io.Writer) error

Encode writes the header to the given writer

type Reader

type Reader struct {
	// contains filtered or unexported fields
}

Reader reads trace records from an input stream.

func NewReader

func NewReader(r io.Reader) (*Reader, error)

NewReader creates a new trace reader.

func (*Reader) ComputeStats

func (tr *Reader) ComputeStats() (*TraceStats, error)

ComputeStats computes statistics from the trace file.

func (*Reader) Count

func (tr *Reader) Count() uint64

Count returns the number of records read so far.

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) Header

func (tr *Reader) Header() *Header

Header returns the trace file header.

func (*Reader) Iterate

func (tr *Reader) Iterate(fn func(*Record) error) error

Iterate iterates over all trace records, calling fn for each.

func (*Reader) Read

func (tr *Reader) Read() (*Record, error)

Read reads the next trace record. Returns io.EOF when there are no more records.

func (*Reader) ReadAll

func (tr *Reader) ReadAll() ([]*Record, error)

ReadAll reads all remaining trace records.

func (*Reader) Version added in v0.2.0

func (tr *Reader) Version() uint32

Version returns the trace file format version.

type Record

type Record struct {
	Timestamp time.Time
	Type      RecordType
	Payload   []byte
}

Record represents a single trace record

func DecodeRecord

func DecodeRecord(r io.Reader) (*Record, error)

DecodeRecord reads a record from the given reader

func (*Record) Encode

func (r *Record) Encode(w io.Writer) error

Encode writes the record to the given writer

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

func (tw *Writer) BytesWritten() int64

BytesWritten returns the approximate number of bytes written.

func (*Writer) Close

func (tw *Writer) Close() error

Close marks the writer as closed.

func (*Writer) Count

func (tw *Writer) Count() uint64

Count returns the number of records written.

func (*Writer) Truncated added in v0.3.0

func (tw *Writer) Truncated() bool

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

func (tw *Writer) WriteAt(timestamp time.Time, recordType RecordType, payload []byte) error

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

func (tw *Writer) WriteCompaction() error

WriteCompaction writes a Compaction trace record.

func (*Writer) WriteFlush

func (tw *Writer) WriteFlush() error

WriteFlush writes a Flush trace record.

func (*Writer) WriteGet

func (tw *Writer) WriteGet(cfID uint32, key []byte) error

WriteGet writes a Get trace record.

func (*Writer) WriteIterSeek

func (tw *Writer) WriteIterSeek(cfID uint32, key []byte) error

WriteIterSeek writes an iterator seek trace record.

func (*Writer) WriteWrite

func (tw *Writer) WriteWrite(cfID uint32, batchData []byte) error

WriteWrite writes a Write 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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL