logqlsyntax

README

logql-syntax

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/	three regex / matcher helpers from pkg/util

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. Copy source files from pkg/logql/{syntax,log}/... into the matching directories here.
2. Rewrite github.com/grafana/loki/v3/pkg/... import paths to github.com/qualithm/logql-syntax/... (see the sed invocation in the project history).
3. Reconcile any new uses of pkg/util, pkg/logqlmodel, or pkg/util/constants — extend the trimmed packages here as needed.
4. 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+

Building & Testing

make build
make test
make lint

Resyncing from upstream Loki

make sync                       # defaults to LOKI_VERSION in the Makefile
LOKI_VERSION=v3.8.0 make sync   # pin a specific upstream release

Minimum Supported Go Version

Go 1.26+.

Licence

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.