/creating-grafana-dashboards

name: ring:creating-grafana-dashboards
description: "Authoring Grafana dashboards for Go services instrumented with lib-observability telemetry (tracing, metrics, log), plus a reference mode for RED/USE panel patterns and Grafonnet templates. Sweep mode inventories telemetry, runs PM deliberation on themes/SLIs/alerts, authors Grafonnet libsonnet compiled to JSON, and installs a CI drift gate. Use when scaffolding dashboards. Skip when the service is non-Go or emits no telemetry."

Creating Grafana Dashboards (lib-observability, PM-team)

When to use

Sweep mode:

• "Create / scaffold Grafana dashboards for this service"
• "Inventory telemetry / build telemetry dictionary"
• "Audit observability before designing dashboards"
• "Produce dashboards as code for {service}"
• "PM wants visibility into {domain} — what dashboards do we need?"

Reference mode:

• "What's the right panel for HTTP request latency?"
• "RED vs USE methodology for this metric type?"
• "How do I compose Grafonnet panels?"
• "Which Grafonnet template fits a counter / histogram / gauge?"

Skip when

• Service is not a Go project (lib-observability is Go-only at this skill's scope)
• Service emits no telemetry (pre-instrumentation; instrument the service before dashboard authoring, then use ring:implementing-tasks to verify observability checks pass)
• Task is purely Grafana folder organization or dashboard import (no authoring)
• Service is consumer-only sidecar with no metrics surface

Sequence

**Runs before:** ring:running-dev-cycle, ring:running-dev-cycle-frontend

Related

**Complementary:** ring:implementing-tasks, ring:codebase-explorer, ring:mapping-streaming-events, ring:using-lib-observability, ring:using-tracing **Similar:** ring:using-runtime, ring:using-assert

Prerequisites

• Go service with lib-observability initialized in bootstrap (`tracing.NewTelemetry`, `metrics.NewFactory`, `zap.NewLogger`)
• At least one metric, span, or structured log emission point present
• docs/ directory writable
• Grafonnet toolchain available in CI (jsonnet + grafonnet-lib) — installer instructions in ci-drift-check.md

Orchestrates a 3-phase, 8-gate workflow to produce Grafana dashboards grounded in real telemetry. You orchestrate. Agents explore. PM iterates. You NEVER read, write, or edit source code directly during the sweep.

**Announce at start:** "Using ring:creating-grafana-dashboards through 8 gates (0–7)."

Mode Selection

| Request Shape | Mode | |---|---| | "Create / scaffold dashboards" / "build telemetry dictionary" | **Sweep** (run gates 0–7) | | "Which panel for X?" / "RED vs USE?" / "Grafonnet template for Y?" | **Reference** (load `sub-files/reference.md`) |

---

SWEEP MODE

Telemetry Architecture (lib-observability)

Lerian Go services emit telemetry through `github.com/LerianStudio/lib-observability`:

• **Tracing** via `lib-observability/tracing` — `tracer.Start(ctx, name, opts...)` returning `context.Context, trace.Span`
• **Metrics** via `lib-observability/metrics` — fluent factory producing `meter.Int64Counter`, `meter.Float64Histogram`, `meter.Int64UpDownCounter`, `meter.Int64ObservableGauge`
• **Logs** via `lib-observability/log` (interface) and `lib-observability/zap` (implementation) — structured fields, automatically correlated with active span via `trace_id`/`span_id`
• **OTel attribute / metric / event names** via `lib-observability/constants` — canonical string constants; dashboards reference these for label and metric names
• **Cross-cutting** — `tenant_id` propagation through context, error attribution via `span.RecordError` + `span.SetStatus`

> **Deprecated shims:** `lib-commons/v5/commons/{opentelemetry,zap,log,metrics}` still compile but route through lib-observability. New emission sites MUST import lib-observability directly. The sweep detects both canonical and shim imports.

**WebFetch canonical docs (lib-observability — develop branch; main has only LICENSE + README):**

• Tracing: `https://raw.githubusercontent.com/LerianStudio/lib-observability/develop/tracing/doc.go`
• Metrics: `https://raw.githubusercontent.com/LerianStudio/lib-observability/develop/metrics/doc.go`
• Log: `https://raw.githubusercontent.com/LerianStudio/lib-observability/develop/log/doc.go`
• Constants: `https://raw.githubusercontent.com/LerianStudio/lib-observability/develop/constants/doc.go`

**WebFetch changelog:** `https://raw.githubusercontent.com/LerianStudio/lib-observability/develop/CHANGELOG.md`

Authoring Format: Grafonnet (Mandatory)

Dashboards are authored as **Grafonnet** (Jsonnet templating language) — compiled to JSON in CI. Raw JSON dashboards are FORBIDDEN.

Reasons:

• Diffable in PR review (libsonnet is code-shaped, JSON is not)
• Composable via `import` and inheritance
• Templated panel patterns reusable across themes
• Single source of truth — JSON is a build artifact, not a checked-in source

Toolchain setup: `sub-files/ci-drift-check.md`. Panel templates: `sub-files/grafonnet-templates/`.

Theme Taxonomy

**Free-form per service.** PM defines the theme directories under `docs/dashboards/{theme}/` during Gate 5. No enforced taxonomy — Lerian services are observability islands and theme naming reflects each service's domain.

Common-but-not-mandatory examples: `transactions/`, `auth/`, `ledger/`, `infrastructure/`, `business-kpis/`, `sla/`. The skill SUGGESTS themes from dictionary contents in Gate 4; PM ACCEPTS, RENAMES, MERGES, or SPLITS in Gate 5.

Drift Gate Posture

CI drift detection is **BLOCKING from day 1**. Any divergence between regenerated dictionary and committed `telemetry-dictionary.md` fails the PR. This is a deliberate cold-start choice — the skill is greenfield, no installed base to retrofit, every new metric emits under the strict regime.

Drift gate spec: `sub-files/ci-drift-check.md`.

Gate Overview

| Gate | Name | Agent | Cadence | |------|------|-------|---------| | 0 | Stack Detection | Orchestrator (grep + read) | Once per ru