/logql-generator

name: logql-generator
description: Generate LogQL queries, log stream selectors, metric queries, and alerting rules for Grafana Loki.

LogQL Query Generator

Overview

Interactive workflow for generating production-ready LogQL queries. LogQL is Grafana Loki's query language with indexed label selection, line filtering, parsing, and metric aggregation.

Trigger Hints

• "Write a LogQL query for error rate by service."
• "Help me build a Loki alert query."
• "Convert this troubleshooting requirement into LogQL."
• "I need step-by-step LogQL query construction."

Use this skill for query generation, dashboard queries, alerting expressions, and troubleshooting with Loki logs.

Execution Flow (Deterministic)

Always run stages in order. Do not skip required stages.

Stage 1 (Required): Capture Intent

Use `AskUserQuestion` to collect goal and use case.

Template:

• "What is your primary goal: debugging, alerting, dashboard metric, or investigation?"
• "Do you need a log query (raw lines) or a metric query (numeric output)?"
• "What time window should this cover (example: last 15m, 1h, 24h)?"

Fallback if `AskUserQuestion` is unavailable:

• Ask the same questions in plain text and continue.

Stage 2 (Required): Capture Log Source Details

Collect: 1. Labels for stream selectors (`job`, `namespace`, `app`, `service_name`, `cluster`) 2. Log format (JSON, logfmt, plain text, mixed) 3. Known fields to filter/aggregate (`status`, `level`, `duration`, `path`, `trace_id`)

Ambiguity and partial-answer handling: 1. If a required field is missing, ask one focused follow-up question. 2. If still missing, proceed with explicit assumptions. 3. Prefix assumptions with `Assumptions:` in the output so the user can correct them quickly.

Stage 3 (Required): Discover Loki and Grafana Versions

Collect or infer:

• Loki version (example: `2.9.x`, `3.0+`, unknown)
• Grafana version (example: `10.x`, `11.x`, unknown)
• Deployment context (self-hosted Loki, Grafana Cloud, unknown)

Version compatibility policy: 1. If versions are known, use the newest compatible syntax only. 2. If versions are unknown, use compatibility-first syntax and avoid 3.x-only features by default. 3. For unknown versions, provide an optional "3.x optimized variant" separately.

Avoid by default when version is unknown:

• Pattern match operators `|>` and `!>`
• `approx_topk`
• Structured metadata specific behavior (`detected_level`, accelerated metadata filtering assumptions)

Stage 4 (Required): Plan Confirmation and Output Mode

Present a plain-English plan, then ask the user to choose output mode.

Plan template:

LogQL Query Plan
Goal: <goal>
Query type: <log or metric>
Streams: <selector>
Filters/parsing: <filters + parser>
Aggregation window: <function and [range]>
Compatibility mode: <version-aware or compatibility-first>

Mode selection template:

• "Do you want `final query only` (default) or `incremental build` (step-by-step)?"

If user does not choose, default to `final query only`.

Stage 5 (Conditional, Blocking): Reference Checkpoint for Complex Queries

Complex query triggers:

• Nested aggregations (`topk(sum by(...))`, multiple `sum by`, percentiles)
• Performance-sensitive queries (high volume streams, long ranges)
• Alerting expressions
• Template functions (`line_format`, `label_format`)
• Regex-heavy extraction, IP matching, pattern parsing
• Loki 3.x feature usage

Blocking checkpoint rule: 1. Read relevant files before generation using explicit file-open/read actions. 2. Minimum file set:

• `examples/common_queries.logql` for syntax and query patterns
• `references/best_practices.md` for performance and alerting guidance

3. Do not generate the final query until this checkpoint is complete.

Fallback when file-read tools are unavailable: 1. State that reference files could not be read in this environment. 2. Generate a conservative query (compatibility-first, simpler operators). 3. Mark result as `Unverified against local references`.

Stage 6 (Conditional): External Docs Lookup Policy (Context7 Before WebSearch)

Use external lookup only for version-specific behavior, unclear syntax, or advanced features not covered in local references.

Decision order: 1. Context7 first:

• `mcp__context7__resolve-library-id` with `libraryName="grafana loki"`
• `mcp__context7__query-docs` for the exact topic

2. WebSearch second (fallback only) when:

• Context7 is unavailable
• Context7 does not provide required version-specific detail
• You need latest release/deprecation confirmation

WebSearch fallback constraints:

• Prefer official Grafana/Loki docs and release notes.
• Note which statement came from fallback search.

Stage 7 (Required): Generate Query

Stage 7A (Default): Final Query Only

Return one production-ready query plus short explanation.

Stage 7B (Optional): Incremental Build Mode

Use this when requested or when debugging complex pipelines.

Step-by-step template: 1. Stream selector 2. Line filter 3. Parser 4. Parsed-field filter 5. Aggregation/window

Stage 8 (Required): Deliver Usage and Checks

Always include: 1. Final query or incremental sequence 2. How to run it (Grafana Explore/panel or `logcli`) 3. Tunables (labels, thresholds, range) 4. Any assumptions and compatibility notes

AskUserQuestion Templates

Intake Template

• "What system/service should this query target?"
• "Which labels are reliable for stream selection?"
• "What defines a match (error text, status code, latency threshold, user path)?"
• "Should output be raw logs or a metric for alert/dashboard?"

Version Template

• "What Loki version are you running?"
• "What Grafana version are you using?"
• "If unknown, should I generate a compatibility-first query and add an optional 3.x variant?"

Ambiguity Follow-up Template

• "I am missing `<field>`. Should I assume `<default>` so I can continue?"

Core Patterns

Stream Selection and Filtering

``