Metrics Types

Also Known As

TL;DR

Explanation

Counter: monotonically increasing integer — request count, error count. Never decreases. Use rate() to get per-second rate. Gauge: current value that can go up or down — memory usage, active connections, queue depth. Histogram: samples observations into configurable buckets — request duration, response size. Enables percentile calculation (p95, p99) across multiple instances. Summary: calculates percentiles client-side — accurate but cannot be aggregated across instances. For distributed PHP apps, histograms are almost always preferred over summaries.

Diagram

flowchart TD
    subgraph Counter
        C[Monotonically increasing<br/>requests_total errors_total]
        C_USE["Use rate() for per-second rate<br/>never decreases"]
    end
    subgraph Gauge
        G[Current value up or down<br/>memory_usage active_connections]
        G_USE[Snapshot of state right now]
    end
    subgraph Histogram
        H[Samples in buckets<br/>request_duration_seconds]
        H_USE[Calculate p50 p95 p99<br/>aggregatable across instances]
    end
    subgraph Summary
        S[Pre-calculated percentiles<br/>accurate but not aggregatable]
    end
style C fill:#1f6feb,color:#fff
style G fill:#238636,color:#fff
style H fill:#6e40c9,color:#fff
style S fill:#d29922,color:#fff

Common Misconception

Why It Matters

Common Mistakes

• Using a gauge for a counter (request count) — gauges reset to 0 on restart, losing the total count.
• Average latency instead of p95/p99 histogram — hides the tail experience of slow requests.
• High-cardinality histogram labels — a label per user ID creates millions of time series.
• Summaries in distributed systems — summaries cannot be aggregated across PHP-FPM workers; use histograms.

Code Examples

// Wrong types — gauge for counter, average for latency:
$registry->registerGauge('app', 'requests_total', 'Total requests');
$gauge->set($gauge->get() + 1); // Gauge — resets to 0 on restart, not monotonic

// Average latency — hides tail:
$totalTime += $elapsed;
$avgLatency = $totalTime / $requestCount; // Misleading

// Correct types with prometheus_client_php:
$counter = $registry->registerCounter('app', 'requests_total', 'Total requests', ['route']);
$counter->inc(['route' => '/api/users']); // Monotonically increasing

$histogram = $registry->registerHistogram(
    'app', 'request_duration_seconds', 'Request duration',
    ['route'],
    [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5] // Buckets in seconds
);
$histogram->observe($elapsed, ['route' => '/api/users']);
// Query p99: histogram_quantile(0.99, rate(app_request_duration_seconds_bucket[5m]))

References

• ↗ https://prometheus.io/docs/concepts/metric_types/

Tags

Related Terms