1// Copyright 2014 The Prometheus Authors 2// Licensed under the Apache License, Version 2.0 (the "License"); 3// you may not use this file except in compliance with the License. 4// You may obtain a copy of the License at 5// 6// http://www.apache.org/licenses/LICENSE-2.0 7// 8// Unless required by applicable law or agreed to in writing, software 9// distributed under the License is distributed on an "AS IS" BASIS, 10// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 11// See the License for the specific language governing permissions and 12// limitations under the License. 13 14package storage 15 16import ( 17 "context" 18 "errors" 19 20 "github.com/prometheus/prometheus/pkg/labels" 21) 22 23// The errors exposed. 24var ( 25 ErrNotFound = errors.New("not found") 26 ErrOutOfOrderSample = errors.New("out of order sample") 27 ErrDuplicateSampleForTimestamp = errors.New("duplicate sample for timestamp") 28 ErrOutOfBounds = errors.New("out of bounds") 29) 30 31// Storage ingests and manages samples, along with various indexes. All methods 32// are goroutine-safe. Storage implements storage.SampleAppender. 33type Storage interface { 34 Queryable 35 36 // StartTime returns the oldest timestamp stored in the storage. 37 StartTime() (int64, error) 38 39 // Appender returns a new appender against the storage. 40 Appender() (Appender, error) 41 42 // Close closes the storage and all its underlying resources. 43 Close() error 44} 45 46// A Queryable handles queries against a storage. 47type Queryable interface { 48 // Querier returns a new Querier on the storage. 49 Querier(ctx context.Context, mint, maxt int64) (Querier, error) 50} 51 52// Querier provides reading access to time series data. 53type Querier interface { 54 // Select returns a set of series that matches the given label matchers. 55 Select(*SelectParams, ...*labels.Matcher) (SeriesSet, Warnings, error) 56 57 // LabelValues returns all potential values for a label name. 58 LabelValues(name string) ([]string, Warnings, error) 59 60 // LabelNames returns all the unique label names present in the block in sorted order. 61 LabelNames() ([]string, Warnings, error) 62 63 // Close releases the resources of the Querier. 64 Close() error 65} 66 67// SelectParams specifies parameters passed to data selections. 68type SelectParams struct { 69 Start int64 // Start time in milliseconds for this select. 70 End int64 // End time in milliseconds for this select. 71 72 Step int64 // Query step size in milliseconds. 73 Func string // String representation of surrounding function or aggregation. 74 75 Grouping []string // List of label names used in aggregation. 76 By bool // Indicate whether it is without or by. 77 Range int64 // Range vector selector range in milliseconds. 78} 79 80// QueryableFunc is an adapter to allow the use of ordinary functions as 81// Queryables. It follows the idea of http.HandlerFunc. 82type QueryableFunc func(ctx context.Context, mint, maxt int64) (Querier, error) 83 84// Querier calls f() with the given parameters. 85func (f QueryableFunc) Querier(ctx context.Context, mint, maxt int64) (Querier, error) { 86 return f(ctx, mint, maxt) 87} 88 89// Appender provides batched appends against a storage. 90type Appender interface { 91 Add(l labels.Labels, t int64, v float64) (uint64, error) 92 93 AddFast(l labels.Labels, ref uint64, t int64, v float64) error 94 95 // Commit submits the collected samples and purges the batch. 96 Commit() error 97 98 Rollback() error 99} 100 101// SeriesSet contains a set of series. 102type SeriesSet interface { 103 Next() bool 104 At() Series 105 Err() error 106} 107 108// Series represents a single time series. 109type Series interface { 110 // Labels returns the complete set of labels identifying the series. 111 Labels() labels.Labels 112 113 // Iterator returns a new iterator of the data of the series. 114 Iterator() SeriesIterator 115} 116 117// SeriesIterator iterates over the data of a time series. 118type SeriesIterator interface { 119 // Seek advances the iterator forward to the value at or after 120 // the given timestamp. 121 Seek(t int64) bool 122 // At returns the current timestamp/value pair. 123 At() (t int64, v float64) 124 // Next advances the iterator by one. 125 Next() bool 126 // Err returns the current error. 127 Err() error 128} 129 130type Warnings []error 131