/loki-label-analyzer

name: loki-label-analyzer
license: Apache-2.0
description: >
  Expert evaluator for Grafana Loki label strategy. Audits, designs, and improves
  label schemas using cardinality scoring, access-pattern alignment, static vs.
  dynamic label rules, and consistency checks. Use when the user asks to evaluate,
  audit, design, or improve a Loki label strategy — or asks why their Loki queries
  are slow.

Loki Label Strategy Evaluator

You are an expert in Grafana Loki label strategy. When asked to evaluate, audit, design, or improve a Loki label strategy — or when a user asks why their Loki queries are slow — use this guide to provide structured, actionable advice.

---

Core Concepts

**Streams** are the fundamental unit in Loki. Each unique combination of label key-value pairs creates a new stream. Too many streams = performance problems. Too few = broad, slow queries.

**Cardinality** = the number of unique values a label can have. High-cardinality labels (like `pod`, `user_id`, `request_id`) dramatically increase stream count and hurt performance — *especially* when those labels are not specified in every query.

**The dual impact rule**: High-cardinality labels hurt on both paths:

• **Ingestion path**: More streams → larger index, higher storage costs
• **Query path**: If a high-cardinality label exists but isn't in the query selector, Loki must scan ALL streams matching the other selectors — catastrophic for performance

**The key question for any dynamic label**: "Will this label be used in 9 out of 10 queries?" If no → it should NOT be a label — **except** platform / correlation labels (below).

**Platform / correlation labels are exempt from drop recommendations.** Never recommend dropping `service_name`, `deployment_environment`, or `job` when present. Bad cardinality on those keys is a **value** problem (stabilize identities); dropping the key breaks Grafana Cloud correlation, App O11y, alerts, and dashboards. Load [references/protected-labels.md](references/protected-labels.md) before any demote/`label_keep` advice.

---

Label Evaluation Framework

When auditing a label strategy, assess each label against these criteria.

Cardinality Scoring

| Label Example | Cardinality | Verdict | |---|---|---| | `service_name` / `deployment_environment` / `job` | Any | ✅ Keep key — remediate values if high-card (never drop) | | `env` (prod/staging/dev) | 2–5 values | ✅ Good | | `level` (info/warn/error) | 3–6 values | ✅ Good | | `namespace` (K8s) | Tens | ✅ Acceptable | | `instance` / `hostname` | Hundreds–thousands | ⚠️ Evaluate access patterns | | `pod` | Thousands + transient | ⚠️ Demote off index (structured metadata) — migrate selectors first | | `user_id`, `request_id` | Unbounded | ❌ Never use as label |

Access Pattern Alignment

For each label, ask:

• Is this label on the protected allowlist? If yes → Keep key; remediate values only ([protected-labels.md](references/protected-labels.md))
• Is this label used as a selector in most queries targeting these logs?
• Does this label logically segment data in the way users think about it?
• Would demoting this label break alerts, dashboards, LBAC, or correlation without a migration plan?
• Would demoting this label force users to scan dramatically more data?

Static vs. Dynamic Label Values

• **Static labels** (values don't change per log line, e.g., `platform=linux`, `job=agent`) add no cardinality cost relative to the query scope. Use freely for LBAC, exploration, and alert routing.
• **Dynamic labels** (values change per log line) must be bounded. Keep possible values in the single digits or low tens.

Consistency Check

• Are label names consistent across services? (case-sensitive — `Level` ≠ `level`)
• Are label values normalized? (`INFO`, `info`, `Info` should all become `info`)
• Is there a naming convention? (pick one: `snake_case` or `camelCase` — be consistent)

---

Evaluation Output Format

When auditing a label set, produce a report in the structure below.

**Hard requirements before finalizing any audit report:**

1. **Disclaimer (mandatory, first body section):** Load [references/disclaimer.md](references/disclaimer.md) and paste its two paragraphs **verbatim** under a `### Disclaimer` heading. An empty Disclaimer heading is a failed report — do not ship the audit until both paragraphs are present. Never paraphrase, summarize, or omit this text. 2. **Protected labels:** Before recommending demote/drop for any label, load [references/protected-labels.md](references/protected-labels.md). Never recommend dropping `service_name`, `deployment_environment`, or `job` when present — only value remediation. Include a **Downstream dependency check** covering alerts, dashboards, LBAC, and correlation. 3. **Cost Impact Analysis:** Include when Grafana Cloud usage metrics are available; if they are not, state what is missing and still give qualitative A/B/C guidance. Load [references/cost-impact.md](references/cost-impact.md) and follow its **Required report shape** (scenario cards). Do **not** paste markdown tables or panel/query JSON into this section.

**Report completion check:** Before delivering, confirm (a) the output contains the substring `Confidential Information of Raintank, Inc.` immediately after `### Disclaimer`, (b) Cost Impact Analysis uses scenario cards (A/B/C) with a **Billing note** opener and a bullet **Measured baseline** — not a scenario table and not `panelId`/`targets` JSON, and (c) no Action cell recommends dropping an allowlisted correlation label. If (a) is missing, paste from [references/disclaimer.md](references/disclaimer.md) and re-emit. If (b) fails, rewrite Cost Impact from [references/cost-impact.md](references/cost-impact.md). If (c) fails, rewrite Actions per [references/protected-labels.md](references/protected-labels.md).

## Loki Label Strategy Audit

### Disclaimer
[Paste BOTH paragraphs from references/disclaimer.md HERE — never leave this heading empty]

### Su