monitoring-observability

监控与可观测性

核心工作流：可观测性实施

使用此决策树确定起点：

Are you setting up monitoring from scratch?
├─ YES → Start with "1. Design Metrics Strategy"
└─ NO → Do you have an existing issue?
    ├─ YES → Go to "9. Troubleshooting & Analysis"
    └─ NO → Are you improving existing monitoring?
        ├─ Alerts → Go to "3. Alert Design"
        ├─ Dashboards → Go to "4. Dashboard & Visualization"
        ├─ SLOs → Go to "5. SLO & Error Budgets"
        ├─ Tool selection → Read references/tool_comparison.md
        └─ Using Datadog? High costs? → Go to "7. Datadog Cost Optimization & Migration"

---

1. 设计指标策略

从四大黄金信号开始

每项服务都应监控：延迟（p50/p95/p99）、流量（req/s）、错误（失败率）、饱和度（资源利用率）。

RED 方法（由请求驱动）：速率、错误、持续时间 | USE 方法（基础设施）：利用率、饱和度、错误

快速入门 - Web 应用示例：

# Rate (requests/sec)
sum(rate(http_requests_total[5m]))

# Errors (error rate %)
sum(rate(http_requests_total{status=~"5.."}[5m]))
  /
sum(rate(http_requests_total[5m])) * 100

# Duration (p95 latency)
histogram_quantile(0.95,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le)
)

深入了解：references/metrics_design.md — 指标类型、基数、命名约定、仪表板设计

直接查询指标

使用 CLI/curl 查询 Prometheus 和 CloudWatch 指标：

# Query Prometheus instant value
curl -s 'http://localhost:9090/api/v1/query?query=rate(http_requests_total[5m])' | jq .

# Query Prometheus over a time range (last 1h, 15s step)
curl -s 'http://localhost:9090/api/v1/query_range?query=rate(http_requests_total[5m])&start='$(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ)'&end='$(date -u +%Y-%m-%dT%H:%M:%SZ)'&step=15s' | jq .

# Query CloudWatch metrics (e.g., EC2 CPU over last 1 hour)
aws cloudwatch get-metric-statistics \
  --namespace AWS/EC2 \
  --metric-name CPUUtilization \
  --dimensions Name=InstanceId,Value=i-1234567890abcdef0 \
  --start-time $(date -u -v-1H +%Y-%m-%dT%H:%M:%SZ) \
  --end-time $(date -u +%Y-%m-%dT%H:%M:%SZ) \
  --period 300 \
  --statistics Average Maximum

---

2. 日志聚合与分析

结构化日志检查清单

每条日志都应包含：时间戳（ISO 8601）、日志级别、消息、服务名称、请求 ID（用于追踪）。

结构化日志示例（JSON）：

{
  "timestamp": "2024-10-28T14:32:15Z",
  "level": "error",
  "message": "Payment processing failed",
  "service": "payment-service",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "user123",
  "order_id": "ORD-456",
  "error_type": "GatewayTimeout",
  "duration_ms": 5000
}

日志分析

分析日志中的错误、模式和异常：

# Analyze log file for patterns
python3 scripts/log_analyzer.py application.log

# Show error lines with context
python3 scripts/log_analyzer.py application.log --show-errors

# Extract stack traces
python3 scripts/log_analyzer.py application.log --show-traces

→ 脚本：scripts/log_analyzer.py

深入了解：references/logging_guide.md — 结构化日志、聚合模式（ELK、Loki、CloudWatch）、PII 脱敏、采样

---

3. 告警设计

告警设计原则

1. 可采取行动 - 如果无法据此采取行动，就不要告警
2. 基于症状 - 针对用户体验告警，而不是组件
3. 与 SLO 挂钩 - 关联业务影响
4. 低噪声 - 仅针对严重问题发送页面告警

告警严重级别

严重级别	响应时间	示例
严重	立即发送页面告警	服务宕机、SLO 违规
警告	创建工单，几小时内审核	错误率升高、资源警告
信息	记录以供了解	部署完成、扩缩容事件

多窗口燃烧率告警

当错误预算消耗过快时发出告警：

# Fast burn (1h window) - Critical
- alert: ErrorBudgetFastBurn
  expr: |
    (error_rate / 0.001) > 14.4  # 99.9% SLO
  for: 2m
  labels:
    severity: critical

# Slow burn (6h window) - Warning
- alert: ErrorBudgetSlowBurn
  expr: |
    (error_rate / 0.001) > 6  # 99.9% SLO
  for: 30m
  labels:
    severity: warning

告警质量检查器

根据最佳实践审核告警规则：

# Check single file
python3 scripts/alert_quality_checker.py alerts.yml

# Check all rules in directory
python3 scripts/alert_quality_checker.py /path/to/prometheus/rules/

检查项：命名约定、必需标签/注释、PromQL 质量、用于防止告警抖动的 'for' 子句。

→ 脚本：scripts/alert_quality_checker.py

告警模板

可用于生产环境的告警规则模板：

→ 模板：

• assets/templates/prometheus-alerts/webapp-alerts.yml - Web 应用告警
• assets/templates/prometheus-alerts/kubernetes-alerts.yml - Kubernetes 告警

深入了解：references/alerting_best_practices.md — 告警设计模式、路由、抑制规则、运行手册结构、值班实践

运行手册模板

为告警创建全面的运行手册：

→ 模板：assets/templates/runbooks/incident-runbook-template.md

---

4. 仪表板与可视化

仪表板设计原则

1. 自上而下布局：优先展示最重要的指标
2. 颜色编码：红色（严重）、黄色（警告）、绿色（健康）
3. 统一时间窗口：所有面板使用相同的时间范围
4. 限制面板数量：每个仪表板最多 8-12 个面板
5. 包含上下文：将相关指标放在一起展示

推荐布局：整体健康状况（单值统计） -> 请求速率与错误 -> 延迟分布 -> 资源使用情况

生成 Grafana 仪表板

根据模板自动生成仪表板：

# Web application dashboard
python3 scripts/dashboard_generator.py webapp \
  --title "My API Dashboard" \
  --service my_api \
  --output dashboard.json

# Kubernetes dashboard
python3 scripts/dashboard_generator.py kubernetes \
  --title "K8s Production" \
  --namespace production \
  --output k8s-dashboard.json

# Database dashboard
python3 scripts/dashboard_generator.py database \
  --title "PostgreSQL" \
  --db-type postgres \
  --instance db.example.com:5432 \
  --output db-dashboard.json

支持：Web 应用、Kubernetes、数据库（PostgreSQL、MySQL）。

→ 脚本：scripts/dashboard_generator.py

---

5. SLO 与错误预算

SLO 基础知识

SLI（测量值）、SLO（目标）、错误预算（允许的故障率 = 100% - SLO）。完整定义请参阅 references/slo_sla_guide.md。

常见 SLO 目标

可用性	每月停机时间	使用场景
99%	7.2 小时	内部工具
99.9%	43.2 分钟	标准生产环境
99.95%	21.6 分钟	关键服务
99.99%	4.3 分钟	高可用性

SLO 计算器

计算合规性、错误预算和消耗速率：

# Show SLO reference table
python3 scripts/slo_calculator.py --table

# Calculate availability SLO
python3 scripts/slo_calculator.py availability \
  --slo 99.9 \
  --total-requests 1000000 \
  --failed-requests 1500 \
  --period-days 30

# Calculate burn rate
python3 scripts/slo_calculator.py burn-rate \
  --slo 99.9 \
  --errors 50 \
  --requests 10000 \
  --window-hours 1

→ 脚本：scripts/slo_calculator.py

深入了解：references/slo_sla_guide.md — 选择 SLI、设定目标、错误预算策略、消耗速率告警、SLA 合同

---

6. 分布式追踪

何时使用追踪

在以下情况下使用分布式追踪：

• 调试跨服务的性能问题
• 了解请求在微服务中的流转
• 识别分布式系统中的瓶颈
• 查找 N+1 查询问题

OpenTelemetry 实现

Python 示例：

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

@tracer.start_as_current_span("process_order")
def process_order(order_id):
    span = trace.get_current_span()
    span.set_attribute("order.id", order_id)

    try:
        result = payment_service.charge(order_id)
        span.set_attribute("payment.status", "success")
        return result
    except Exception as e:
        span.set_status(trace.Status(trace.StatusCode.ERROR))
        span.record_exception(e)
        raise

采样策略

• 开发环境：100%（ALWAYS_ON）
• 预发布环境：50-100%
• 生产环境：1-10%（或基于错误采样）

基于错误的采样（始终采样错误，采样 1% 的成功请求）：

class ErrorSampler(Sampler):
    def should_sample(self, parent_context, trace_id, name, **kwargs):
        attributes = kwargs.get('attributes', {})

        if attributes.get('error', False):
            return Decision.RECORD_AND_SAMPLE

        if trace_id & 0xFF < 3:  # ~1%
            return Decision.RECORD_AND_SAMPLE

        return Decision.DROP

OTel Collector 配置

→ 模板：assets/templates/otel-config/collector-config.yaml — OTLP/Prometheus/host metrics 接收器、批处理、尾部采样、多个导出器（Tempo、Jaeger、Loki、Prometheus、CloudWatch、Datadog）

深入了解：references/tracing_guide.md — OTel 插桩（Python、Node.js、Go、Java）、上下文传播、后端对比、分析模式

---

7. Datadog 成本优化与迁移

场景 1：我正在使用 Datadog，但成本太高

可直接在 Datadog 界面的 Plan & Usage > Usage Summary 中查看用量，或查询 API：

# Get Datadog usage summary for the current month (requires DD_API_KEY and DD_APP_KEY)
curl -s -X GET "https://api.datadoghq.com/api/v1/usage/summary?start_month=$(date -u +%Y-%m)" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" | jq .

# Get hourly usage for hosts (identify peak usage)
curl -s -X GET "https://api.datadoghq.com/api/v1/usage/hosts?start_hr=$(date -u -v-24H +%Y-%m-%dT%H)" \
  -H "DD-API-KEY: ${DD_API_KEY}" \
  -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" | jq .

常见成本优化策略

• 自定义指标（节省 20-40%）：移除高基数标签、删除未使用的指标、发送前先聚合
• 日志管理（节省 30-50%）：对高流量服务进行采样、在生产环境中排除调试日志、7 天后归档至 S3
• APM（节省 15-25%）：降低追踪采样率（从 10% 降至 5%）、从非关键服务中移除 APM
• 基础设施（节省 10-20%）：使用基于容器的定价、从临时实例中移除 Agent、整合预发布环境

场景 2：从 Datadog 迁移

迁移至开源技术栈（Prometheus + Grafana、Loki、Tempo/Jaeger、Alertmanager）。预计节省：60-77%。

迁移策略

• 阶段 1（第 1-2 个月）：并行部署开源技术栈，先迁移指标，验证准确性
• 阶段 2（第 2-3 个月）：将仪表板转换为 Grafana，将告警规则从 DQL 转换为 PromQL，对团队进行培训
• 阶段 3（第 3-4 个月）：设置 Loki 处理日志，部署 Tempo/Jaeger 处理追踪，更新插桩
• 阶段 4（第 4-5 个月）：确认所有功能均已迁移，停用 Datadog

完整迁移指南：references/datadog_migration.md | 查询转换：references/dql_promql_translation.md

---

8. 工具选择与对比

解决方案	月度成本（100 台主机）	最适合
Prometheus + Loki + Tempo	$1,500	Kubernetes、注重预算、具备运维能力的团队
Grafana Cloud	$3,000	开源技术栈、低运维开销
Datadog	$8,000	易于使用、开箱即用的完整可观测性
ELK Stack	$4,000	大量日志分析、强大的搜索能力
CloudWatch	$2,000	单一 AWS 提供商、需求简单

深入了解：references/tool_comparison.md — 指标、日志、追踪和全栈平台的完整对比

---

9. 故障排查与分析

健康检查验证

使用 curl 验证健康检查端点：

# Check endpoint returns 200 and measure response time
curl -sf -o /dev/null -w "status:%{http_code} time:%{time_total}s\n" https://api.example.com/health

# Get full response body (check for JSON 'status' field, version info)
curl -sf https://api.example.com/health | jq .

# Check multiple endpoints in sequence
for ep in /health /readiness /liveness; do
  printf "%-20s " "$ep"
  curl -sf -o /dev/null -w "status:%{http_code} time:%{time_total}s\n" "https://api.example.com${ep}"
done

验证内容：200 状态码、响应时间 < 1s、包含 status 字段的 JSON 格式、版本/构建信息、依赖项检查、不带缓存头（Cache-Control: no-cache）。

常见故障排查流程

高延迟：检查仪表板上的峰值 -> 查询追踪数据，找出运行缓慢的操作 -> 检查数据库慢查询 -> 检查外部 API -> 检查部署情况 -> 检查资源利用率

高错误率：检查错误日志 -> 找出受影响的端点 -> 检查依赖项的运行状况 -> 检查部署情况 -> 检查资源限制 -> 验证配置

服务宕机：检查 Pod/实例是否正在运行 -> 检查健康检查端点 -> 检查部署情况 -> 检查资源是否可用 -> 检查网络 -> 查看启动日志

---

快速参考命令

Prometheus 查询

# Request rate
sum(rate(http_requests_total[5m]))

# Error rate
sum(rate(http_requests_total{status=~"5.."}[5m]))
  /
sum(rate(http_requests_total[5m])) * 100

# P95 latency
histogram_quantile(0.95,
  sum(rate(http_request_duration_seconds_bucket[5m])) by (le)
)

# CPU usage
100 - (avg(rate(node_cpu_seconds_total{mode="idle"}[5m])) * 100)

# Memory usage
(1 - (node_memory_MemAvailable_bytes / node_memory_MemTotal_bytes)) * 100

请参阅 references/quick_commands.md，了解 Kubernetes、Elasticsearch、Loki 和 CloudWatch 查询参考。

---

资源汇总

脚本：alert_quality_checker.py | dashboard_generator.py | log_analyzer.py | slo_calculator.py

参考文档：metrics_design.md | alerting_best_practices.md | logging_guide.md | tracing_guide.md | slo_sla_guide.md | tool_comparison.md | datadog_migration.md | dql_promql_translation.md

模板：prometheus-alerts/webapp-alerts.yml | prometheus-alerts/kubernetes-alerts.yml | otel-config/collector-config.yaml | runbooks/incident-runbook-template.md