LogQL Query Language Fundamentals
What you'll learn: You'll master how to write LogQL queries to select, filter, and parse log streams in Grafana Loki.
What is LogQL?
LogQL is Loki's query language—think of it as Loki's version of SQL for logs. Unlike traditional log systems that index full log content, Loki only indexes labels (metadata like app, environment, pod). LogQL lets you efficiently select log streams using these labels, then filter and parse the actual log lines.
Stream Selection with Label Matchers
LogQL queries start with log stream selectors using curly braces and label matchers:
{app="nginx", environment="production"}
This selects all logs with both labels. You can use operators like = (equals), != (not equals), =~ (regex match), and !~ (regex not match):
{namespace=~"prod-.*", level!="debug"}
Think of stream selection as choosing which filing cabinets to open—you're narrowing down by metadata before reading content.
Line Filter Expressions
After selecting streams, use line filters with pipe operators (|=, !=, |~, !~) to filter log lines by content:
{app="api"} |= "error" != "timeout"
This finds lines containing "error" but not "timeout". Regex filtering works too:
{app="api"} |~ "status=[45]\\d{2}"
Basic Log Parsing
LogQL includes parser expressions to extract fields from unstructured logs. The | json parser automatically extracts JSON fields, while | logfmt handles key-value pairs:
{app="api"} | json | status_code >= 500
This parses JSON logs and filters for specific field values—turning unstructured text into queryable data.
Key Takeaway: LogQL queries start with label-based stream selection (efficient thanks to Loki's index), then apply line filters and parsers to extract and filter actual log content—a three-step process of select, filter, and parse.