lokicompliance

Documentation

Overview

Package lokicompliance provides utilities for Loki/LogQL compliance testing.

Packagel lokicompliance provides utilities for Loki/LogQL compliance testing.

Index

• func GenerateLogs(ctx context.Context, targets []string, opts GenerateOptions) error
• type Comparer
  • func New(refAPI, testAPI LokiAPI) *Comparer
  • func (c *Comparer) Compare(ctx context.Context, tc *TestCase) (*Result, error)
• type Config
  • func Load(content []byte) (*Config, error)
  • func LoadFromFiles(filenames []string) (*Config, error)
• type GenerateOptions
• type LogEntry
  • func NewLogEntry(r *rand.Rand, ts time.Time) LogEntry
  • func (e LogEntry) EncodeJSON(enc *jx.Encoder)
  • func (e LogEntry) JSON() string
  • func (e LogEntry) OTEL(r plog.LogRecord)
• type LokiAPI
• type QueryParameters
• type Result
  • func (r *Result) Success() bool
• type TargetConfig
• type TestCase
  • func ExpandQuery(cfg *Config, start, end time.Time, step time.Duration) (r []*TestCase, _ error)
• type TestCasePattern

Functions

func GenerateLogs

func GenerateLogs(ctx context.Context, targets []string, opts GenerateOptions) error

GenerateLogs generates logs and sends them to targets

Types

type Comparer

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

A Comparer allows comparing query results for test cases between a reference API and a test API.

func New

func New(refAPI, testAPI LokiAPI) *Comparer

New returns a new Comparer.

func (*Comparer) Compare

func (c *Comparer) Compare(ctx context.Context, tc *TestCase) (*Result, error)

Compare runs a test case query against the reference API and the test API and compares the results.

type Config

type Config struct {
	ReferenceTargetConfig TargetConfig       `yaml:"reference_target_config"`
	TestTargetConfig      TargetConfig       `yaml:"test_target_config"`
	TestCases             []*TestCasePattern `yaml:"test_cases"`
	QueryParameters       QueryParameters    `yaml:"query_parameters"`
}

Config models the main configuration file.

func Load

func Load(content []byte) (*Config, error)

Load parses the YAML input into a Config.

func LoadFromFiles

func LoadFromFiles(filenames []string) (*Config, error)

LoadFromFiles parses the given YAML files into a Config.

type GenerateOptions

type GenerateOptions struct {
	Start, End time.Time
	Step       time.Duration
	Lines      int
	Streams    []string
	Client     ht.Client
}

GenerateOptions defines options for [LogGenerator.Generate].

type LogEntry

type LogEntry struct {
	Timestamp time.Time
	Level     plog.SeverityNumber

	// HTTP attributes.
	Protocol   string
	Method     string
	ClientIP   netip.Addr
	RemoteIP   netip.Addr
	RemotePort uint16
	Status     int
	Took       time.Duration
	Size       uint64

	SpanID  pcommon.SpanID
	TraceID pcommon.TraceID
}

func NewLogEntry

func NewLogEntry(r *rand.Rand, ts time.Time) LogEntry

NewLogEntry generates new LogEntry.

func (LogEntry) EncodeJSON

func (e LogEntry) EncodeJSON(enc *jx.Encoder)

EncodeJSON encodes entry to given encoder.

func (LogEntry) JSON

func (e LogEntry) JSON() string

JSON returns JSON-encoded line.

func (LogEntry) OTEL

func (e LogEntry) OTEL(r plog.LogRecord)

OTEL returns OpenTelemetry log record.

type LokiAPI

type LokiAPI interface {
	Query(ctx context.Context, params lokiapi.QueryParams) (*lokiapi.QueryResponse, error)
	QueryRange(ctx context.Context, params lokiapi.QueryRangeParams) (*lokiapi.QueryResponse, error)
}

LokiAPI represents LogQL API.

type QueryParameters

type QueryParameters struct {
	EndTime        string            `yaml:"end_time"`
	RangeInSeconds float64           `yaml:"range_in_seconds"`
	StepInSeconds  float64           `yaml:"step_in_seconds"`
	Direction      lokiapi.Direction `yaml:"direction"`
	Limit          *int              `yaml:"limit"`
}

type Result

type Result struct {
	TestCase          *TestCase       `json:"testCase"`
	Diff              string          `json:"diff"`
	Expected          json.RawMessage `json:"expected"`
	Got               json.RawMessage `json:"got"`
	UnexpectedFailure string          `json:"unexpectedFailure"`
	UnexpectedSuccess bool            `json:"unexpectedSuccess"`
	Unsupported       bool            `json:"unsupported"`
}

Result tracks a single test case's query comparison result.

func (*Result) Success

func (r *Result) Success() bool

Success returns true if the comparison result was successful.

type TargetConfig

type TargetConfig struct {
	// ReadyQuery is a log query to check instance readiness.
	ReadyQuery string `yaml:"ready_query"`
	QueryURL   string `yaml:"query_url"`
	PushURL    string `yaml:"push_url,omitempty"`
}

TargetConfig represents the configuration of a single Prometheus API endpoint.

type TestCase

type TestCase struct {
	Query          string            `json:"query"`
	SkipComparison bool              `json:"skipComparison"`
	ShouldFail     bool              `json:"shouldFail"`
	ShouldBeEmpty  bool              `json:"shouldBeEmpty"`
	Start          time.Time         `json:"start"`
	End            time.Time         `json:"end"`
	Step           time.Duration     `json:"step"`
	Limit          int               `json:"limit"`
	Direction      lokiapi.Direction `json:"direction"`
}

TestCase represents a fully expanded query to be tested.

func ExpandQuery

func ExpandQuery(cfg *Config, start, end time.Time, step time.Duration) (r []*TestCase, _ error)

ExpandQuery expands given test case.

type TestCasePattern

type TestCasePattern struct {
	Query          string `yaml:"query"`
	SkipComparison bool   `yaml:"skip_comparison,omitempty"`
	ShouldFail     bool   `yaml:"should_fail,omitempty"`
	ShouldBeEmpty  bool   `yaml:"should_be_empty,omitempty"`
}

TestCase represents a given query (pattern) to be tested.