LogQL is the query language of Grafana Loki, an open-source log store. Every LogQL query starts with a stream selector, which is a set of labels in braces such as . From there you can chain more steps: line filters (|=, !=, |~, !~), a parser (json, logfmt, pattern, regexp, unpack), filters on the fields the parser extracted, and reformatting. A query either returns log lines or turns them into metrics with functions like rate and count_over_time. Loki only indexes labels, not the text of each line. That makes it cheap to run, but your queries are only fast if you choose good labels. The syntax is based on PromQL, so Prometheus users will find it familiar quickly.

How does a LogQL query actually work?

Loki groups log lines into streams. A stream is every line that shares the same set of labels. Per the Loki overview, Loki “does not index the contents of the logs, but only indexes metadata about your logs as a set of labels for each log stream.” The stream selector picks which compressed chunks Loki reads. Everything after the selector runs as a brute-force scan over those chunks.

This is why the order of steps matters. Put a cheap string filter before the parser, so Loki only parses the lines that survive the filter:

 |= "error" != "timeout" | logfmt | duration > 30s

The log query reference lists all the operators. Regex filters use RE2 and are case-sensitive unless you add (?i). line_format and label_format rewrite lines and labels using Go template functions. drop and keep remove labels you don’t need.

How do you turn logs into metrics and alerts?

A metric query wraps a log query in a range aggregation. Two common examples are an error rate per service and a latency percentile taken from a field in the log line:

sum by (app) (rate( |= "error" ))  quantile_over_time(0.95,    | logfmt | unwrap duration_seconds(latency) | __error__=""  ) by (route)

Metric queries support rate, count_over_time, bytes_over_time and absent_over_time. With unwrap you also get sum_over_time, avg_over_time, quantile_over_time and similar functions. The __error__="" filter throws away lines the parser couldn’t read. Without it, one malformed line can break the whole query.

Loki’s ruler runs these queries on a schedule. According to the alerting docs, alerting rules work exactly like Prometheus rules “except they use LogQL for their expressions”. Recording rules can remote-write their results to Prometheus, Mimir or Thanos. That means existing Alertmanager routing and SLO dashboards keep working, with log-based series sitting next to your metrics.

How should you choose labels?

Labels decide whether Loki is fast and cheap or slow and expensive. Every unique combination of label values creates a new stream. Grafana’s label best practices say dynamic labels should be “ideally limited to tens of values”. Even very large tenants sending more than 10 TB a day should stay under about 100,000 active streams and under one million streams per 24 hours.

  • Good labels: cluster, namespace, app, environment. These are low-cardinality and match how you search.
  • Bad labels: trace ID, user ID, request ID, order number. These create thousands of tiny streams and tiny chunks.
  • Where high-cardinality values go: structured metadata. It is stored alongside each line, isn’t indexed, and you query it like a label: | trace_id="abc123". It requires the TSDB index and schema v13 or later.

The most common mistake we see is adding a label “just in case” and then watching ingestion slow down and storage costs rise. Our rule of thumb: if you’d normally search for the value with a string filter, it shouldn’t be a label.

What does this look like in a media production pipeline?

Our pipeline is typical for video work: uploads, transcodes, proxy generation and delivery jobs, each producing a lot of log output. FFmpeg alone writes progress lines every second and gives a short failure message at the end. The useful pattern is to label by job type and environment, keep job IDs in structured metadata, and alert on the failure signal instead of the noise:

sum(count_over_time( |= "Conversion failed" )) > 0

The trade-off is query speed. If you select a broad stream and search weeks of verbose encoder output, Loki has to scan everything you selected, so a lookup that takes seconds over a short window can take minutes over a long one. How long depends on data volume, how many queriers you run and how narrow your selector is. Short-lived job logs suit Loki well. Long-term audit search across all your text is the use case where a full-text indexing engine still wins.

Turn on retention from the start. By default, logs live forever until you enable the compactor’s retention_enabled and set retention_period. Retention per stream can’t be set below 24 hours.

What has changed in Loki and LogQL recently?

A lot of older LogQL advice is now out of date:

  • Promtail is gone. The Promtail page states it reached end of life on March 2, 2026. Collection now happens in Grafana Alloy, and Grafana provides a migration tool.
  • Native OpenTelemetry. Loki 3.0 (April 2024) added OTLP ingestion. Resource attributes such as service.name become labels (written service_name), and the remaining attributes become structured metadata.
  • Bloom-filter acceleration is still experimental. Query acceleration speeds up equality filters on structured metadata, but only when the filter comes before any parser stage.
  • No built-in machine learning or joins. LogQL has no anomaly-detection models, no SQL-style joins and no WASM transforms. The nearest feature is Grafana Logs Drilldown. It groups lines into patterns automatically and lets you browse logs without writing a query.
  • Licence. Loki is AGPL-3.0-only. Read the licence before you embed or modify Loki inside a product you distribute or offer as a service.

Where should you start?

Pick one noisy service. Give it three or four low-cardinality labels and move IDs into structured metadata. Then write three queries: a filtered log search, an error rate and one unwrap latency percentile. Once those return results quickly over a 24-hour window, turn the error rate into a ruler alert and set retention before you add more services.

Case Studies

Clients we worked with.