Documentation
¶
Index ¶
- Constants
- func ExtractBlanketRegexLabels(query string) ([]string, error)
- func ExtractMetricNames(query string) ([]string, error)
- func ParseTimestamp(timestamp string) (time.Time, error)
- type GuardrailViolation
- type Guardrails
- type Loader
- type RealLoader
- func (p *RealLoader) ExecuteInstantQuery(ctx context.Context, query string, ts time.Time) (map[string]any, error)
- func (p *RealLoader) ExecuteRangeQuery(ctx context.Context, query string, queryStart, queryEnd time.Time, ...) (map[string]any, error)
- func (p *RealLoader) GetLabelNames(ctx context.Context, metricName string, start, end time.Time) ([]string, error)
- func (p *RealLoader) GetLabelValues(ctx context.Context, label, metricName string, start, end time.Time) ([]string, error)
- func (p *RealLoader) GetSeries(ctx context.Context, matches []string, start, end time.Time) ([]map[string]string, error)
- func (p *RealLoader) ListMetrics(ctx context.Context, nameRegex string) ([]string, error)
- func (p *RealLoader) ValidateMetricsExist(ctx context.Context, query string) error
- func (p *RealLoader) WithGuardrails(g *Guardrails) *RealLoader
Constants ¶
const ( GuardrailDisallowExplicitNameLabel = "disallow-explicit-name-label" GuardrailRequireLabelMatcher = "require-label-matcher" GuardrailDisallowBlanketRegex = "disallow-blanket-regex" GuardrailMaxMetricCardinality = "max-metric-cardinality" GuardrailMaxLabelCardinality = "max-label-cardinality" )
Guardrail name constants for use with ParseGuardrails
const ( // ListMetricsTimeRange is the time range used when listing metrics ListMetricsTimeRange = 1 * time.Hour // DefaultQueryTimeout is the default timeout for Prometheus queries DefaultQueryTimeout = 30 * time.Second )
Variables ¶
This section is empty.
Functions ¶
func ExtractBlanketRegexLabels ¶
ExtractBlanketRegexLabels extracts label names that use blanket regex patterns (.* or .+).
func ExtractMetricNames ¶
Types ¶
type GuardrailViolation ¶
GuardrailViolation is returned when a query violates a specific guardrail rule. It carries the guardrail name for structured logging.
func (*GuardrailViolation) Error ¶
func (e *GuardrailViolation) Error() string
type Guardrails ¶
type Guardrails struct {
// DisallowExplicitNameLabel prevents queries using explicit {__name__="..."} syntax
DisallowExplicitNameLabel bool
// RequireLabelMatcher ensures all vector selectors have at least one non-name label matcher
RequireLabelMatcher bool
// DisallowBlanketRegex prevents expensive regex patterns like .* or .+ on any label
DisallowBlanketRegex bool
// MaxMetricCardinality sets the maximum allowed series count per metric (0 = disabled)
MaxMetricCardinality uint64
// MaxLabelCardinality sets the maximum allowed label value count for blanket regex
// (0 = always disallow regex matcher provided DisallowBlanketRegex is true)
MaxLabelCardinality uint64
}
Guardrails provides safety checks for PromQL queries based on configurable rules.
func DefaultGuardrails ¶
func DefaultGuardrails() *Guardrails
DefaultGuardrails returns a Guardrails instance with all safety checks enabled.
func ParseGuardrails ¶
func ParseGuardrails(value string) (*Guardrails, error)
func (*Guardrails) IsSafeQuery ¶
IsSafeQuery analyzes a PromQL query string and returns false if it's deemed unsafe or too expensive based on the configured rules. If client is provided and MaxMetricCardinality is set, it checks TSDB metric cardinality. If client is provided and MaxLabelCardinality is set, it checks TSDB label cardinality for blanket regex.
Returns (false, error) if the query is invalid or violates a guardrail rule. The error message explains which rule was violated. Returns (true, nil) if the query is valid and passes all rules.
type Loader ¶
type Loader interface {
ListMetrics(ctx context.Context, nameRegex string) ([]string, error)
ExecuteRangeQuery(ctx context.Context, query string, start, end time.Time, step time.Duration) (map[string]any, error)
ExecuteInstantQuery(ctx context.Context, query string, time time.Time) (map[string]any, error)
GetLabelNames(ctx context.Context, metricName string, start, end time.Time) ([]string, error)
GetLabelValues(ctx context.Context, label string, metricName string, start, end time.Time) ([]string, error)
GetSeries(ctx context.Context, matches []string, start, end time.Time) ([]map[string]string, error)
}
Loader defines the interface for querying Prometheus
type RealLoader ¶
type RealLoader struct {
// contains filtered or unexported fields
}
RealLoader implements Loader using the Prometheus HTTP API.
func NewPrometheusClient ¶
func NewPrometheusClient(apiConfig api.Config) (*RealLoader, error)
func (*RealLoader) ExecuteInstantQuery ¶
func (*RealLoader) ExecuteRangeQuery ¶
func (*RealLoader) GetLabelNames ¶
func (*RealLoader) GetLabelValues ¶
func (*RealLoader) ListMetrics ¶
func (*RealLoader) ValidateMetricsExist ¶
func (p *RealLoader) ValidateMetricsExist(ctx context.Context, query string) error
ValidateMetricsExist validates that all metrics referenced in a query exist in Prometheus TSDB. This is an always-on validation that should be called before executing any query. It uses ListMetrics to fetch available metrics and ensures all metrics in the query exist.
func (*RealLoader) WithGuardrails ¶
func (p *RealLoader) WithGuardrails(g *Guardrails) *RealLoader
WithGuardrails sets a custom Guardrails configuration for the client.
Source Files