Jon Chery
496303471d
---ci--- project: atelier phase: 7 milestone: v0.1 status: complete phase_role: final milestone_complete: true requirements: covered: [ATELIER-01, ATELIER-02, ATELIER-03, ATELIER-04, ATELIER-05, ATELIER-06, ATELIER-07, ATELIER-08, ATELIER-09, ATELIER-10, ATELIER-11, ATELIER-12, ATELIER-13, ATELIER-14, ATELIER-15, ATELIER-16, ATELIER-17, ATELIER-18, ATELIER-19, ATELIER-20, ATELIER-21, ATELIER-22, ATELIER-23, ATELIER-24, ATELIER-25, ATELIER-26, ATELIER-27, ATELIER-28, ATELIER-29, ATELIER-30, ATELIER-31, ATELIER-32, ATELIER-33, ATELIER-34, ATELIER-35] partial: [] ship: milestone: v0.1 type: NFR tag: v0.0.7 merge: milestone/v0.1-atelier -> main release: https://git.cloudinit.dev/cloudinit-bot/atelier/releases/tag/v0.0.7 ---/ci--- Milestone v0.1 — Initial Framework (NFR, complete). 8 core principles (C1-C8), 11 domains, 110 domain principles, 27 derived docs, 4 good + 3 bad examples, 4 language docs, full matrix, 3 review docs. All 35 requirements covered. 7 patches (v0.0.0 pre-execution through v0.0.7 final). v0.0.7 IS the v0.1.0 milestone release.
50 lines
1.9 KiB
Markdown
50 lines
1.9 KiB
Markdown
# Metrics — Derived Rules
|
|
|
|
> Derives from `domains/observability/first-principles.md` P1 (Structured by Default), P4 (Cardinality Discipline), P8 (SLI/SLO Awareness).
|
|
|
|
## The Four Golden Signals
|
|
|
|
| Signal | What |
|
|
|--------|------|
|
|
| Latency | Time to serve a request (p50, p95, p99) |
|
|
| Traffic | Request rate (req/s) |
|
|
| Errors | Error rate (errors/s, or % of traffic) |
|
|
| Saturation | How full is the system (CPU, memory, queue depth) |
|
|
|
|
- All four are needed. Missing one is a blind spot.
|
|
- Latency is percentiles, not average. Average hides the long tail.
|
|
|
|
## Cardinality (P4)
|
|
|
|
- Labels have bounded cardinality. `user_id` as a label = unbounded cardinality = unbounded bill.
|
|
- High-cardinality dimensions belong in traces, not metrics.
|
|
- A metric with `user_id` as a label is a 1M-series metric. That is a budget bomb.
|
|
|
|
## Counter vs Gauge vs Histogram
|
|
|
|
| Type | What | Example |
|
|
|------|------|---------|
|
|
| Counter | Monotonically increasing | `http_requests_total` |
|
|
| Gauge | A value at a point in time | `active_connections` |
|
|
| Histogram | Distribution of values | `http_request_duration_seconds` |
|
|
|
|
- A counter never decreases. Use `rate()` over time to get the rate.
|
|
- A gauge can go up and down. Use it for saturation.
|
|
- A histogram gives percentiles. Use it for latency.
|
|
|
|
## SLI/SLO (P8)
|
|
|
|
- SLI (Service Level Indicator): a metric of good/total (e.g., 99.9% of requests < 500ms).
|
|
- SLO (Service Level Objective): the target for the SLI (e.g., 99.9% over 30 days).
|
|
- Error budget: 1 - SLO. If SLO is 99.9%, error budget is 0.1%. Spend it on feature risk, not bugs.
|
|
- When the error budget is exhausted, freeze features. Fix reliability.
|
|
|
|
## What Violates Metrics Discipline
|
|
|
|
| Violation | Principle |
|
|
|-----------|-----------|
|
|
| `user_id` as a label | P4 Cardinality |
|
|
| Average latency only | P8 (hides the tail) |
|
|
| No error rate metric | P8 (no SLI) |
|
|
| 1000 metrics, no SLO | P8 (no objective) |
|
|
| A counter that decreases | (type error) | |