Skip to main content

Workflow: Guided LogQL Query Builder

Transforming user intent into syntactically valid, high-performance LogQL queries while avoiding common cardinality and parser mistakes.

Step 1: Establish Stream Selectors​

  1. Scope the query using low-cardinality indexed labels: {namespace="production", app="auth-service"}.
  2. Never place high-cardinality identifiers (user IDs, IP addresses, trace IDs) inside {} stream selectors. Use line filters (|=) or parsed label filters (| json | user_id == "...") instead.

Step 2: Select the Optimal Parser Stage​

Choose the parser matching your application's log format:

  • JSON Logs: | json (unpacks JSON keys into queryable labels).
  • Logfmt / Key-Value: | logfmt (unpacks k=v pairs).
  • Unstructured / Custom: | pattern "<_> [<level>] <msg> <duration_ms>" (uses Loki pattern ingester).
  • Regex Extraction: | regexp "(?P<ip>\\d+\\.\\d+\\.\\d+\\.\\d+)".

Step 3: Add Line & Label Filters​

Filter on parsed fields to narrow results down to relevant records:

{app="auth-service"} 
  | json 
  | status == "FAILED" 
  | attempts > 3

Step 4: Add Metric Aggregations (Optional)​

Calculate time-series rates or counts over rolling windows:

sum by (client_ip) (
  count_over_time({app="auth-service"} | json | status == "FAILED" [10m])
)

Use execute_logql_query(query=..., step="1m") to graph the trend over time.