local

Documentation

Overview

Package local contains the local time series storage used by Prometheus.

Index

• Constants
• Variables
• func DumpHeads(filename string, out io.Writer) error
• type MemorySeriesStorage
  • func NewMemorySeriesStorage(o *MemorySeriesStorageOptions) *MemorySeriesStorage
  • func NewTestStorage(t testutil.T, encoding chunkEncoding) (*MemorySeriesStorage, testutil.Closer)
  • func (s *MemorySeriesStorage) Append(sample *model.Sample) error
  • func (s *MemorySeriesStorage) Collect(ch chan<- prometheus.Metric)
  • func (s *MemorySeriesStorage) Describe(ch chan<- *prometheus.Desc)
  • func (s *MemorySeriesStorage) DropMetricsForFingerprints(fps ...model.Fingerprint)
  • func (s *MemorySeriesStorage) LabelValuesForLabelName(labelName model.LabelName) model.LabelValues
  • func (s *MemorySeriesStorage) LastSampleForFingerprint(fp model.Fingerprint) model.Sample
  • func (s *MemorySeriesStorage) MetricsForLabelMatchers(from, through model.Time, matchers ...*metric.LabelMatcher) map[model.Fingerprint]metric.Metric
  • func (s *MemorySeriesStorage) NeedsThrottling() bool
  • func (s *MemorySeriesStorage) NewPreloader() Preloader
  • func (s *MemorySeriesStorage) Start() (err error)
  • func (s *MemorySeriesStorage) Stop() error
  • func (s *MemorySeriesStorage) WaitForIndexing()
• type MemorySeriesStorageOptions
• type Preloader
• type Querier
• type SeriesIterator
• type Storage
• type SyncStrategy
  • func (ss *SyncStrategy) Set(s string) error
  • func (ss SyncStrategy) String() string

Constants

const (
	// Version of the storage as it can be found in the version file.
	// Increment to protect against incompatible changes.
	Version = 1
)

Variables

var (
	// ErrOutOfOrderSample is returned if a sample has a timestamp before the latest
	// timestamp in the series it is appended to.
	ErrOutOfOrderSample = fmt.Errorf("sample timestamp out of order")
	// ErrDuplicateSampleForTimestamp is returned if a sample has the same
	// timestamp as the latest sample in the series it is appended to but a
	// different value. (Appending an identical sample is a no-op and does
	// not cause an error.)
	ErrDuplicateSampleForTimestamp = fmt.Errorf("sample with repeated timestamp but different value")
)

var DefaultChunkEncoding = doubleDelta

DefaultChunkEncoding can be changed via a flag.

var ZeroSample = model.Sample{Timestamp: model.Earliest}

ZeroSample is the pseudo zero-value of model.Sample used by the local package to signal a non-existing sample. It is a Sample with timestamp model.Earliest, value 0.0, and metric nil. Note that the natural zero value of Sample has a timestamp of 0, which is possible to appear in a real Sample and thus not suitable to signal a non-existing Sample.

var ZeroSamplePair = model.SamplePair{Timestamp: model.Earliest}

ZeroSamplePair is the pseudo zero-value of model.SamplePair used by the local package to signal a non-existing sample pair. It is a SamplePair with timestamp model.Earliest and value 0.0. Note that the natural zero value of SamplePair has a timestamp of 0, which is possible to appear in a real SamplePair and thus not suitable to signal a non-existing SamplePair.

Functions

func DumpHeads

func DumpHeads(filename string, out io.Writer) error

DumpHeads writes the metadata of the provided heads file in a human-readable form.

Types

type MemorySeriesStorage

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

func NewMemorySeriesStorage

func NewMemorySeriesStorage(o *MemorySeriesStorageOptions) *MemorySeriesStorage

NewMemorySeriesStorage returns a newly allocated Storage. Storage.Serve still has to be called to start the storage.

func NewTestStorage

func NewTestStorage(t testutil.T, encoding chunkEncoding) (*MemorySeriesStorage, testutil.Closer)

NewTestStorage creates a storage instance backed by files in a temporary directory. The returned storage is already in serving state. Upon closing the returned test.Closer, the temporary directory is cleaned up.

func (*MemorySeriesStorage) Append

func (s *MemorySeriesStorage) Append(sample *model.Sample) error

Append implements Storage.

func (*MemorySeriesStorage) Collect

func (s *MemorySeriesStorage) Collect(ch chan<- prometheus.Metric)

Collect implements prometheus.Collector.

func (*MemorySeriesStorage) Describe

func (s *MemorySeriesStorage) Describe(ch chan<- *prometheus.Desc)

Describe implements prometheus.Collector.

func (*MemorySeriesStorage) DropMetricsForFingerprints

func (s *MemorySeriesStorage) DropMetricsForFingerprints(fps ...model.Fingerprint)

DropMetric implements Storage.

func (*MemorySeriesStorage) LabelValuesForLabelName

func (s *MemorySeriesStorage) LabelValuesForLabelName(labelName model.LabelName) model.LabelValues

LabelValuesForLabelName implements Storage.

func (*MemorySeriesStorage) LastSampleForFingerprint

func (s *MemorySeriesStorage) LastSampleForFingerprint(fp model.Fingerprint) model.Sample

LastSampleForFingerprint implements Storage.

func (*MemorySeriesStorage) MetricsForLabelMatchers

func (s *MemorySeriesStorage) MetricsForLabelMatchers(
	from, through model.Time,
	matchers ...*metric.LabelMatcher,
) map[model.Fingerprint]metric.Metric

MetricsForLabelMatchers implements Storage.

func (*MemorySeriesStorage) NeedsThrottling

func (s *MemorySeriesStorage) NeedsThrottling() bool

NeedsThrottling implements Storage.

func (*MemorySeriesStorage) NewPreloader

func (s *MemorySeriesStorage) NewPreloader() Preloader

NewPreloader implements Storage.

func (*MemorySeriesStorage) Start

func (s *MemorySeriesStorage) Start() (err error)

Start implements Storage.

func (*MemorySeriesStorage) Stop

func (s *MemorySeriesStorage) Stop() error

Stop implements Storage.

func (*MemorySeriesStorage) WaitForIndexing

func (s *MemorySeriesStorage) WaitForIndexing()

WaitForIndexing implements Storage.

type MemorySeriesStorageOptions

type MemorySeriesStorageOptions struct {
	MemoryChunks               int           // How many chunks to keep in memory.
	MaxChunksToPersist         int           // Max number of chunks waiting to be persisted.
	PersistenceStoragePath     string        // Location of persistence files.
	PersistenceRetentionPeriod time.Duration // Chunks at least that old are dropped.
	CheckpointInterval         time.Duration // How often to checkpoint the series map and head chunks.
	CheckpointDirtySeriesLimit int           // How many dirty series will trigger an early checkpoint.
	Dirty                      bool          // Force the storage to consider itself dirty on startup.
	PedanticChecks             bool          // If dirty, perform crash-recovery checks on each series file.
	SyncStrategy               SyncStrategy  // Which sync strategy to apply to series files.
	MinShrinkRatio             float64       // Minimum ratio a series file has to shrink during truncation.
	NumMutexes                 int           // Number of mutexes used for stochastic fingerprint locking.
}

MemorySeriesStorageOptions contains options needed by NewMemorySeriesStorage. It is not safe to leave any of those at their zero values.

type Preloader

type Preloader interface {
	PreloadRange(
		fp model.Fingerprint,
		from, through model.Time,
	) SeriesIterator
	PreloadInstant(
		fp model.Fingerprint,
		timestamp model.Time, stalenessDelta time.Duration,
	) SeriesIterator
	// Close unpins any previously requested series data from memory.
	Close()
}

A Preloader preloads series data necessary for a query into memory, pins it until released via Close(), and returns an iterator for the pinned data. Its methods are generally not goroutine-safe.

type Querier

type Querier interface {
	// NewPreloader returns a new Preloader which allows preloading and pinning
	// series data into memory for use within a query.
	NewPreloader() Preloader
	// MetricsForLabelMatchers returns the metrics from storage that satisfy
	// the given label matchers. At least one label matcher must be
	// specified that does not match the empty string. The times from and
	// through are hints for the storage to optimize the search. The storage
	// MAY exclude metrics that have no samples in the specified interval
	// from the returned map. In doubt, specify model.Earliest for from and
	// model.Latest for through.
	MetricsForLabelMatchers(from, through model.Time, matchers ...*metric.LabelMatcher) map[model.Fingerprint]metric.Metric
	// LastSampleForFingerprint returns the last sample that has been
	// ingested for the provided fingerprint. If this instance of the
	// Storage has never ingested a sample for the provided fingerprint (or
	// the last ingestion is so long ago that the series has been archived),
	// ZeroSample is returned.
	LastSampleForFingerprint(model.Fingerprint) model.Sample
	// Get all of the label values that are associated with a given label name.
	LabelValuesForLabelName(model.LabelName) model.LabelValues
}

Querier allows querying a time series storage.

type SeriesIterator

type SeriesIterator interface {
	// Gets the value that is closest before the given time. In case a value
	// exists at precisely the given time, that value is returned. If no
	// applicable value exists, ZeroSamplePair is returned.
	ValueAtOrBeforeTime(model.Time) model.SamplePair
	// Gets all values contained within a given interval.
	RangeValues(metric.Interval) []model.SamplePair
}

SeriesIterator enables efficient access of sample values in a series. Its methods are not goroutine-safe. A SeriesIterator iterates over a snapshot of a series, i.e. it is safe to continue using a SeriesIterator after or during modifying the corresponding series, but the iterator will represent the state of the series prior to the modification.

type Storage

type Storage interface {
	Querier

	// This SampleAppender needs multiple samples for the same fingerprint to be
	// submitted in chronological order, from oldest to newest. When Append has
	// returned, the appended sample might not be queryable immediately. (Use
	// WaitForIndexing to wait for complete processing.) The implementation might
	// remove labels with empty value from the provided Sample as those labels
	// are considered equivalent to a label not present at all.
	//
	// Appending is throttled if the Storage has too many chunks in memory
	// already or has too many chunks waiting for persistence.
	storage.SampleAppender

	// Drop all time series associated with the given fingerprints.
	DropMetricsForFingerprints(...model.Fingerprint)
	// Run the various maintenance loops in goroutines. Returns when the
	// storage is ready to use. Keeps everything running in the background
	// until Stop is called.
	Start() error
	// Stop shuts down the Storage gracefully, flushes all pending
	// operations, stops all maintenance loops,and frees all resources.
	Stop() error
	// WaitForIndexing returns once all samples in the storage are
	// indexed. Indexing is needed for FingerprintsForLabelMatchers and
	// LabelValuesForLabelName and may lag behind.
	WaitForIndexing()
}

Storage ingests and manages samples, along with various indexes. All methods are goroutine-safe. Storage implements storage.SampleAppender.

type SyncStrategy

type SyncStrategy int

SyncStrategy is an enum to select a sync strategy for series files.

const (
	Never SyncStrategy
	Always
	Adaptive
)

Possible values for SyncStrategy.

func (*SyncStrategy) Set

func (ss *SyncStrategy) Set(s string) error

Set implements flag.Value.

func (SyncStrategy) String

func (ss SyncStrategy) String() string

String implements flag.Value.