4. 基于 Prometheus 的 SLI 采集：使用 Histogram 和 Summary 记录请求延迟，使用 Counter 记录错误计数，指标命名规范与标签设计

SLI（Service Level Indicator）是 SLO 的量化基石。Prometheus 通过四种核心指标类型（Counter、Gauge、Histogram、Summary）来采集 SLI 数据。本章聚焦于 请求延迟 和 错误计数 两个最关键的 SLI，讲解如何正确使用 Histogram/Summary 记录延迟分布，使用 Counter 记录错误次数，并遵循 Prometheus 官方命名规范与标签设计原则。

4.1 核心 SLI 指标类型选择

4.2 使用 Histogram 记录请求延迟

Histogram 将观测值放入预定义的桶（bucket）中，同时记录总计数和总和。以下是一个典型的 HTTP 请求延迟 Histogram 采集示例：

// 定义 Histogram 指标
http_request_duration_seconds = Histogram(
    'http_request_duration_seconds',
    'HTTP request latency in seconds',
    ['method', 'path', 'status'],
    buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
)

// 在请求处理结束时记录延迟
def handle_request(method, path):
    start = time.time()
    try:
        # 处理请求逻辑
        response = process_request(method, path)
        status = response.status_code
    except Exception as e:
        status = 500
    finally:
        duration = time.time() - start
        http_request_duration_seconds.labels(
            method=method, path=path, status=status
        ).observe(duration)

桶（Bucket）设计原则：

• 桶的范围应覆盖预期的延迟分布，通常从 5ms 到 10s。
• 在 SLO 目标值附近（如 200ms、500ms）增加桶密度，提高分位数精度。
• Prometheus 自动添加 +Inf 桶，确保所有观测值都被计数。

4.3 使用 Summary 记录请求延迟（备选方案）

当无法在服务端聚合分位数，或需要精确的滑动窗口分位数时，可以使用 Summary。但注意 Summary 的分位数是客户端计算的，无法跨进程聚合。

// 定义 Summary 指标
http_request_duration_summary = Summary(
    'http_request_duration_summary',
    'HTTP request latency summary in seconds',
    ['method', 'path', 'status'],
    quantiles=(0.5, 0.9, 0.99)
)

// 记录延迟
http_request_duration_summary.labels(
    method='GET', path='/api/users', status='200'
).observe(0.123)

4.4 使用 Counter 记录错误计数

错误计数通常作为 http_requests_total 的一个标签维度，而不是单独定义一个指标。这样可以通过 PromQL 的 rate() 和 sum() 灵活计算错误率。

// 定义 Counter 指标
http_requests_total = Counter(
    'http_requests_total',
    'Total number of HTTP requests',
    ['method', 'path', 'status']
)

// 在请求结束时递增计数
def handle_request(method, path):
    status = process_request(method, path)
    http_requests_total.labels(
        method=method, path=path, status=status
    ).inc()

错误率计算 PromQL 示例：

# 5 分钟内错误率（status 以 5xx 开头）
rate(http_requests_total{status=~"5.."}[5m])
/
rate(http_requests_total[5m])

4.5 指标命名规范与标签设计

Prometheus 官方命名规范要求指标名遵循 namespace_subsystem_unit_suffix 格式。标签设计应遵循“少而精”原则，避免基数爆炸。

4.6 SLI 采集架构图

下图展示了基于 Prometheus 的 SLI 采集整体架构，从应用埋点到指标存储与查询：

4.7 完整采集示例：结合 Histogram 与 Counter

以下是一个完整的 Python Flask 应用示例，同时采集请求延迟 Histogram 和请求计数 Counter：

from prometheus_client import Histogram, Counter, generate_latest
from flask import Flask, request, Response
import time

app = Flask(__name__)

# 定义指标
REQUEST_DURATION = Histogram(
    'http_request_duration_seconds',
    'HTTP request latency in seconds',
    ['method', 'endpoint', 'status'],
    buckets=(0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0)
)

REQUEST_COUNT = Counter(
    'http_requests_total',
    'Total number of HTTP requests',
    ['method', 'endpoint', 'status']
)

@app.before_request
def before_request():
    request.start_time = time.time()

@app.after_request
def after_request(response):
    duration = time.time() - request.start_time
    REQUEST_DURATION.labels(
        method=request.method,
        endpoint=request.path,
        status=response.status_code
    ).observe(duration)
    REQUEST_COUNT.labels(
        method=request.method,
        endpoint=request.path,
        status=response.status_code
    ).inc()
    return response

@app.route('/metrics')
def metrics():
    return Response(generate_latest(), mimetype='text/plain')

@app.route('/api/users')
def get_users():
    return {'users': ['alice', 'bob']}

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8000)

4.8 标签设计实战：避免高基数陷阱

标签设计不当会导致 Prometheus 存储爆炸和查询性能下降。以下对比展示了正确与错误的标签设计：

4.9 Histogram 与 Summary 对比总结