block

Documentation

Index

• Variables
• func Flush(dataDir string, series []SeriesFlush) (string, error)
• func FlushCompacted(dataDir string, series []SeriesFlush, level int, sources []string) (string, error)
• type BlockMeta
  • func ReadMeta(dir string) (BlockMeta, error)
• type BlockStats
• type ChunkData
• type CompactionInfo
• type Reader
  • func Open(dir string) (*Reader, error)
  • func (r *Reader) AllPostings() []uint64
  • func (r *Reader) ChunkIterator(ref index.ChunkRef) (chunkenc.ChunkIterator, error)
  • func (r *Reader) Close() error
  • func (r *Reader) Condemn()
  • func (r *Reader) Dir() string
  • func (r *Reader) LabelValues(name string) []string
  • func (r *Reader) Labels(ref uint64) ([]labels.Label, bool)
  • func (r *Reader) Postings(name, value string) []uint64
  • func (r *Reader) RawChunkData(ref index.ChunkRef) ([]byte, error)
  • func (r *Reader) Ref()
  • func (r *Reader) Release() bool
  • func (r *Reader) Series() []index.SeriesEntry
  • func (r *Reader) SeriesByRef(ref uint64) (index.SeriesEntry, bool)
  • func (r *Reader) SeriesChunkIterator(ref uint64, mint, maxt int64) (chunkenc.ChunkIterator, error)
• type SeriesFlush
• type ValidationError
  • func Validate(dir string) []ValidationError
  • func (e ValidationError) Error() string

Variables

var (
	ErrInvalidChunkMagic   = errors.New("block: invalid chunk file magic")
	ErrInvalidChunkVersion = errors.New("block: unsupported chunk file version")
	ErrCorruptChunk        = errors.New("block: corrupt chunk (CRC mismatch)")
	ErrChunkNotFound       = errors.New("block: chunk ref out of bounds")
)

Functions

func Flush

func Flush(dataDir string, series []SeriesFlush) (string, error)

Flush writes a new immutable block from the given series data. It creates a ULID-named directory under dataDir containing:

• chunks/ with segment files
• index file
• meta.json (written last as the immutability gate)

Returns the block ULID and any error.

func FlushCompacted

func FlushCompacted(dataDir string, series []SeriesFlush, level int, sources []string) (string, error)

FlushCompacted writes a new immutable block from compacted series data, recording the compaction level and source block ULIDs.

Types

type BlockMeta

type BlockMeta struct {
	ULID       string         `json:"ulid"`
	MinTime    int64          `json:"minTime"`
	MaxTime    int64          `json:"maxTime"`
	Stats      BlockStats     `json:"stats"`
	Compaction CompactionInfo `json:"compaction"`
	Version    int            `json:"version"`
}

BlockMeta describes a block on disk.

func ReadMeta

func ReadMeta(dir string) (BlockMeta, error)

ReadMeta reads and returns the BlockMeta for a block directory. Exported for use by ingotctl.

type BlockStats

type BlockStats struct {
	NumSamples int `json:"numSamples"`
	NumSeries  int `json:"numSeries"`
	NumChunks  int `json:"numChunks"`
}

BlockStats holds summary statistics for a block.

type ChunkData

type ChunkData struct {
	MinT int64
	MaxT int64
	Data []byte // raw XOR chunk bytes (including 2-byte sample count header)
}

ChunkData describes a single chunk to be flushed to a block.

type CompactionInfo

type CompactionInfo struct {
	Level   int      `json:"level"`
	Sources []string `json:"sources"`
}

CompactionInfo records the block's compaction lineage.

type Reader

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

Reader provides read access to an immutable on-disk block.

func Open

func Open(dir string) (*Reader, error)

Open opens a block directory for reading. Chunk files are mmap'd.

func (*Reader) AllPostings

func (r *Reader) AllPostings() []uint64

AllPostings returns sorted refs for all series in the block.

func (*Reader) ChunkIterator

func (r *Reader) ChunkIterator(ref index.ChunkRef) (chunkenc.ChunkIterator, error)

ChunkIterator returns an iterator for a chunk at the given ref.

func (*Reader) Close

func (r *Reader) Close() error

Close releases all resources (munmaps chunk files).

func (*Reader) Condemn

func (r *Reader) Condemn()

Condemn marks the block for directory deletion when refcount reaches zero.

func (*Reader) Dir

func (r *Reader) Dir() string

Dir returns the block directory path.

func (*Reader) LabelValues

func (r *Reader) LabelValues(name string) []string

LabelValues returns sorted unique values for the given label name.

func (*Reader) Labels

func (r *Reader) Labels(ref uint64) ([]labels.Label, bool)

Labels returns the labels for a series by ref.

func (*Reader) Postings

func (r *Reader) Postings(name, value string) []uint64

Postings returns sorted series refs matching label name=value.

func (*Reader) RawChunkData

func (r *Reader) RawChunkData(ref index.ChunkRef) ([]byte, error)

RawChunkData returns the raw chunk bytes at the given ref (for compaction).

func (*Reader) Ref

func (r *Reader) Ref()

Ref increments the refcount. Called by Querier on snapshot.

func (*Reader) Release

func (r *Reader) Release() bool

Release decrements the refcount. Returns true if the refcount hit zero and the block is condemned (caller should delete the directory).

func (*Reader) Series

func (r *Reader) Series() []index.SeriesEntry

Series returns all series entries from the index.

func (*Reader) SeriesByRef

func (r *Reader) SeriesByRef(ref uint64) (index.SeriesEntry, bool)

SeriesByRef looks up a series by ref.

func (*Reader) SeriesChunkIterator

func (r *Reader) SeriesChunkIterator(ref uint64, mint, maxt int64) (chunkenc.ChunkIterator, error)

SeriesChunkIterator returns an iterator over all chunks for a series in a time range. Chunks are iterated in order.

type SeriesFlush

type SeriesFlush struct {
	Ref    uint64
	Labels []labels.Label
	Chunks []ChunkData
}

SeriesFlush describes a series with its sealed chunks for block writing.

type ValidationError

type ValidationError struct {
	Block   string // ULID or directory name
	Section string // "meta", "index", "chunks"
	Detail  string
}

ValidationError describes a single integrity issue found during validation.

func Validate

func Validate(dir string) []ValidationError

Validate performs integrity checks on a single block directory. It checks meta.json consistency, index integrity (magic, version, TOC CRC), and CRC validation on every chunk entry.

func (ValidationError) Error

func (e ValidationError) Error() string