Documentation
¶
Overview ¶
Package promql is an optional adapter that bridges the storage fetch contract (query/fetch) to the Prometheus storage.Queryable interface. It does not own a PromQL engine: the embedder (e.g. go-faster/oteldb, which already has PromQL/LogQL/TraceQL engines) drives its own promql.Engine over the Queryable this package returns. The storage library proper stops at the fetch seam and stays language- and Prometheus-free; this package is the only one importing github.com/prometheus/prometheus, and importing it is opt-in.
Condition extraction lives here (the language layer), never in storage: a Prometheus matcher that can match the empty string (e.g. `!=`, `!~`, `=""`) would wrongly exclude series that lack the label if pushed into the postings index, so only index-safe matchers are pushed down; every returned series is then re-checked against the full matcher set.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func MatchesAll ¶ added in v0.9.0
MatchesAll reports whether a series' labels satisfy every matcher, treating an absent label as the empty string (Prometheus semantics). It is the post-fetch re-check companion to PushableMatchers: exported so an embedder's pushdown path re-checks the full matcher set the same way Queryable does.
func PromLabels ¶ added in v0.9.0
PromLabels projects a storage series identity to a Prometheus label set: every resource, scope, and (folded) point attribute becomes a label, with the internal reserved labels (except __name__) hidden. Scope name/version are exposed under the otel.scope.* keys, the same labels the head indexes.
PromLabels is exported so an embedder can render a signal.Series (e.g. the identity carried alongside an github.com/oteldb/storage.Storage.AggregateMetrics result) as PromQL labels without duplicating this projection.
func PushableMatchers ¶ added in v0.9.0
PushableMatchers returns fetch matchers for the index-safe subset: matchers that do not match the empty string. A matcher that matches "" (negated/absent) cannot prune via the postings index without wrongly dropping series that lack the label, so it is enforced only by the post-fetch re-check in MatchesAll.
It is exported so an embedder building a pushdown path over the fetch/aggregate seam (e.g. oteldb's *_over_time aggregate pushdown) can lower the same index-safe matcher set the Queryable uses, keeping matcher translation in one place.
Types ¶
type LabelCache ¶ added in v0.24.0
type LabelCache struct {
// contains filtered or unexported fields
}
LabelCache memoizes a series identity's projected Prometheus label set. The projection is a pure function of the content-addressed signal.SeriesID, so a cached entry is always valid; the cache is bounded by series cardinality (the same set Prometheus keeps resident). It is safe for concurrent use and may be shared across a Queryable's queriers and — via NewQueryableWithCache — across successive Queryables over the engine's lifetime.
func NewLabelCache ¶ added in v0.24.0
func NewLabelCache() *LabelCache
NewLabelCache returns an empty LabelCache ready to share across queries.
func (*LabelCache) Len ¶ added in v0.24.0
func (c *LabelCache) Len() int
Len reports the number of interned series projections. It lets an embedder observe the cache's resident size (e.g. to expose a metric or decide when to swap in a fresh cache on series churn).
type Queryable ¶
type Queryable struct {
// contains filtered or unexported fields
}
Queryable adapts a fetch.Fetcher (one tenant's engine) to the Prometheus storage.Queryable interface for a single tenant.
func NewQueryable ¶
NewQueryable returns a Prometheus storage.Queryable backed by fetcher for the given tenant. A single Queryable reused across queries (the embedder's per-tenant adapter) memoizes label projections, so repeated queries pay the projection cost once per series.
Each call allocates a fresh LabelCache. An embedder that takes a new fetcher per query (to observe the latest head) but wants label projections interned across the engine's lifetime should hold a LabelCache itself and use NewQueryableWithCache.
func NewQueryableWithCache ¶ added in v0.24.0
func NewQueryableWithCache(fetcher fetch.Fetcher, tenant signal.TenantID, cache *LabelCache) *Queryable
NewQueryableWithCache is NewQueryable with an explicit, caller-owned LabelCache. The cache is keyed by content-addressed signal.SeriesID, so an entry is valid for the life of the series and may be shared across Queryables built over different fetchers of the same engine — letting the embedder intern label projections for the engine's lifetime rather than per query. The cache is safe for concurrent use.
func (*Queryable) QuerierWithScope ¶ added in v0.37.0
QuerierWithScope is Queryable.Querier bound to a caller-supplied fetch.Scope, for an embedder whose logical query spans more than this querier — its own reads plus the ones it makes here. Sharing the scope is what keeps admission from treating those as unrelated queries and blocking the caller against its own reservation.
Source Files