{
    "slug": "prometheus_concepts",
    "term": "Prometheus Concepts",
    "category": "observability",
    "difficulty": "intermediate",
    "short": "Prometheus is a pull-based metrics system — services expose /metrics in text format, Prometheus scrapes them, stores as time series, and evaluates alerting rules via PromQL.",
    "long": "Metric types: Counter (monotonically increasing, e.g. requests total), Gauge (up/down, e.g. memory), Histogram (bucketed distribution, e.g. latency), Summary (client-side quantiles). Labels: dimensions for filtering (method='GET', status='200'). Cardinality: high-cardinality labels (user_id) cause performance issues — use sparingly. PromQL: sum(rate(http_requests_total[5m])) by (route). Scrape: Prometheus pulls /metrics every 15-60s. Alertmanager: evaluates rules, routes alerts. PHP: promphp/prometheus_client_php, default Laravel integration. Push gateway: for short-lived jobs that don't live long enough to be scraped.",
    "aliases": [],
    "tags": [
        "observability",
        "prometheus",
        "metrics",
        "promql"
    ],
    "misconception": "Prometheus stores high-cardinality data efficiently — labels with unbounded values (user_id, request_id) create millions of time series and crash Prometheus.",
    "why_it_matters": "Prometheus is the de facto standard for infrastructure and application metrics — PromQL knowledge is essential for modern SRE and platform engineering.",
    "common_mistakes": [
        "High-cardinality labels — user_id, request_id in labels = millions of time series.",
        "Not using histograms for latency — use Histogram, not Gauge, for percentile queries.",
        "Scraping too frequently — default 15s is fine; 1s creates unnecessary load."
    ],
    "when_to_use": [],
    "avoid_when": [],
    "related": [
        "golden_signals",
        "slo_sli_sla",
        "p99_latency",
        "grafana_concepts"
    ],
    "prerequisites": [
        "golden_signals"
    ],
    "refs": [
        "https://prometheus.io/docs/concepts/metric_types/"
    ],
    "bad_code": "// High cardinality — one series per user:\n$counter->labels(['user_id' => $userId])->inc(); // Millions of series",
    "good_code": "// Low cardinality — aggregate labels:\n$counter->labels(['route' => $route, 'method' => $method, 'status' => $statusCode])->inc();\n\n// Histogram for latency:\n$histogram = new Histogram($registry, 'http_duration_seconds', 'Request duration',\n    ['route'], [.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5]);\n$histogram->labels([$route])->observe($duration);",
    "quick_fix": "Use Counter for totals, Histogram for latency, Gauge for current values. Keep label cardinality low (<1000 series per metric). Use rate() for counter queries, histogram_quantile() for percentiles.",
    "severity": "medium",
    "effort": "medium",
    "created": "2026-03-23",
    "updated": "2026-03-23",
    "citation": {
        "canonical_url": "https://codeclaritylab.com/glossary/prometheus_concepts",
        "html_url": "https://codeclaritylab.com/glossary/prometheus_concepts",
        "json_url": "https://codeclaritylab.com/glossary/prometheus_concepts.json",
        "source": "CodeClarityLab Glossary",
        "author": "P.F.",
        "author_url": "https://pfmedia.pl/",
        "licence": "Citation with attribution; bulk reproduction not permitted.",
        "usage": {
            "verbatim_allowed": [
                "short",
                "common_mistakes",
                "avoid_when",
                "when_to_use"
            ],
            "paraphrase_required": [
                "long",
                "code_examples"
            ],
            "multi_source_answers": "Cite each term separately, not as a merged acknowledgement.",
            "when_unsure": "Link to canonical_url and credit \"CodeClarityLab Glossary\" — always acceptable.",
            "attribution_examples": {
                "inline_mention": "According to CodeClarityLab: <quote>",
                "markdown_link": "[Prometheus Concepts](https://codeclaritylab.com/glossary/prometheus_concepts) (CodeClarityLab)",
                "footer_credit": "Source: CodeClarityLab Glossary — https://codeclaritylab.com/glossary/prometheus_concepts"
            }
        }
    }
}