logqlsyntax

package module
v0.1.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 10, 2026 License: AGPL-3.0 Imports: 0 Imported by: 0

README

LogQL Syntax

CI codecov Go Reference

Standalone Go parser and AST for Grafana Loki's LogQL. Lifts the upstream syntax, log, and logqlmodel packages out of grafana/loki with their runtime dependencies (dskit, etcd, jaeger, the queryrange/push machinery) stripped away.

Installation

go get github.com/qualithm/logql-syntax

Usage

import "github.com/qualithm/logql-syntax/syntax"

expr, err := syntax.ParseExpr(`sum by (job) (rate({app="api"} |= "error" [5m]))`)
if err != nil {
    return err
}
expr.Walk(func(e syntax.Expr) bool {
    // inspect the AST
    return true
})

What's included

Path Source
syntax/ github.com/grafana/loki/v3/pkg/logql/syntax
log/ github.com/grafana/loki/v3/pkg/logql/log
log/jsonexpr/ github.com/grafana/loki/v3/pkg/logql/log/jsonexpr
log/logfmt/ github.com/grafana/loki/v3/pkg/logql/log/logfmt
log/pattern/ github.com/grafana/loki/v3/pkg/logql/log/pattern
logqlmodel/ trimmed extract of pkg/logqlmodel (errors + label constants only)
internal/util/ regex, matcher and encoding helpers from pkg/util
internal/constants/ variants.go from pkg/util/constants

The runtime Result and Streams types from logqlmodel are intentionally omitted because they pull in loki/pkg/push and queryrange machinery.

Upstream sync

Tracked against Loki v3.7.2.

To resync against a newer Loki release:

  1. Download the release and run the sync script, which copies the upstream packages and rewrites their import paths. make sync uses the version pinned in scripts/sync-upstream.sh.

    go mod download github.com/grafana/loki/v3@<loki-version>
    ./scripts/sync-upstream.sh <loki-version>
    
  2. Reconcile any new uses of pkg/logqlmodel — extend the trimmed logqlmodel/ package here as needed.

  3. go test ./... — the only known persistent failures are the two timestamp subtests in log/ that hardcode local-timezone dates upstream.

Development

Prerequisites
  • Go 1.26+
Setup
make install-tools

This installs golangci-lint, goimports, govulncheck and gosec into $GOPATH/bin (~/go/bin by default). Put that directory on your PATH:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
Building & Testing
make build
make test
make lint
Security Tooling
make audit   # govulncheck
make gosec   # standalone gosec scan

.github/workflows/audit.yaml runs govulncheck and gosec daily.

Minimum Supported Go Version

Go 1.26+.

License

Apache-2.0. See LICENSE and NOTICE for upstream attribution.

Documentation

Overview

Package logqlsyntax is the root of a partial fork of Grafana Loki's LogQL parser packages, stripped of Loki's runtime dependencies (dskit, etcd, jaeger, queryrange, push, etc.).

Use sub-packages to parse and walk LogQL expressions:

import "github.com/qualithm/logql-syntax/syntax"

expr, err := syntax.ParseExpr(`sum by (job) (rate({app="api"} |= "error" [5m]))`)
if err != nil {
    return err
}
expr.Walk(func(e syntax.Expr) bool { return true })

See the README for the relationship to upstream Loki and the sync workflow.

Directories

Path Synopsis
internal
log
logfmt
Adapted from https://github.com/go-logfmt/logfmt/ but []byte as parameter instead Original license is MIT.
Adapted from https://github.com/go-logfmt/logfmt/ but []byte as parameter instead Original license is MIT.
Package logqlmodel contains the error types and label-name constants used by the LogQL syntax and evaluation packages.
Package logqlmodel contains the error types and label-name constants used by the LogQL syntax and evaluation packages.
This file is taken from the golang text/scanner package so `bufLen` can be set to `maxInputSize`.
This file is taken from the golang text/scanner package so `bufLen` can be set to `maxInputSize`.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL