Prometheus Notes #

This is my learning Notes for Prometheus

Docs, Github

Prometheus Course (LFS241), PromLabs, Robust Perception

awesome-prometheus

Introduction to Observability #

可观测性（Observability）的三大支柱：

监控（Monitoring）回答"系统是否正常"，可观测性（Observability）回答"为什么不正常"——能否从外部输出推断系统内部状态。Prometheus 专注于 Metrics 维度。

Architecture #

核心组件：

┌─────────────────────────────────────────────────────────────┐
│                      Prometheus Server                      │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌──────────┐ │
│  │ Retrieval │→ │   TSDB    │→ │  HTTP     │  │   Alert  │ │
│  │  (Pull)   │  │ (Storage) │  │  Server   │  │ Manager  │ │
│  └─────┬─────┘  └───────────┘  └──────────┘  └────┬─────┘ │
│        │                                            │       │
└────────┼────────────────────────────────────────────┼───────┘
         │                                            │
    ┌────▼──────────────────────┐               ┌────▼──────┐
    │  Service Discovery        │               │  Alert    │
    │  Kubernetes / Consul / EC2│              │  Manager  │
    └────┬──────────────────────┘               └────┬──────┘
         │                                           │
    ┌────▼────────────────────┐                ┌─────▼─────┐
    │  Targets (Exporters)    │                │  Pager    │
    │  node_exporter / app    │                │  Email    │
    └─────────────────────────┘                │  Slack    │
                                               └───────────┘
    ┌──────────────────┐
    │   Pushgateway    │ ← short-lived jobs push metrics here
    └────────┬─────────┘
             │ (Prometheus still pulls from Pushgateway)

Prometheus 核心设计：Pull 模型——Prometheus 主动从目标 HTTP 端点（默认 /metrics）拉取指标，而非被动等待推送。

Data Model #

Metric Types #

Labels & Time Series #

一条时序由 metric name + label set 唯一标识：

http_requests_total{method="POST", endpoint="/api", status="200"}  1234
└── metric name ──┘  └─────────── labels ───────────────────────┘  └ value

注意：高基数（high cardinality）标签（如 user_id, request_id）会导致时序爆炸，应避免。

Naming Conventions #

• metric name 使用 snake_case，包含单位后缀（_seconds, _bytes, _total）
• 应用前缀表示所属子系统：http_, node_, go_
• Counter 类型以 _total 结尾

Installation & Setup #

Docker Quick Start #

# 启动 Prometheus
docker run -d \
  --name prometheus \
  -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus

# 启动 node_exporter（主机指标）
docker run -d --name node-exporter -p 9100:9100 prom/node-exporter

prometheus.yml 配置示例 #

global:
  scrape_interval: 15s          # 抓取间隔
  evaluation_interval: 15s     # 规则评估间隔

alerting:
  alertmanagers:
    - static_configs:
        - targets: ['localhost:9093']

rule_files:
  - "alerts.yml"
  - "recording_rules.yml"

scrape_configs:
  - job_name: 'prometheus'       # 监控 Prometheus 自身
    static_configs:
      - targets: ['localhost:9090']

  - job_name: 'node'            # 主机指标
    static_configs:
      - targets: ['localhost:9100']

常用启动参数 #

PromQL #

基础查询 #

# 即时向量（instant vector）：当前值
node_memory_MemAvailable_bytes

# 带标签过滤
http_requests_total{method="GET", status="200"}

# 范围向量（range vector）：过去 5 分钟
rate(http_requests_total[5m])

# 聚合运算
sum by (instance) (rate(http_requests_total[5m]))

常用函数 #

运算符示例 #

# 计算每个实例的 CPU 使用率
1 - avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m]))

# 过滤错误率 > 5% 的端点
rate(http_requests_total{status=~"5.."}[5m])
  / rate(http_requests_total[5m]) > 0.05

# 向量匹配：按 instance 标签做除法
rate(http_errors_total[5m])
  / on(instance) rate(http_requests_total[5m])

rate() 用于 Counter，irate() 适合短期告警；计算 P99 延迟必须配合 _bucket 与 histogram_quantile()。

PromQL Cheatsheet

Service Discovery #

静态配置 static_configs 适合固定目标；动态环境需 Service Discovery。

scrape_configs:
  - job_name: 'consul-services'
    consul_sd_configs:
      - server: 'localhost:8500'
    relabel_configs:
      - source_labels: [__meta_consul_tags]
        regex: '.*,metrics,.*'
        action: keep

Relabeling #

Relabeling 在抓取前后对 label 进行增删改，是 Prometheus 最强大也最易混淆的特性之一。

常用 action #

# 示例：只抓取带 prometheus.io/scrape=true 注解的 Pod
relabel_configs:
  - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
    action: keep
    regex: true

  # 将 Pod 注解中的路径设为抓取路径
  - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
    action: replace
    target_label: __metrics_path__
    regex: (.+)

# 抓取后丢弃高基数标签，避免时序爆炸
metric_relabel_configs:
  - action: labeldrop
    regex: 'request_id|user_id'

__ 开头的 label（如 __address__, __metrics_path__）是元标签（meta label），在最终存储前会被自动移除，除非用 replace 显式映射到普通 label。

Exporters #

常用 Exporters #

Instrumenting Code #

直接在应用代码中埋点，推荐使用官方 client library：

Alerting #

告警流程：Alert Rule → Prometheus 评估 → Alertmanager 去重/分组/路由 → Receiver

alerts.yml 示例 #

groups:
  - name: node-alerts
    rules:
      - alert: HighCpuUsage
        expr: 1 - avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m])) > 0.85
        for: 5m              # 持续满足 5 分钟才触发
        labels:
          severity: warning
        annotations:
          summary: "High CPU usage on {{ $labels.instance }}"
          description: "CPU usage is {{ $value | humanizePercentage }} (threshold 85%)"

      - alert: DiskSpaceLow
        expr: 1 - (node_filesystem_avail_bytes / node_filesystem_size_bytes) > 0.85
        for: 10m
        labels:
          severity: critical
        annotations:
          summary: "Disk space low on {{ $labels.instance }}"

Alertmanager 路由配置 #

route:
  receiver: 'default'
  group_by: ['alertname', 'cluster']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 4h

receivers:
  - name: 'default'
    email_configs:
      - to: 'ops@example.com'
    slack_configs:
      - api_url: 'https://hooks.slack.com/services/xxx'
        channel: '#alerts'

inhibit_rules:
  - source_match: { severity: 'critical' }
    target_match: { severity: 'warning' }
    equal: ['instance']   # 同一实例 critical 抑制 warning

Recording Rules #

预计算高频、复杂查询的结果，避免每次查询实时重算。

groups:
  - name: recording-rules
    interval: 30s
    rules:
      - record: job:http_requests:rate5m
        expr: sum by (job) (rate(http_requests_total[5m]))

      - record: instance:cpu_usage:ratio
        expr: 1 - avg by (instance) (rate(node_cpu_seconds_total{mode="idle"}[5m]))

命名约定：level:metric:operations，如 job:http_requests:rate5m。

Pushgateway #

Pull 模型不适合短生命周期任务（如 Cron Job）——任务可能结束时 Prometheus 还未抓取。Pushgateway 作为中转：任务将指标推送到 Pushgateway，Prometheus 再从中拉取。

# 推送示例
echo "batch_jobs_total 42" | \
  curl --data-binary @- http://localhost:9091/metrics/job/batch_job

Pushgateway 不替代 Pull 模型，仅用于短生命周期/批处理任务。常驻服务应直接暴露 /metrics。

Blackbox Monitoring #

blackbox_exporter 从外部探测端点可用性（HTTP/TCP/ICMP/DNS），与 node_exporter 的"白盒"内部指标互补。

scrape_configs:
  - job_name: 'blackbox-http'
    metrics_path: /probe
    params:
      module: [http_2xx]
    static_configs:
      - targets:
          - https://example.com
          - https://api.example.com/health
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: localhost:9115  # blackbox_exporter 地址

Storage #

Local TSDB #

Prometheus 本地存储为自定义时序数据库（TSDB），采用基于时间的分块（block）存储，每个 block 默认 2 小时，含压缩的 chunk 数据与索引。

Remote Storage Integrations #

本地存储不适合长期保存（数月/年级别）。通过 Remote Read/Write 对接远端存储：

High Availability & Scaling #

Prometheus 本身是单实例设计（无原生集群）。HA 与扩展方案：

Thanos 架构 #

┌────────────────┐  ┌────────────────┐  ┌────────────────┐
│  Prometheus    │  │  Prometheus    │  │  Prometheus    │
│  + Thanos      │  │  + Thanos      │  │  + Thanos      │
│  Sidecar       │  │  Sidecar       │  │  Sidecar       │
└───────┬────────┘  └───────┬────────┘  └───────┬────────┘
        │ upload             │ upload            │ upload
        ▼                    ▼                   ▼
┌──────────────────────────────────────────────────────────┐
│           Object Storage (S3 / OSS / GCS)               │
└──────────────────────────┬───────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│     Store    │  │  Compactor   │  │    Query     │
│   Gateway    │  │ (downsample) │  │ (PromQL UI)  │
└──────────────┘  └──────────────┘  └──────────────┘

Prometheus & Kubernetes #

kube-prometheus-stack #

社区推荐的 K8s 监控套件（Helm Chart），包含：

• Prometheus Operator
• Prometheus（多实例管理）
• Alertmanager
• Grafana
• node_exporter（DaemonSet）
• kube-state-metrics
• 预置告警规则与 Dashboard

helm repo add prometheus-community https://prometheus-community.github.io/helm-charts
helm install kube-prometheus-stack prometheus-community/kube-prometheus-stack

Prometheus Operator CRD #

K8s 关键监控指标 #

Monitoring & Debugging Prometheus #

自我监控指标 #

Prometheus 暴露自身的运行指标（prometheus_* 前缀）：

常见问题排查 #

Questions #

• Recording Rules 与 Alert Rules 的最佳拆分粒度
• Thanos Query 与 VictoriaMetrics 的选型对比
• PromQL 中 on() vs ignoring() 的使用场景

Reference #

Prometheus, Docs, Github

Prometheus Course (LFS241), PromLabs, Robust Perception

Best Practices, PromQL Cheatsheet

Thanos, Cortex, Mimir, VictoriaMetrics

kube-prometheus-stack, Prometheus Operator

node_exporter, blackbox_exporter

Demo: Docker-Compose-Prometheus-and-Grafana