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.
Source Files