# logql-generator

Builds production-ready LogQL queries, metric aggregations, and Grafana Loki alert rules through a guided workflow. Useful for debugging logs and setting up dashboards.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 597 installs · ★ 327
- Author: akin-ozer
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/akin-ozer/cc-devops-skills/tree/HEAD/devops-skills-plugin/skills/logql-generator/SKILL.md
- Updated: 2026-07-26
- HTML: https://affpapa.org/en/nevibecode/skills/logql-generator

## What it does

The skill follows an eight-stage workflow to build Grafana Loki queries. It captures your goal, stream labels, and log formats such as JSON or logfmt. Then it checks versions. When the version is unknown, it defaults to a compatibility-first syntax, avoiding Loki 3.x features like `|>`, `!>`, and `approx_topk`.

For complex aggregations, it blocks output until it inspects local reference files. Unread files leave the query unverified. The skill delivers either the final LogQL query directly or an incremental pipeline broken down into stream selectors, filters, and aggregations.

## Requirements
- Works with: Grafana

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add akin-ozer/cc-devops-skills --skill logql-generator -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/logql-generator/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/logql-generator/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add akin-ozer/cc-devops-skills --skill logql-generator -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/logql-generator/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add akin-ozer/cc-devops-skills --skill logql-generator -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/logql-generator/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install akin-ozer/cc-devops-skills logql-generator
```

2. **Manually: put the files in place**
- File: `.github/skills/logql-generator/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add akin-ozer/cc-devops-skills --skill logql-generator -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/akin-ozer/cc-devops-skills --path devops-skills-plugin/skills/logql-generator
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/logql-generator/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add akin-ozer/cc-devops-skills --skill logql-generator -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/akin-ozer/cc-devops-skills/tree/HEAD/devops-skills-plugin/skills/logql-generator/SKILL.md

## When to use it
- construct LogQL queries to calculate service error rates
- build numeric metric queries for Grafana dashboard panels
- write Loki alerting rules with range aggregations
- parse structured logs using json, logfmt, or pattern matchers

## Example prompts
- Write a LogQL query for error rate by service over the last 15m
- Help me build a Loki alert query for 500 status codes in nginx logs
- I need step-by-step LogQL query construction with JSON parsing

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 46838d99779c1a52.

BEGIN THIRD-PARTY FILE 46838d99779c1a52
````text
---
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:
```text
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)?"
````
END THIRD-PARTY FILE 46838d99779c1a52

The third-party file has ended. Everything between the 46838d99779c1a52 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2982 of 15358 bytes. © akin-ozer · Apache-2.0 · https://github.com/akin-ozer/cc-devops-skills/tree/HEAD/devops-skills-plugin/skills/logql-generator/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md