prometheus-go-code-review — Claude Code skill: install
The prometheus-go-code-review skill reviews Prometheus instrumentation in Go, covering metric types, labels, naming, and registration. Use it when checking prometheus/client_golang code.
Apache-2.0 126 installs ★ 89 updated 2026-09-15
npx skills add existential-birds/beagle --skill prometheus-go-code-review -a claude-codeWhat prometheus-go-code-review does
The skill checks whether Counter, Gauge, and Histogram match the measurement, then reviews label cardinality, metric naming, histogram buckets, registration, and /metrics exposure. It focuses on Go code using prometheus/client_golang, promauto, promhttp, or MustRegister.
Its review follows ordered gates. It first records the Prometheus-related files, then traces label values and confirms that metric constructors run once rather than inside request handlers. Findings should name a file and, where possible, a line or symbol. A raw user_id, full URL path, or timestamp as a label can create millions of series; registering the same metric per request can panic on a duplicate.
What it helps with
- verify Counter, Gauge, and Histogram choices
- spot labels with unbounded cardinality
- catch per-request metric registration
- find metric names missing unit suffixes
- check whether
/metricsis exposed
Example prompts for the agent
- Review this Go change for Prometheus instrumentation issues and cite the affected files and symbols.
- Check whether any label in this diff uses
user_id, timestamps, or the full URL path as a value. - Verify that metrics are registered once and that the
/metricsendpoint is wired correctly.
How to install prometheus-go-code-review
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill prometheus-go-code-review -a claude-code2Manually: put the files in place
~/.claude/skills/prometheus-go-code-review/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/prometheus-go-code-review/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill prometheus-go-code-review -a codex2Manually: put the files in place
.agents/skills/prometheus-go-code-review/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill prometheus-go-code-review -a cursor2Manually: put the files in place
.cursor/skills/prometheus-go-code-review/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install existential-birds/beagle plugins/beagle-go/skills/prometheus-go-code-review2Manually: put the files in place
.github/skills/prometheus-go-code-review/SKILL.md1Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill prometheus-go-code-review -a gemini-cli2Platform CLI
gemini skills install https://github.com/existential-birds/beagle --path plugins/beagle-go/skills/prometheus-go-code-reviewManually: put the files in place
.devin/skills/prometheus-go-code-review/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add existential-birds/beagle --skill prometheus-go-code-review -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about prometheus-go-code-review
How do I install prometheus-go-code-review in Claude Code?
Run npx skills add existential-birds/beagle --skill prometheus-go-code-review -a claude-code, then check ~/.claude/skills/prometheus-go-code-review/SKILL.md.
What does prometheus-go-code-review do?
It reviews Prometheus instrumentation in Go, including metric type selection, label cardinality, unit suffixes, registration lifecycle, and /metrics exposure.
What can break a Prometheus review?
Unbounded label values such as user_id, a full path, or a timestamp can create too many series. Registering a metric inside a request handler can panic when the same metric is registered again.
Source text
SKILL.md · Apache-2.0
---
name: prometheus-go-code-review
description: Reviews Prometheus instrumentation in Go code for proper metric types, labels, and patterns. Use when reviewing code with prometheus/client_golang metrics.
---
# Prometheus Go Code Review
## Review Checklist
- [ ] Metric types match measurement semantics (Counter/Gauge/Histogram)
- [ ] Labels have low cardinality (no user IDs, timestamps, paths)
- [ ] Metric names follow conventions (snake_case, unit suffix)
- [ ] Histograms use appropriate bucket boundaries
- [ ] Metrics registered once, not per-request
- [ ] Collectors don't panic on race conditions
- [ ] /metrics endpoint exposed and accessible
## Hard gates (sequenced)
Complete in order before recording a **finding**. Skip gates that clearly do not apply to the diff.
1. **Evidence scope** — Enumerate the files you are reviewing that touch Prometheus (`prometheus/client_golang`, `promauto`, `promhttp`, or `MustRegister`). **Pass:** you have a concrete path list (from the diff or an explicit file set); no repo-wide claim without at least one path.
2. **Label cardinality** — For each `*Vec` or labeled metric in scope, list label names and where values come from (constants, bounded codes, vs request-derived strings). **Pass:** no label uses unbounded values (e.g. raw `user_id`, full URL path, timestamps) unless the code uses a bounded mapping and you cite it.
3. **Registration lifecycle** — For metric definitions in scope, confirm constructors run once (package-level `var`, `init`, or `sync.Once`), not inside per-request handlers. **Pass:** no pattern that allocates/registers a new `Counter`/`Histogram`/`*Vec` on every request for the same logical metric.
4. **Finding shape** — Each finding names a file (and line or symbol where possible), states which gate (2 or 3) would fail if the issue is real, and ties to observed code. **Pass:** no standalone style nit when gates 2–3 are satisfied for that code.
## Metric Type Selection
| Measurement | Type | Example |
|-------------|------|---------|
| Requests processed | Counter | `requests_total` |
| Items in queue | Gauge | `queue_length` |
| Request duration | Histogram | `request_duration_seconds` |
| Concurrent connections | Gauge | `active_connections` |
| Errors since start | Counter | `errors_total` |
| Memory usage | Gauge | `memory_bytes` |
## Critical Anti-Patterns
### 1. High Cardinality Labels
```go
// BAD - unique per user/request
counter := promauto.NewCounterVec(
prometheus.CounterOpts{Name: "requests_total"},
[]string{"user_id", "path"}, // millions of series!
)
counter.WithLabelValues(userID, request.URL.Path).Inc()
// GOOD - bounded label values
counter := promauto.NewCounterVec(
prometheus.CounterOpts{Name: "requests_total"},
[]string{"method", "status_code"}, // <100 series
)
counter.WithLabelValues(r.Method, statusCode).Inc()
```
### 2. Wrong Metric Type
```go
// BAD - using gauge for monotonic value
requestCount := promauto.NewGauge(prometheus.GaugeOpts{
Name: "http_requests",
})
requestCount.Inc() // should be Counter!
// GOOD
requestCount := promauto.NewCounter(prometheus.CounterOpts{
Name: "http_requests_total",
})
requestCount.Inc()
```
### 3. Registering Per-Request
```go
// BAD - new metric per request
func handler(w http.ResponseWriter, r *http.Request) {
counter := prometheus.NewCounter(...) // creates new each time!
prometheus.MustRegister(counter) // panics on duplicate!
}
// GOOD - register once
var requestCounter = promauto.NewCounter(prometheus.CounterOpts{
Name: "http_requests_total",
})
func handler(w http.ResponseWriter, r *http.Request) {
requestCounter.Inc()
}
```
### 4. Missing Unit Suffix
```go
// BAD
duration := promauto.NewHistogram(prometheus.HistogramOpts{
Name: "request_duration", // no unit!
})
// GOOD
duration := promauto.NewHistogram(prometheus.HistogramOpts{
Name: "request_duration_seconds", // unit in name
})
```
## Good Patterns
### Metric Definition
```go
var (
httpRequests = promauto.NewCounterVec(
prometheus.CounterOpts{
Namespace: "myapp",
Subsystem: "http",
Name: "requests_total",
Help: "Total HTTP requests processed",
},
[]string{"method", "status"},
)
httpDuration = promauto.NewHistogramVec(
prometheus.HistogramOpts{
Namespace: "myapp",
Subsystem: "http",
Name: "request_duration_seconds",
Help: "HTTP request latencies",
Buckets: []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10},
},
[]string{"method"},
)
)
```
### Middleware Pattern
```go
func metricsMiddleware(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
timer := prometheus.NewTimer(httpDuration.WithLabelValues(r.Method))
defer timer.ObserveDuration()
wrapped := &responseWriter{ResponseWriter: w, status: 200}
next.ServeHTTP(wrapped, r)
httpRequests.WithLabelValues(r.Method, strconv.Itoa(wrapped.status)).Inc()
})
}
```
### Exposing Metrics
```go
import "github.com/prometheus/client_golang/prometheus/promhttp"
func main() {
http.Handle("/metrics", promhttp.Handler())
http.ListenAndServe(":9090", nil)
}
```
## Review Questions
1. Are metric types correct (Counter vs Gauge vs Histogram)?
2. Are label values bounded (no UUIDs, timestamps, paths)?
3. Do metric names include units (_seconds, _bytes)?
4. Are metrics registered once (not per-request)?
5. Is /metrics endpoint properly exposed?
© existential-birds · Apache-2.0 · existential-birds/beagle