Loki Querying

LogQL Overview

LogQL is Loki's query language, inspired by PromQL. It has two modes: log queries return log lines, and metric queries return numeric values derived from logs. LogQL queries start with stream selectors and optionally apply pipeline stages.

Stream Selectors

Stream selectors filter which log streams to query. They use the same label matcher syntax as Prometheus. Selectors are the first step in every LogQL query.

# All logs from the api app
{app="api"}

# Logs from production namespace
{namespace="production"}

# Logs matching a regex
{app=~"api|web|gateway"}

# Negative match
{namespace!="default"}

Log Pipeline

A log pipeline applies processing stages to log lines after stream selection. Stages parse, filter, and transform log content. Pipeline stages are separated by pipes.

{app="api"}
  | json
  | level="error"
  | line_format "{{.timestamp}} {{.message}}"

Parsers

Parsers extract labels from log lines. Loki supports JSON, logfmt, regex, and pattern parsers. Parsed labels can be used for filtering and aggregation.

# JSON parsing
{app="api"} | json | status >= 500

# logfmt parsing
{app="api"} | logfmt | level="error"

# Regex parsing
{app="api"} | regexp "(?P<method>\\w+) (?P<path>/\\S+) (?P<status>\\d+)"

# Pattern parsing
{app="api"} | pattern "<_> <method> <path> <status> <_>" | status >= 500

Label Formatting

label_format creates new labels or renames existing ones using template expressions. This is useful for standardizing label values or combining multiple labels into one.

{app="api"}
  | json
  | label_format status_code="{{.status}}"
  | label_format level="{{if eq .level "error"}}ERROR{{else}}{{.level}}{{end}}"

Line Formatting

line_format rewrites the log line content using template expressions. Use it to create concise, human-readable output from structured logs.

{app="api"}
  | json
  | line_format "{{.timestamp}} [{{.level}}] {{.method}} {{.path}} {{.status}} {{.duration_ms}}ms"

Unwrap for Metrics

The unwrap clause extracts a numeric value from logs for metric queries. It converts log lines into time series that can be aggregated with rate, sum, or histogram_quantile.

# Count of errors per second
count_over_time({app="api"} | json | level="error" [1m])

# Sum of duration values
sum_over_time({app="api"} | json | unwrap duration_ms [5m])

# Rate of errors
rate({app="api"} | json | level="error" [5m])