Metrics Collection
Prometheus-compatible metrics for visibility into system behavior.
When to Use This Skill
- Need visibility into request rates and latencies
- Want to track business metrics (signups, conversions)
- Building dashboards and alerts
- Debugging performance issues
Core Concepts
Three metric types cover most use cases:
| Type | Use Case | Example |
|---|---|---|
| Counter | Things that only go up | Requests, errors, events |
| Gauge | Current value | Active connections, queue size |
| Histogram | Distribution of values | Request latency, response sizes |
Implementation
TypeScript
interface CounterMetric {
name: string;
help: string;
labels: string[];
values: Map<string, number>;
}
interface GaugeMetric {
name: string;
help: string;
labels: string[];
values: Map<string, number>;
}
interface HistogramMetric {
name: string;
help: string;
labels: string[];
buckets: number[];
values: Map<string, { count: number; sum: number; buckets: number[] }>;
}
class MetricsRegistry {
private counters = new Map<string, CounterMetric>();
private gauges = new Map<string, GaugeMetric>();
private histograms = new Map<string, HistogramMetric>();
// Counter methods
registerCounter(name: string, help: string, labels: string[] = []): void {
if (!this.counters.has(name)) {
this.counters.set(name, { name, help, labels, values: new Map() });
}
}
incrementCounter(name: string, labels: Record<string, string> = {}, value = 1): void {
const counter = this.counters.get(name);
if (!counter) return;
const key = this.labelsToKey(labels);
const current = counter.values.get(key) || 0;
counter.values.set(key, current + value);
}
// Gauge methods
registerGauge(name: string, help: string, labels: string[] = []): void {
if (!this.gauges.has(name)) {
this.gauges.set(name, { name, help, labels, values: new Map() });
}
}
setGauge(name: string, value: number, labels: Record<string, string> = {}): void {
const gauge = this.gauges.get(name);
if (!gauge) return;
const key = this.labelsToKey(labels);
gauge.values.set(key, value);
}
incrementGauge(name: string, labels: Record<string, string> = {}, value = 1): void {
const gauge = this.gauges.get(name);
if (!gauge) return;
const key = this.labelsToKey(labels);
const current = gauge.values.get(key) || 0;
gauge.values.set(key, current + value);
}
decrementGauge(name: string, labels: Record<string, string> = {}, value = 1): void {
this.incrementGauge(name, labels, -value);
}
// Histogram methods
registerHistogram(
name: string,
help: string,
labels: string[] = [],
buckets: number[] = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
): void {
if (!this.histograms.has(name)) {
this.histograms.set(name, { name, help, labels, buckets, values: new Map() });
}
}
observeHistogram(name: string, value: number, labels: Record<string, string> = {}): void {
const histogram = this.histograms.get(name);
if (!histogram) return;
const key = this.labelsToKey(labels);
let data = histogram.values.get(key);
if (!data) {
data = { count: 0, sum: 0, buckets: new Array(histogram.buckets.length).fill(0) };
histogram.values.set(key, data);
}
data.count++;
data.sum += value;
for (let i = 0; i < histogram.buckets.length; i++) {
if (value <= histogram.buckets[i]) {
data.buckets[i]++;
}
}
}
// Timer helper
startTimer(histogramName: string, labels: Record<string, string> = {}): () => void {
const start = performance.now();
return () => {
const duration = (performance.now() - start) / 1000;
this.observeHistogram(histogramName, duration, labels);
};
}
// Export to Prometheus format
toPrometheus(): string {
const lines: string[] = [];
for (const counter of this.counters.values()) {
lines.push(`# HELP ${counter.name} ${counter.help}`);
lines.push(`# TYPE ${counter.name} counter`);
for (const [labels, value] of counter.values) {
const labelStr = labels ? `{${labels}}` : '';
lines.push(`${counter.name}${labelStr} ${value}`);
}
}
for (const gauge of this.gauges.values()) {
lines.push(`# HELP ${gauge.name} ${gauge.help}`);
lines.push(`# TYPE ${gauge.name} gauge`);
for (const [labels, value] of gauge.values) {
const labelStr = labels ? `{${labels}}` : '';
lines.push(`${gauge.name}${labelStr} ${value}`);
}
}
for (const histogram of this.histograms.values()) {
lines.push(`# HELP ${histogram.name} ${histogram.help}`);
lines.push(`# TYPE ${histogram.name} histogram`);
for (const [labels, data] of histogram.values) {
const labelStr = labels ? `${labels},` : '';
for (let i = 0; i < histogram.buckets.length; i++) {
lines.push(`${histogram.name}_bucket{${labelStr}le="${histogram.buckets[i]}"} ${data.buckets[i]}`);
}
lines.push(`${histogram.name}_bucket{${labelStr}le="+Inf"} ${data.count}`);
lines.push(`${histogram.name}_sum{${labels}} ${data.sum}`);
lines.push(`${histogram.name}_count{${labels}} ${data.count}`);
}
}
return lines.join('\n');
}
toJSON(): object {
return {
counters: Object.fromEntries(
Array.from(this.counters.entries()).map(([name, metric]) => [
name, Object.fromEntries(metric.values),
])
),
gauges: Object.fromEntries(
Array.from(this.gauges.entries()).map(([name, metric]) => [
name, Object.fromEntries(metric.values),
])
),
histograms: Object.fromEntries(
Array.from(this.histograms.entries()).map(([name, metric]) => [
name, Object.fromEntries(metric.values),
])
),
};
}
private labelsToKey(labels: Record<string, string>): string {
return Object.entries(labels)
.sort(([a], [b]) => a.localeCompare(b))
.map(([k, v]) => `${k}="${v}"`)
.join(',');
}
}
export const metrics = new MetricsRegistry();
// Pre-register common metrics
metrics.registerCounter('http_requests_total', 'Total HTTP requests', ['method', 'path', 'status']);
metrics.registerCounter('errors_total', 'Total errors', ['type', 'source']);
metrics.registerHistogram('http_request_duration_seconds', 'HTTP request duration', ['method', 'path']);
metrics.registerGauge('active_connections', 'Active connections');
metrics.registerGauge('queue_size', 'Queue size', ['queue']);Python
from dataclasses import dataclass, field
from typing import Dict, List, Optional, Callable
import time
@dataclass
class CounterMetric:
name: str
help: str
labels: List[str]
values: Dict[str, float] = field(default_factory=dict)
@dataclass
class GaugeMetric:
name: str
help: str
labels: List[str]
values: Dict[str, float] = field(default_factory=dict)
@dataclass
class HistogramData:
count: int = 0
sum: float = 0
buckets: List[int] = field(default_factory=list)
@dataclass
class HistogramMetric:
name: str
help: str
labels: List[str]
bucket_bounds: List[float]
values: Dict[str, HistogramData] = field(default_factory=dict)
class MetricsRegistry:
DEFAULT_BUCKETS = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
def __init__(self):
self._counters: Dict[str, CounterMetric] = {}
self._gauges: Dict[str, GaugeMetric] = {}
self._histograms: Dict[str, HistogramMetric] = {}
def register_counter(self, name: str, help: str, labels: List[str] = None) -> None:
if name not in self._counters:
self._counters[name] = CounterMetric(name, help, labels or [])
def increment_counter(self, name: str, labels: Dict[str, str] = None, value: float = 1) -> None:
counter = self._counters.get(name)
if not counter:
return
key = self._labels_to_key(labels or {})
counter.values[key] = counter.values.get(key, 0) + value
def register_gauge(self, name: str, help: str, labels: List[str] = None) -> None:
if name not in self._gauges:
self._gauges[name] = GaugeMetric(name, help, labels or [])
def set_gauge(self, name: str, value: float, labels: Dict[str, str] = None) -> None:
gauge = self._gauges.get(name)
if not gauge:
return
key = self._labels_to_key(labels or {})
gauge.values[key] = value
def increment_gauge(self, name: str, labels: Dict[str, str] = None, value: float = 1) -> None:
gauge = self._gauges.get(name)
if not gauge:
return
key = self._labels_to_key(labels or {})
gauge.values[key] = gauge.values.get(key, 0) + value
def register_histogram(
self, name: str, help: str, labels: List[str] = None, buckets: List[float] = None
) -> None:
if name not in self._histograms:
self._histograms[name] = HistogramMetric(
name, help, labels or [], buckets or self.DEFAULT_BUCKETS
)
def observe_histogram(self, name: str, value: float, labels: Dict[str, str] = None) -> None:
histogram = self._histograms.get(name)
if not histogram:
return
key = self._labels_to_key(labels or {})
if key not in histogram.values:
histogram.values[key] = HistogramData(
buckets=[0] * len(histogram.bucket_bounds)
)
data = histogram.values[key]
data.count += 1
data.sum += value
for i, bound in enumerate(histogram.bucket_bounds):
if value <= bound:
data.buckets[i] += 1
def start_timer(self, histogram_name: str, labels: Dict[str, str] = None) -> Callable[[], None]:
start = time.perf_counter()
def end_timer():
duration = time.perf_counter() - start
self.observe_histogram(histogram_name, duration, labels)
return end_timer
def to_prometheus(self) -> str:
lines = []
for counter in self._counters.values():
lines.append(f"# HELP {counter.name} {counter.help}")
lines.append(f"# TYPE {counter.name} counter")
for labels, value in counter.values.items():
label_str = f"{{{labels}}}" if labels else ""
lines.append(f"{counter.name}{label_str} {value}")
for gauge in self._gauges.values():
lines.append(f"# HELP {gauge.name} {gauge.help}")
lines.append(f"# TYPE {gauge.name} gauge")
for labels, value in gauge.values.items():
label_str = f"{{{labels}}}" if labels else ""
lines.append(f"{gauge.name}{label_str} {value}")
for histogram in self._histograms.values():
lines.append(f"# HELP {histogram.name} {histogram.help}")
lines.append(f"# TYPE {histogram.name} histogram")
for labels, data in histogram.values.items():
label_prefix = f"{labels}," if labels else ""
for i, bound in enumerate(histogram.bucket_bounds):
lines.append(f'{histogram.name}_bucket{{{label_prefix}le="{bound}"}} {data.buckets[i]}')
lines.append(f'{histogram.name}_bucket{{{label_prefix}le="+Inf"}} {data.count}')
lines.append(f"{histogram.name}_sum{{{labels}}} {data.sum}")
lines.append(f"{histogram.name}_count{{{labels}}} {data.count}")
return "\n".join(lines)
def _labels_to_key(self, labels: Dict[str, str]) -> str:
return ",".join(f'{k}="{v}"' for k, v in sorted(labels.items()))
# Singleton
metrics = MetricsRegistry()
# Pre-register common metrics
metrics.register_counter("http_requests_total", "Total HTTP requests", ["method", "path", "status"])
metrics.register_counter("errors_total", "Total errors", ["type", "source"])
metrics.register_histogram("http_request_duration_seconds", "HTTP request duration", ["method", "path"])
metrics.register_gauge("active_connections", "Active connections")
metrics.register_gauge("queue_size", "Queue size", ["queue"])Usage Examples
HTTP Request Tracking
async function withMetrics(
handler: () => Promise<Response>,
method: string,
path: string
): Promise<Response> {
const endTimer = metrics.startTimer('http_request_duration_seconds', { method, path });
try {
const response = await handler();
metrics.incrementCounter('http_requests_total', {
method, path, status: String(response.status),
});
return response;
} catch (error) {
metrics.incrementCounter('http_requests_total', { method, path, status: '500' });
metrics.incrementCounter('errors_total', { type: 'http', source: path });
throw error;
} finally {
endTimer();
}
}Queue Monitoring
class JobQueue {
private queue: Job[] = [];
add(job: Job): void {
this.queue.push(job);
metrics.setGauge('queue_size', this.queue.length, { queue: 'jobs' });
}
process(): Job | undefined {
const job = this.queue.shift();
metrics.setGauge('queue_size', this.queue.length, { queue: 'jobs' });
return job;
}
}Business Metrics
metrics.registerCounter('predictions_generated', 'Predictions generated', ['tier']);
metrics.registerCounter('user_signups', 'User signups', ['source']);
async function generatePrediction(userId: string, tier: string) {
const endTimer = metrics.startTimer('prediction_latency_seconds');
try {
const prediction = await mlPipeline.generate();
metrics.incrementCounter('predictions_generated', { tier });
return prediction;
} finally {
endTimer();
}
}Metrics Endpoint
app.get('/metrics', (req, res) => {
res.set('Content-Type', 'text/plain; charset=utf-8');
res.send(metrics.toPrometheus());
});Best Practices
- Use consistent naming (snake_case, units in name)
- Keep cardinality low (avoid high-cardinality labels)
- Pre-register metrics at startup
- Use histograms for latencies, not gauges
- Include units in metric names (_seconds, _bytes)
Common Mistakes
- High cardinality labels (user_id as label)
- Using gauges for latency (use histograms)
- Not pre-registering metrics
- Missing units in names
- Too many buckets in histograms
Related Patterns
- health-checks - Health endpoints for probes
- anomaly-detection - Alert on metric anomalies
- logging-observability - Correlate logs with metrics