# Prometheus 知识学习手册 · 第 1 篇：入门与架构

> 基于 [prometheus.io 官方文档](https://prometheus.io/docs/introduction/overview/) 整理
> 文档版本：Prometheus v3.15.0（最新稳定版，2026-10 发布）｜ 抓取日期：2026-10-08
> 数据来源：prometheus/prometheus@v3.15.0、prometheus/alertmanager、prometheus/docs 官方仓库源文件（与官网 latest 内容一致）
>
> **全册结构（共 4 篇）**
> - **第 1 篇：入门与架构** ← 本篇
> - 第 2 篇：PromQL 与查询
> - 第 3 篇：配置与运维
> - 第 4 篇：Alertmanager 与生态（告警、插桩、可视化、规范）

---

## 目录

- [第 1 章 概述](#第-1-章-概述)
  - [1.1 Prometheus 是什么](#11-prometheus-是什么)
  - [1.2 解决什么问题](#12-解决什么问题)
  - [1.3 核心特点](#13-核心特点)
  - [1.4 适用场景：何时该用、何时不该用](#14-适用场景何时该用何时不该用)
  - [1.5 竞品对比](#15-竞品对比)
- [第 2 章 快速上手](#第-2-章-快速上手)
  - [2.1 环境要求](#21-环境要求)
  - [2.2 下载与安装](#22-下载与安装)
  - [2.3 5 分钟跑通](#23-5-分钟跑通)
  - [2.4 官方 Hello World 教程完整步骤](#24-官方-hello-world-教程完整步骤)
  - [2.5 验证安装成功](#25-验证安装成功)
  - [2.6 常见启动问题](#26-常见启动问题)
- [第 3 章 核心概念](#第-3-章-核心概念)
  - [3.1 数据模型详解](#31-数据模型详解)
  - [3.2 四种指标类型](#32-四种指标类型)
  - [3.3 Jobs 与 Instances](#33-jobs-与-instances)
  - [3.4 术语表](#34-术语表)
- [第 4 章 架构与设计](#第-4-章-架构与设计)
  - [4.1 设计哲学与动机](#41-设计哲学与动机)
  - [4.2 整体架构与组件关系](#42-整体架构与组件关系)
  - [4.3 Agent 模式（对比 Server 模式）](#43-agent-模式对比-server-模式)
  - [4.4 API 稳定性承诺](#44-api-稳定性承诺)
- [第 5 章 生态与版本](#第-5-章-生态与版本)
  - [5.1 路线图](#51-路线图)
  - [5.2 发布周期与 LTS 策略](#52-发布周期与-lts-策略)
  - [5.3 学习资源](#53-学习资源)
  - [5.4 官方 FAQ 整理](#54-官方-faq-整理)
- [附录：本篇覆盖清单](#附录本篇覆盖清单)

---

## 第 1 章 概述

### 1.1 Prometheus 是什么

`Prometheus` 是一个开源的**系统监控与告警工具箱**（monitoring and alerting toolkit）。

- 最初由 `SoundCloud` 构建，**2012 年**启动。
- **2016 年**作为继 `Kubernetes` 之后**第二个**托管项目加入 `Cloud Native Computing Foundation`（CNCF，cncf.io）。
- 现为**独立开源项目**，独立于任何公司维护。
- 它是 `Kubernetes` 唯一直接支持的系统监控方案，也是云原生生态的事实标准。

其数据本质是：以**时间序列数据（time series data）**采集并存储指标——即每条指标信息都带记录时的时间戳，并附带可选的键值对 `labels`。

> 💡 补充：Prometheus 的“复数”在官方 FAQ 中经研究确定为 **Prometheis**；记不住时可直接用 “Prometheus instances”。

> 引自：[Overview](https://prometheus.io/docs/introduction/overview/) ｜ [Frequently asked questions](https://prometheus.io/docs/introduction/faq/) ｜ [Getting started with Prometheus](https://prometheus.io/docs/tutorials/getting_started/)

### 1.2 解决什么问题

要理解 Prometheus 解决什么问题，先理解 **metrics（指标）** 与 **time series（时间序列）**。

- **metrics**：通俗意义上的**数值测量**。
- **time series**：随时间变化的记录。

**为什么需要它**：不同应用关心的测量内容不同——

| 系统类型 | 典型关注指标 |
| --- | --- |
| Web 服务器 | 请求耗时（request times） |
| 数据库 | CPU 使用率、活跃连接数、活跃查询数 |

以“Web 服务器变慢”为例：请求计数（request count）指标显示请求量变高，据此即可判断“变慢是因为请求量高”，并据此扩容服务器。

官方教程给出的指标定义自问法（非常实用）：

> **“what all information will be important for me to debug if any issue occurs in my application?”**
> （如果我的应用出了问题，哪些信息对调试重要？）

Prometheus 就是系统化地回答这个问题的工具：定义指标 → 暴露指标 → 抓取存储 → 查询告警。

> 引自：[Overview](https://prometheus.io/docs/introduction/overview/) ｜ [Getting started with Prometheus](https://prometheus.io/docs/tutorials/getting_started/)

### 1.3 核心特点

官方 Overview 列出的核心特性（Features）逐条如下：

| # | 特性 | 说明 |
| --- | --- | --- |
| 1 | 多维数据模型（multi-dimensional data model） | 时间序列由 `metric name` 与 key/value pairs（即 labels）标识 |
| 2 | `PromQL` | 灵活查询语言，用于充分利用该多维性 |
| 3 | 单节点自治 | 不依赖分布式存储，single server nodes are autonomous |
| 4 | Pull 模型采集 | 时间序列采集通过 HTTP 上的 **pull model** 完成 |
| 5 | 支持 Push | 通过中间网关（**push gateway**）支持推送时间序列 |
| 6 | 服务发现 | targets 通过 **service discovery** 或静态配置（static configuration）发现 |
| 7 | 多种可视化 | 支持多种绘图（graphing）与仪表盘（dashboarding）模式 |

**可靠性定位**：Prometheus 的设计目标是**可靠性**——它是故障时快速诊断的首选系统。每个 Prometheus server 都是独立的，不依赖网络存储或其他远程服务，因此即使基础设施的其他部分损坏，Prometheus 仍可依赖，而且无需搭建大量基础设施。

> 💡 补充（来自官方 FAQ）：Prometheus 的取舍是最看重“**可靠地把告警送达人类**”（reliably delivering alerts to humans）。这一点在第 1.4 节“何时不该用”中会看到其反面影响。

> 引自：[Overview](https://prometheus.io/docs/introduction/overview/)

### 1.4 适用场景：何时该用、何时不该用

#### 何时该用（When does it fit）

- **适合记录任何纯数值的时间序列**。
- 既适配**以机器为中心的监控**（machine-centric monitoring），也适配**高度动态的面向服务架构**（highly dynamic service-oriented architectures）。
- 在**微服务**场景下，多维数据采集与多维查询是显著优势。
- 需要**高可靠性、快速故障诊断**的场景——Prometheus server 独立自治，不依赖网络存储或远程服务。

#### 何时不该用（When does it not fit）

- Prometheus **重可靠性而非 100% 准确性**。
- 若需要 **100% 准确**（典型例子：**按请求计费 per-request billing**），**不适合**——因为采集的数据可能不够详尽、不够完整。
- 正确做法：**另用一个系统专门做计费数据采集**，Prometheus 负责其余监控。

#### 选择决策速查表

| 你的需求 | 是否适合 Prometheus | 说明 |
| --- | --- | --- |
| 记录纯数值时间序列 | ✅ 适合 | 核心用例 |
| 机器/主机监控 | ✅ 适合 | 配合 Node Exporter |
| 高度动态的云原生 / 微服务 | ✅ 适合 | 多维模型 + 服务发现 |
| 需要可靠的告警送达 | ✅ 适合 | 设计目标即“可靠地把告警送达人类” |
| 按请求计费（per-request billing） | ❌ 不适合 | 需 100% 准确，另建专用系统 |
| 日志/事件采集 | ❌ 不适合 | 见 FAQ：应改用 `Grafana Loki` 或 `OpenSearch` |
| 长期历史数据（超单节点容量） | ⚠️ 需外部方案 | 借助 remote write 到长期存储系统（如 Thanos 等） |

> 引自：[Overview](https://prometheus.io/docs/introduction/overview/) ｜ [Frequently asked questions](https://prometheus.io/docs/introduction/faq/)

### 1.5 竞品对比

本节基于官方 [Comparison to alternatives](https://prometheus.io/docs/introduction/comparison/) 页面整理，对比 Prometheus 与 Graphite、InfluxDB、OpenTSDB、Nagios、Sensu 等系统。

#### 1.5.1 总览对比表

| 维度 | Prometheus | Graphite | InfluxDB | OpenTSDB | Nagios | Sensu |
| --- | --- | --- | --- | --- | --- | --- |
| 类型 | 完整监控与告警系统 | 被动时序数据库 + 查询 + 绘图 | 开源时序数据库（有商用集群版） | 基于 Hadoop/HBase 的分布式时序库 | 基于脚本 exit code 的告警系统 | 开源可观测性 pipeline |
| 主动抓取 | ✅ 内置 | ❌ 交给外部组件 | ❌ 需外部 | ❌ 需外部 | 主动 check（脚本） | ✅ 事件驱动 |
| 查询语言 | `PromQL`（强，支持聚合/切片/预测/join） | 有查询语言（弱于 PromQL） | 有（弱于 PromQL） | API 仅支持简单聚合与数学运算 | ❌ 无查询语言 | 有限 |
| 多维标签 | ✅ labels（key-value，显式） | ❌ 点分 metric name 隐式编码 | ✅ 称 `tags`（另有 `fields`） | ✅ 称 `tags`（同 Prometheus labels） | ❌ 无 labels 概念 | ✅ labels/annotations |
| 告警/通知 | ✅ Alertmanager（分组、去重、静默、限流） | ❌ 交给外部 | 需搭配 `Kapacitor` | ❌ | ✅ 但无分组/路由/去重 | ✅ 事件处理强 |
| 存储 | 本地 TSDB（block + WAL），接受任意间隔样本 | `Whisper`（RRD 风格，要求固定间隔，过期覆盖） | 时间分片 LSM tree + WAL | Hadoop/HBase 之上 | 除当前状态外无存储 | 嵌入式 `etcd` 或外部 `PostgreSQL` |
| 水平扩展 | 单节点自治，超容量需按边界显式分片 | 集群方案更成熟适合长历史 | 商用版分布式集群，易水平扩展 | 易水平扩展（需运维 Hadoop/HBase） | 单 server，文件配置 | 组件可集群 |
| 开源模式 | 完全开源、独立项目 | 开源 | open-core（单一商业公司） | 开源 | 开源 | open-core（单一商业公司） |

#### 1.5.2 vs. Graphite

- **Scope（范围）**：Graphite 侧重做被动的时序数据库 + 查询语言 + 绘图，其他关注点交给外部组件。Prometheus 是**全套监控与趋势系统**，内置主动抓取、存储、查询、绘图、基于时序数据的告警；它知道“世界应是什么样”（哪些端点应存在、哪些时序模式意味着异常）并主动找故障。
- **Data model（数据模型）**：Graphite 存的是命名时序的数值样本。Graphite 用点分隔的 metric name **隐式编码维度**；Prometheus 则用显式的 key-value pairs（`labels`）附加于 metric name，便于按标签过滤、分组、匹配。Graphite 搭配 StatsD 时常只存所有实例的**聚合数据**，不保留 instance 维度，**无法下钻到具体问题实例**。

  编码示例对比：

  ```text
  # Graphite/StatsD 编码（仅一个聚合值，丢失实例维度）
  stats.api-server.tracks.post.500 -> 93
  ```

  ```text
  # Prometheus 编码（假设三个 api-server 实例，可下钻到实例）
  api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample1>"} -> 34
  api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample2>"} -> 28
  api_server_http_requests_total{method="POST",handler="/tracks",status="500",instance="<sample3>"} -> 31
  ```

- **Storage（存储）**：Graphite 用 `Whisper` 格式存本地磁盘，RRD 风格，**要求样本按固定间隔到达**；每个时序单独一个文件，过时后新样本覆盖旧样本。Prometheus 本地 TSDB 用**内存 head**（由 write-ahead log 保护）保存近期样本，再以**基于时间的 block 目录**持久化（含 chunks 目录、index 与 metadata），**接受任意间隔的样本**；保留期可配置，适合大量短生命周期、频繁变化的时序。
- **Summary**：Prometheus 数据模型与查询语言更丰富、更易运行集成；若需要**可长期持有历史数据的集群方案**，Graphite 可能更合适。

#### 1.5.3 vs. InfluxDB

- InfluxDB 是开源时序数据库，有商用扩展/集群选项；其项目**发布晚于 Prometheus 开发开始近一年**。公平比较需连同 `Kapacitor` 一起看（两者合计对应 Prometheus + Alertmanager 的问题域）。
- **功能对应关系**：

  | InfluxDB 侧能力 | Prometheus 侧对应 |
  | --- | --- |
  | InfluxDB continuous queries | Prometheus recording rules |
  | Kapacitor 全部范围 | Prometheus recording rules + alerting rules + Alertmanager 通知功能 |

  Prometheus 查询语言更强；Alertmanager 另有分组、去重、静默。
- **Data model / storage**：InfluxDB 的 labels 称 `tags`，另有二级 labels 称 `fields`（用途更受限）；支持最高**纳秒**分辨率时间戳，类型 float64、int64、bool、string。Prometheus 支持 **float64**（字符串支持有限）与**毫秒**分辨率时间戳。InfluxDB 用按时间分片的 log-structured merge tree + write ahead log，更适合事件日志；Prometheus 基于 block 的本地 TSDB **针对监控时序优化**。
- **Architecture**：Prometheus server 各自独立运行，核心功能（抓取、规则处理、告警）**仅依赖本地存储**；开源版 InfluxDB 类似。商用 InfluxDB 按设计是分布式存储集群（存储与查询由多节点处理），更易水平扩展但**需从一开始管理分布式存储复杂性**；Prometheus 更易运行，但超单节点容量后需按 scalability 边界（产品、服务、数据中心等）**显式分片**。独立 server（可并行冗余运行）带来更好可靠性与故障隔离。
- **Kapacitor**：开源版无内置 rules/alerting/notifications 的分布式/冗余选项，可由用户手动分片扩展；Influx 提供 Enterprise Kapacitor 支持 HA/冗余告警。Prometheus 与 Alertmanager 则通过**运行冗余 Prometheus 副本 + Alertmanager 高可用模式**，提供**完全开源**的冗余选项。
- **Summary**：
  - 相似处：都用 labels（InfluxDB 称 `tags`）支持多维指标；都用基本相同的数据压缩算法；都有广泛集成（包括互相）；都有扩展钩子。
  - InfluxDB 更优：做事件日志时；商用版聚类更适合长期数据存储；副本间最终一致视图。
  - Prometheus 更优：主要做 metrics 时；查询语言、告警、通知更强；绘图与告警的可用性与 uptime 更高。
  - 维护模式：InfluxDB 由单一商业公司按 open-core 模式维护（闭源聚类、托管、支持等增值功能）；Prometheus 是**完全开源独立项目**。

#### 1.5.4 vs. OpenTSDB

- 基于 `Hadoop` 与 `HBase` 的分布式时序数据库。Scope 差异同 Graphite 处。
- **Data model**：与 Prometheus **几乎相同**——时序由任意 key-value pairs 标识（OpenTSDB `tags` = Prometheus `labels`）。某 metric 的全部数据存于一起，**限制 metric 基数（cardinality）**。差异：Prometheus 允许 label value 使用任意字符，OpenTSDB 更受限；OpenTSDB **缺少完整查询语言**，API 仅支持简单聚合与数学运算。
- **Storage**：OpenTSDB 存储实现在 Hadoop/HBase 之上，易水平扩展，但需**从头接受运行 Hadoop/HBase 集群的复杂性**；Prometheus 初期更易运行，但超过单节点容量后需显式分片。
- **Summary**：Prometheus 查询语言丰富、可处理更高基数、是完整监控系统的一部分；若**已运行 Hadoop** 且更看重长期存储，OpenTSDB 是好选择。

#### 1.5.5 vs. Nagios

- 起源于 1990 年代（名为 **NetSaint**）。
- **Scope**：主要基于**脚本 exit codes** 告警，称为 "checks"；可静默单个告警，但**无分组、路由或去重**。插件生态丰富（如将 perfData 管道到 Graphite 等时序库，或用 `NRPE` 在远程机器执行 checks）。
- **Data model**：以 **host** 为基础，每 host 可含一个或多个 services，每 service 执行一个 check；**无 labels 概念，无查询语言**。
- **Storage**：除当前 check 状态外**无存储**；有插件可存储数据用于可视化。
- **Architecture**：Nagios server 独立；所有 check 配置通过文件。
- **Summary**：适合**小型/静态系统**的基础监控（blackbox probing 足够时）。若做 **whitebox monitoring** 或环境**动态/基于云**，选 Prometheus。

#### 1.5.6 vs. Sensu

- 开源监控与可观测性 pipeline，有商用发行版提供扩展性功能，**可复用现有 Nagios 插件**。
- **Scope**：是 observability pipeline，侧重把可观测性数据作为 `Events` 流处理与告警，提供可扩展框架用于 event filtering、aggregation、transformation、processing（含向其他系统发告警、把事件存到第三方系统）。其事件处理能力范围类似 **Prometheus alerting rules + Alertmanager**。
- **Data model**：Sensu `Events` 以结构化格式表示服务健康与/或 metrics，由 `entity` 名（如 server、云实例、container 或 service）、event name 及可选 key-value metadata（称 "labels" 或 "annotations"）标识。Event payload 可含一个或多个 metric `points`，以 JSON 对象表示，含 `name`、`tags`（key/value pairs）、`timestamp`、`value`（总是 float）。
- **Storage**：当前与近期事件状态信息及实时 inventory 存于嵌入式数据库（`etcd`）或外部 RDBMS（`PostgreSQL`）。
- **Architecture**：所有组件可集群，以实现高可用与更高事件处理吞吐。
- **Summary**：
  - 共同点：都有可扩展的动态云环境发现机制；都支持通过 labels/annotations 收集多维指标；都有广泛集成；Sensu 原生支持从所有 Prometheus exporters 收集指标；都可转发可观测性数据到第三方平台。
  - Sensu 更优：收集处理**混合**可观测性数据（metrics 与/或 events）；整合多监控工具且需支持 metrics 与 Nagios 风格插件/check 脚本；事件处理平台更强。
  - Prometheus 更优：主要**收集与评估 metrics**；监控**同构 Kubernetes 基础设施**（若 100% 工作负载在 K8s，Prometheus 的 K8s 集成更好）；查询语言更强且内置历史数据分析支持。
  - 维护模式：Sensu 由单一商业公司按 open-core 模式维护；Prometheus 是完全开源独立项目。

> 引自：[Comparison to alternatives](https://prometheus.io/docs/introduction/comparison/) ｜ [Frequently asked questions](https://prometheus.io/docs/introduction/faq/)

---

## 第 2 章 快速上手

### 2.1 环境要求

- Prometheus 使用 **`Go`** 编写，**只需对应操作系统的编译二进制**即可运行。
- 运行只需两样东西：**二进制 + 配置文件**（配置文件使用 **YAML** 格式）。
- 官方为多数 Prometheus 组件提供**预编译二进制**（precompiled binaries）。

> 💡 补充（工程经验，非官方原文）：Prometheus 官方只发布 Linux/macOS/Windows 的可执行文件，本身是静态编译的单一二进制，无需额外运行时依赖。生产环境建议运行在 Linux 服务器上，并为其预留独立的数据盘（TSDB 数据目录 `--storage.tsdb.path`，默认 `./data`）。

> 引自：[Installation](https://prometheus.io/docs/prometheus/latest/installation/) ｜ [Getting started with Prometheus](https://prometheus.io/docs/tutorials/getting_started/) ｜ [Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/)

### 2.2 下载与安装

官方 Installation 页面给出的安装方式逐条如下。

#### 2.2.1 方式一：预编译二进制

- 为多数官方 Prometheus 组件提供预编译二进制，版本列表见 <https://prometheus.io/download>。
- 下载后解包：

  ```bash
  tar xvfz prometheus-*.tar.gz
  cd prometheus-*
  ```

- 服务器为**单一二进制** `prometheus`（Windows 下为 `prometheus.exe`）。用 `--help` 查看所有选项：

  ```bash
  ./prometheus --help
  usage: prometheus [<flags>]

  The Prometheus monitoring server

  . . .
  ```

> 💡 补充（来自官方 Tutorials 教程）：也可下载后把二进制目录加入系统 `PATH`，之后即可直接以 `prometheus --config.file=prometheus.yml` 启动。

#### 2.2.2 方式二：从源码构建

- 见各仓库的 `Makefile` targets（例如 prometheus/prometheus 仓库）。

#### 2.2.3 方式三：Docker

- 所有 Prometheus 服务提供 Docker 镜像，位于 [Quay.io](https://quay.io/repository/prometheus/prometheus) 或 [Docker Hub](https://hub.docker.com/r/prom/prometheus/)。
- 最简启动（以示例配置启动并暴露 9090 端口）：

  ```bash
  docker run -p 9090:9090 prom/prometheus
  ```

- **镜像使用 volume 存储实际 metrics**。生产部署**强烈建议使用 named volume**，以便升级时管理数据。
- **命令行参数注意**：镜像以若干默认命令行参数启动（可在 Dockerfile 中查看）；若想追加参数，需**自行重新加上原有参数**，否则会被覆盖。

**挂载配置示例（二选一）**：

```bash
# 只挂载单个配置文件
docker run -p 9090:9090 -v /path/to/prometheus.yml:/etc/prometheus/prometheus.yml prom/prometheus

# 挂载整个配置目录
docker run -p 9090:9090 -v /path/to/config:/etc/prometheus prom/prometheus
```

**保存数据（持久化）**：数据存于容器内 `/prometheus` 目录，**容器重启即清空**；需设置持久化存储：

```bash
docker volume create prometheus-data
docker run -p 9090:9090 -v /path/to/prometheus.yml:/etc/prometheus/prometheus.yml -v prometheus-data:/prometheus prom/prometheus
```

**自定义镜像（把配置烤入镜像）**：

```Dockerfile
FROM prom/prometheus
ADD prometheus.yml /etc/prometheus/
```

```bash
docker build -t my-prometheus .
docker run -p 9090:9090 my-prometheus
```

- **更高级选项**：启动时用工具动态渲染配置，或由守护进程定期更新。

#### 2.2.4 方式四：配置管理系统（第三方贡献）

| 工具 | 项目地址 |
| --- | --- |
| Ansible | `prometheus-community/ansible` |
| Chef | `rayrod2030/chef-prometheus` |
| Puppet | `puppet/prometheus` |
| SaltStack | `saltstack-formulas/prometheus-formula` |

> 引自：[Installation](https://prometheus.io/docs/prometheus/latest/installation/)

### 2.3 5 分钟跑通

这一节把“下载 → 写配置 → 启动 → 首次查询 → 用 UI”串成一条最小可用路径，素材来自官方 [First steps with Prometheus](https://prometheus.io/docs/introduction/first_steps/)。

#### 2.3.1 配置文件详解

Prometheus 配置为 **YAML**，下载包自带示例配置 `prometheus.yml`，注释以 `#` 前缀。

```yaml
global:
  scrape_interval:     15s
  evaluation_interval: 15s

rule_files:
  # - "first.rules"
  # - "second.rules"

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ['localhost:9090']
```

配置由**三个配置块**组成：

| 配置块 | 作用 | 关键字段说明 |
| --- | --- | --- |
| `global` | 全局默认 | `scrape_interval` 控制抓取频率（本例 15 秒，可**按 target 单独覆盖**）；`evaluation_interval` 控制规则求值频率，规则用于创建新时间序列与生成告警 |
| `rule_files` | 规则文件位置 | 指定要加载的规则文件位置；示例中暂无规则 |
| `scrape_configs` | 监控哪些资源 | 默认单 job 名为 `prometheus`，抓取 Prometheus server 自身暴露的时间序列；含单个静态配置 target：`localhost` 的 `9090` 端口 |

- **默认抓取路径为 `/metrics`**，即完整 URL 为 <http://localhost:9090/metrics>。

#### 2.3.2 启动

```bash
./prometheus --config.file=prometheus.yml
```

启动后：

- 可在 <http://localhost:9090> 查看自身状态页；
- 约需 **30 秒**采集自身 HTTP 指标端点数据；
- 可在 <http://localhost:9090/metrics> 验证。

#### 2.3.3 首次查询（表达式浏览器）

访问 <http://localhost:9090/query>，选择 **"Table"** 标签页。

示例指标 `promhttp_metric_handler_requests_total`（Prometheus 自身已处理的 `/metrics` 请求总数）：

```promql
promhttp_metric_handler_requests_total
```

返回若干时间序列（各带最新值）：metric name 相同但 labels 不同，labels 用于标识不同请求状态。

只查看 HTTP `200`：

```promql
promhttp_metric_handler_requests_total{code="200"}
```

统计返回的时间序列数量：

```promql
count(promhttp_metric_handler_requests_total)
```

#### 2.3.4 UI 使用（绘图界面）

- 访问 <http://localhost:9090/query> 的 **"Graph"** 标签页。
- 示例（每秒 200 状态码请求速率）：

  ```promql
  rate(promhttp_metric_handler_requests_total{code="200"}[1m])
  ```

- 在 <http://localhost:9090/targets>（或 **Status → Target health**）查看各 target 健康状态。

#### 2.3.5 监控其他 target

- 建议参考其他 exporter 文档，起点为官方指南 **`Monitoring Linux or macOS host metrics using a node exporter`**（<https://prometheus.io/docs/guides/node-exporter/>）。

> 引自：[First steps with Prometheus](https://prometheus.io/docs/introduction/first_steps/)

### 2.4 官方 Hello World 教程完整步骤

本节按官方 [Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/)（核心文档中的 “Hello World” 式教程）的完整流程展开：下载并在本地运行 Prometheus，配置其抓取自身与一个示例应用，再通过查询、规则、图表使用采集到的时序数据。

#### 2.4.1 步骤 1：下载并解包

```bash
tar xvfz prometheus-*.tar.gz
cd prometheus-*
```

#### 2.4.2 步骤 2：编写自监控配置

保存为 `prometheus.yml`：

```yaml
global:
  scrape_interval:     15s # By default, scrape targets every 15 seconds.
  external_labels:
    monitor: 'codelab-monitor'
scrape_configs:
  - job_name: 'prometheus'
    scrape_interval: 5s
    static_configs:
      - targets: ['localhost:9090']
```

要点：`global.scrape_interval` 全局 15s；job 级 `scrape_interval: 5s` **覆盖**全局值；`external_labels` 添加 `monitor: 'codelab-monitor'`。

#### 2.4.3 步骤 3：启动

```bash
./prometheus --config.file=prometheus.yml
```

- 默认数据库存于 `./data`（flag `--storage.tsdb.path`）。
- 状态页：<http://localhost:9090>
- metrics 端点：<http://localhost:9090/metrics>

#### 2.4.4 步骤 4：用表达式浏览器探索数据

访问 <http://localhost:9090/query> 并选择 **"Graph"** 标签页：

```promql
prometheus_target_interval_length_seconds
```

```promql
prometheus_target_interval_length_seconds{quantile="0.99"}
```

```promql
count(prometheus_target_interval_length_seconds)
```

其中 `prometheus_target_interval_length_seconds` 表示 target 抓取之间的实际耗时。

绘图示例：

```promql
rate(prometheus_tsdb_head_chunks_created_total[1m])
```

#### 2.4.5 步骤 5：启动示例 target（Node Exporter）

```bash
tar -xzvf node_exporter-*.*.tar.gz
cd node_exporter-*.*
./node_exporter --web.listen-address 127.0.0.1:8080
./node_exporter --web.listen-address 127.0.0.1:8081
./node_exporter --web.listen-address 127.0.0.1:8082
```

#### 2.4.6 步骤 6：将多个端点归入一个 job 并分组

将三个端点归入一个名为 `node` 的 job，前两个为 production、第三个为 canary：

```yaml
scrape_configs:
  - job_name:       'node'
    scrape_interval: 5s
    static_configs:
      - targets: ['localhost:8080', 'localhost:8081']
        labels:
          group: 'production'
      - targets: ['localhost:8082']
        labels:
          group: 'canary'
```

在 <http://localhost:9090/targets> 或 **Status → Target health** 查看：三个端点状态应为 `UP`；若为 `DOWN`，检查对应端口上 Node Exporter 是否仍在运行。

示例返回序列：

```promql
node_cpu_seconds_total{cpu="0",group="production",instance="localhost:8080",job="node",mode="idle"}
```

在查询选项菜单（表达式输入框右侧三点按钮）→ **Explore metrics** 可浏览全部 metric name。

#### 2.4.7 步骤 7：定义 Recording rule

将表达式 `avg by (job, instance, mode) (rate(node_cpu_seconds_total[5m]))` 预录为 `job_instance_mode:node_cpu_seconds:avg_rate5m`，保存为 `prometheus.rules.yml`：

```yaml
groups:
- name: cpu-node
  rules:
  - record: job_instance_mode:node_cpu_seconds:avg_rate5m
    expr: avg by (job, instance, mode) (rate(node_cpu_seconds_total[5m]))
```

在 `prometheus.yml` 中：

- 加入 `rule_files: ['prometheus.rules.yml']`；
- 在 `global` 中加入 `evaluation_interval: 15s`（Evaluate rules every 15 seconds）。

#### 2.4.8 步骤 8：重载配置与优雅关闭

**重载配置（无需重启）**：发送 `SIGHUP` 信号。

```bash
kill -s SIGHUP <PID>
```

**优雅关闭**（推荐用信号/中断）：

- Linux 上发送 `SIGTERM` 或 `SIGINT`：

  ```bash
  kill -s <SIGNAL> <PID>
  ```

- 或在控制终端按中断字符（默认 `^C`）。

> 💡 补充（来自官方 FAQ）：除 `SIGHUP` 外，也可向 `/-/reload` 端点发 **HTTP POST** 重载配置；各组件会尽量**优雅处理失败的变更**。

> 引自：[Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/) ｜ [Frequently asked questions](https://prometheus.io/docs/introduction/faq/)

#### 2.4.9 Tutorials 版快速上手（含 node_exporter）

官方 [Tutorials → Getting started with Prometheus](https://prometheus.io/docs/tutorials/getting_started/) 给出了更精简的版本：

**第一步：只抓取自身。**

```yaml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]
```

含义：`scrape_interval` 定义抓取频率；`scrape_configs` 含 job 名称与抓取目标。Prometheus 默认监听 **9090** 端口，故把 `localhost:9090` 加入 targets。

启动：

```bash
prometheus --config.file=prometheus.yml
```

此时 Prometheus 已运行并**每 15s 抓取自身指标**。

**第二步：接入 node exporter。** 先运行 exporter（机器指标 exporter，下载：<https://prometheus.io/download/#node_exporter>）：

```bash
./node_exporter
```

再加入 `scrape_configs`：

```yaml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: prometheus
    static_configs:
      - targets: ["localhost:9090"]
  - job_name: node_exporter
    static_configs:
      - targets: ["localhost:9100"]
```

**抓取原理示例**：以 web server 为例，用 Prometheus client library 添加 instrumentation 代码暴露指标；配置 Prometheus 从该 web server（监听 IP 端口 7500）按固定间隔（如每分钟）抓取：

| Time Stamp | Request Count (metric) |
| --- | --- |
| 11:00:00 | 0 |
| 11:01:00 | 1 |
| 11:02:00 | 3 |

- 11:00:00 首次抓取 request count 存为 `0`；
- 11:01:00 处理 1 个请求，count 增至 `1`；
- 11:02:00 再处理 2 个请求，count = 1 + 2 = `3`。
- 抓取频率由用户控制。
- 备注：该表仅用于理解，**Prometheus 并非以此确切格式存储值**。

**查询 API**：Prometheus 提供 API 查询已抓取并存储的指标，用于查询指标、创建 dashboard/chart 等，使用 `PromQL`。

> 引自：[Getting started with Prometheus](https://prometheus.io/docs/tutorials/getting_started/)

### 2.5 验证安装成功

| 检查项 | 方法 | 预期结果 |
| --- | --- | --- |
| 进程已启动 | 访问 <http://localhost:9090> | 能看到自身状态页 |
| metrics 端点正常 | 访问 <http://localhost:9090/metrics> | 返回文本格式指标（约启动 30 秒后有数据） |
| 目标健康 | <http://localhost:9090/targets> 或 **Status → Target health** | `prometheus` target 状态为 `UP` |
| 查询可用 | <http://localhost:9090/query> 选 Table，执行 `promhttp_metric_handler_requests_total` | 返回带不同 labels 的多条时间序列 |
| 规则已加载（配置规则后） | <http://localhost:9090/rules> | 能看到已定义的 record/alert 规则 |
| 告警可查（接入 Alertmanager 后） | <http://localhost:9090/alerts> | 能看到告警及状态 |

> 引自：[First steps with Prometheus](https://prometheus.io/docs/introduction/first_steps/) ｜ [Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/)

### 2.6 常见启动问题

> 💡 补充：以下内容为基于官方文档各处的**工程实践提示**，官方未单列“常见启动问题”章节，故以排错清单形式给出。

| 现象 | 可能原因 | 排查方向 |
| --- | --- | --- |
| 状态页打不开 | 端口被占用 / 监听地址不对 | 检查 `--web.listen-address`（默认 `0.0.0.0:9090`）；用 `lsof -i :9090` 查占用 |
| target 状态 `DOWN` | 被监控进程未运行 / 端口错误 | 官方指引：检查对应端口上 exporter（如 Node Exporter）是否仍在运行 |
| 配置文件报错无法启动 | YAML 语法错误 / 字段拼写错误 | 用 `promtool check config prometheus.yml` 校验（见官方 promtool 文档） |
| 启动后查询无数据 | 抓取尚未完成 | 官方说明：约需 **30 秒**才开始采集到自身 HTTP 指标端点数据 |
| Docker 中数据丢失 | 数据存于容器内 `/prometheus`，容器重启即清空 | 使用 named volume：`-v prometheus-data:/prometheus` |
| Docker 中自定义参数不生效 | 镜像有默认命令行参数，追加参数会覆盖默认参数 | 需**自行重新加上**原有默认参数 |
| 配置改了不生效 | 未重载 | 发送 `SIGHUP`，或向 `/-/reload` 发 HTTP POST |
| 关闭时数据/状态异常 | 直接 kill 未优雅退出 | 使用 `SIGTERM`/`SIGINT` 优雅关闭 |

> 引自：[First steps with Prometheus](https://prometheus.io/docs/introduction/first_steps/) ｜ [Installation](https://prometheus.io/docs/prometheus/latest/installation/) ｜ [Getting started](https://prometheus.io/docs/prometheus/latest/getting_started/) ｜ [Frequently asked questions](https://prometheus.io/docs/introduction/faq/)

---

## 第 3 章 核心概念

### 3.1 数据模型详解

#### 3.1.1 时间序列（Time Series）

- Prometheus 把**所有数据**都存储为 **_time series_（时间序列）**：属于**同一 metric** 且**同一组 labeled dimensions** 的、带时间戳的值的流。
- 除已存储的序列外，Prometheus 还可能**因查询生成临时派生序列**。
- 每条时间序列由 **metric name** 和**可选的键值对 labels** 唯一标识。

#### 3.1.2 样本（Sample）

- 每个 **sample** 由两部分组成：

  | 组成 | 说明 |
  | --- | --- |
  | 值 | 一个 `float64` 值，或一个 **native histogram** 值 |
  | 时间戳 | **毫秒精度**时间戳 |

> 💡 补充（来自官方 FAQ 的 Implementation 一节）：之所以样本值都是 **64 位浮点**，是为了简化设计。`IEEE 754` 双精度二进制浮点格式支持整数精度至 **2^53**。原生 64 位整数仅在需要 2^53 以上、2^63 以下整数精度时才有帮助。原则上可实现不同样本值类型（含大整数，超过 64 位），但目前非优先。即便 counter 每秒递增一百万次，也需超过 **285 年**才会遇到精度问题。

#### 3.1.3 Metric name（指标名）

命名规则：

- **SHOULD** 描述被测量系统的通用特征（如 `http_requests_total` 表示收到的 HTTP 请求总数）；
- **MAY** 使用任意 UTF-8 字符；
- **SHOULD** 匹配正则 `[a-zA-Z_:][a-zA-Z0-9_:]*`，否则在 PromQL 中使用时需**加引号**；
- 冒号 `:` **保留给用户自定义 recording rules**，exporters 或直接插桩 **SHOULD NOT** 使用。

#### 3.1.4 Metric labels（指标标签）

- 用于捕获同一 metric name 的不同实例（如所有用 `POST` 方法访问 `/api/tracks` 的 HTTP 请求），这种模型称为 **"dimensional data model"（维度化数据模型）**。
- **任何 label 值变化（含增删 label）都会创建新的时间序列。**
- 命名规则：

  | 对象 | 规则 |
  | --- | --- |
  | label name | **MAY** 任意 UTF-8；以 `__`（双下划线）开头 **MUST** 保留给 Prometheus 内部使用；**SHOULD** 匹配 `[a-zA-Z_][a-zA-Z0-9_]*` |
  | label value | **MAY** 含任意 UTF-8 |
  | 空 label value | **等价于该 label 不存在** |

#### 3.1.5 命名规则速查表

| 对象 | SHOULD 匹配的正则 | 备注 |
| --- | --- | --- |
| metric name | `[a-zA-Z_:][a-zA-Z0-9_:]*` | `:` 保留给 recording rules；不匹配则 PromQL 中需加引号 |
| label name | `[a-zA-Z_][a-zA-Z0-9_]*` | `__` 前缀为 Prometheus 内部保留 |
| label value | 无字符集限制 | 可为任意 UTF-8；空值等于 label 不存在 |

#### 3.1.6 UTF-8 说明（重要警示）

> **WARNING**：metric/label name 的 UTF-8 支持在 **Prometheus v3.0.0** 才加入。生态（下游 PromQL 兼容项目、工具、第三方插桩、collectors）**可能尚未跟进**。为兼容性，建议沿用上文 **SHOULD** 字符集。

#### 3.1.7 Notation（记法）

标准记法：

```text
<metric name>{<label name>="<label value>", ...}
```

示例（与 OpenTSDB 记法相同）：

```text
api_http_requests_total{method="POST", handler="/messages"}
```

**UTF-8 字符（超出推荐集）需加引号**：

```text
{"<metric name>", <label name>="<label value>", ...}
```

因 metric name 内部表示为特殊 label `__name__`，也可写作：

```text
{__name__="<metric name>", <label name>="<label value>", ...}
```

> 引自：[Data model](https://prometheus.io/docs/concepts/data_model/) ｜ [Frequently asked questions](https://prometheus.io/docs/introduction/faq/)

### 3.2 四种指标类型

Prometheus 插桩库提供**四种核心 metric type**：**Counter、Gauge、Histogram、Summary**。

**关键前提**：除 **native histogram** 外，这些类型目前**只在插桩库 API 与 exposition 协议中区分**；**Prometheus server 尚不使用类型信息**，除 native histogram 外全部**扁平化为浮点值 untyped time series**。native histogram 则以特殊的**复合 histogram sample** 的时间序列被摄入。

#### 3.2.1 四种类型对比总表

| 类型 | 语义 | 单调性 | 典型用途 | 常用 PromQL |
| --- | --- | --- | --- | --- |
| **Counter** | 累积型（cumulative）、单调递增计数器 | 只增，重启时可重置为 0 | 请求数、完成任务数、错误数 | `rate()`、`increase()` |
| **Gauge** | 可任意上下浮动的单个数值 | 可升可降 | 温度、当前内存占用、并发请求数、队列中事件数、集群 pod 数 | `max_over_time`、`min_over_time`、`avg_over_time` |
| **Histogram** | 按可配置 buckets 对观测值计数 + 观测值之和（本质是 bucketed counter） | 累积 | 请求耗时（latency）、响应大小等分布 | `histogram_quantile()`、`histogram_fraction()`、`rate()` |
| **Summary** | 类似 histogram，另在滑动时间窗上计算可配置分位数 | 累积 | 请求时长、响应大小 | 直接读取 `{quantile="φ"}` |

#### 3.2.2 Counter（计数器）

- **是什么**：累积型（cumulative）metric，表示**只增不减**的单调递增计数器（monotonically increasing counter），值**只能在重启时被重置为 0**。
- **怎么用**：适合表示请求数、完成任务数、错误数。
- **不该用在哪**：**不可用于可能下降的值**（如当前运行进程数——应改用 gauge）。
- **注意**：`rate()` 函数**仅适用于 counter 值**。
- 教程中的示例查询：

  ```promql
  go_gc_duration_seconds_count
  ```

  `rate()` 取某时间窗内指标历史，计算每秒增长速度：

  ```promql
  rate(go_gc_duration_seconds_count[5m])
  ```

#### 3.2.3 Gauge（仪表盘）

- **是什么**：表示**可任意上下浮动**的单个数值。
- **怎么用**：用于温度、当前内存占用，或可升可降的“计数”如并发请求数。
- 教程中的示例查询：

  ```promql
  go_memstats_heap_alloc_bytes
  ```

  可用 PromQL 函数（作用于 gauge 指标）：`max_over_time`、`min_over_time`、`avg_over_time`。

#### 3.2.4 Histogram（直方图）

**是什么**：按**可配置的 buckets** 对观测值计数，并提供**所有观测值之和**，本质是 bucketed counter。它也可表示分布的当前状态，此时称为 **_gauge histogram_**（例如 `rate` 函数作用于 counter histogram 的结果）。

**版本分类**：histogram 有两种版本——较新的 **_native histograms_** 与较旧的 **_classic histograms_**。

**classic histogram 产生的序列**（base name 为 `<basename>`）：

| 序列 | 含义 |
| --- | --- |
| `<basename>_bucket{le="<upper inclusive bound>"}` | 观测 bucket 的**累积**计数器 |
| `<basename>_sum` | 所有观测值**总和** |
| `<basename>_count` | 观测事件**计数**（等同于 `<basename>_bucket{le="+Inf"}`） |

**native histogram 的优势**：

- 以 **composite samples** 暴露与摄入，每个 sample 表示观测的计数与总和，并带一组**动态 bucket**；
- 更高效、分辨率更高；
- 插桩时**无需显式配置 bucket 边界**；
- 网络传输（如 remote write）具备**原子性**（classic histogram 因各组成序列独立传输可能**部分传输**）；
- 其 bucketing schema **保证总可互相聚合**。

**支持情况**：当前支持 native histogram 的插桩库为 **Go 和 Java**，**建议优先使用 native histogram**。若只能用 classic，可配置 Prometheus 将其摄入为 **Native Histograms with Custom Bucket boundaries（NHCB）**——存储为相同 composite samples，但 bucket 布局与 classic 一致、分辨率与可聚合性受限。

**分位数计算**：用 `histogram_quantile()` 从 histogram（或 histogram 聚合）计算分位数，**classic 与 native 均适用**但语法略有不同；也可算 **Apdex score**。classic bucket 是**累积**的（每个 bucket 统计小于等于该 label 上界的所有观测）；native histogram 可用 `histogram_fraction()` 计算落在给定边界内的观测比例，并用 **trim operators** 过滤波段。

**教程中的分桶示例**：以“观察处理 API 请求耗时”为例。不存储每个请求的时间，而是分桶存储。定义耗时 bucket：`le 0.3`、`le 0.5`、`le 0.7`、`le 1`、`le 1.2`。请求耗时计算后，被加到**所有 bucket 边界高于该测量值**的 bucket 计数中。

- Request 1，端点 `/ping` 耗时 **0.25 s**：

  | Bucket | Count |
  | --- | --- |
  | 0 - 0.3 | 1 |
  | 0 - 0.5 | 1 |
  | 0 - 0.7 | 1 |
  | 0 - 1 | 1 |
  | 0 - 1.2 | 1 |
  | 0 - +Inf | 1 |

  备注：`+Inf` bucket 是**默认添加**的。由于 histogram 是累积频率（cumulative frequency），所有大于该值的 bucket 计数都加 1。

- Request 2，端点 `/ping` 耗时 **0.4 s**：

  | Bucket | Count |
  | --- | --- |
  | 0 - 0.3 | 1 |
  | 0 - 0.5 | 2 |
  | 0 - 0.7 | 2 |
  | 0 - 1 | 2 |
  | 0 - 1.2 | 2 |
  | 0 - +Inf | 2 |

  因为 0.4 低于 0.5，所有直到该边界的 bucket 计数增加。

**在 UI 中探索 histogram 指标**：

```promql
prometheus_http_request_duration_seconds_bucket{handler="/graph"}
```

`histogram_quantile()` 计算分位数：

```promql
histogram_quantile(0.9,prometheus_http_request_duration_seconds_bucket{handler="/graph"})
```

图中显示第 90 百分位数为 **0.09**。计算最近 **5m** 的 `histogram_quantile`，使用 `rate()` 与时间窗：

```promql
histogram_quantile(0.9, rate(prometheus_http_request_duration_seconds_bucket{handler="/graph"}[5m]))
```

> **NOTE**：自 **Prometheus v3.0** 起，classic histogram 的 `le` label 值在摄入时按 **OpenMetrics Canonical Numbers** 格式归一化。

#### 3.2.5 Summary（摘要）

- **是什么**：类似 histogram，采样观测值（通常是请求时长、响应大小），提供观测总数与所有观测值之和，并**在滑动时间窗口上计算可配置的分位数**。
- **暴露的序列**（base name 为 `<basename>`，在抓取时暴露多条序列）：

  | 序列 | 含义 |
  | --- | --- |
  | `<basename>{quantile="<φ>"}` | 流式 **φ-quantiles**（0 ≤ φ ≤ 1） |
  | `<basename>_sum` | 总和 |
  | `<basename>_count` | 计数 |

- **优缺点**：是 histogram 的替代方案；更省资源（cheaper）但**丢失更多数据**。**在应用层计算**，因此**无法聚合同一进程多个实例的指标**。
- **适用**：指标 bucket **事先未知**的场景；但**强烈建议尽可能优先使用 histograms 而非 summaries**。

> **NOTE**：自 **Prometheus v3.0** 起，`quantile` label 值在摄入时按 **OpenMetrics Canonical Numbers** 格式归一化。

#### 3.2.6 类型选型决策指南

| 你要测量的东西 | 推荐类型 | 理由 |
| --- | --- | --- |
| 请求数 / 错误数 / 完成任务数 | **Counter** | 只增不减，可配 `rate()` 看速率 |
| 当前进程数 / 并发数 / 温度 / 内存占用 | **Gauge** | 可升可降 |
| 请求耗时/响应大小的分布、需算分位数 | **Histogram（优先 native）** | 可跨实例聚合；native 无需预设桶、可原子传输 |
| bucket 边界事先未知、且无需跨实例聚合 | **Summary** | 应用层算分位数；但**优先选 histogram** |
| 已有的 classic histogram 不想改造 | 配置 **NHCB** | 摄入为 native 形态，但桶布局与 classic 一致 |

> 引自：[Metric types](https://prometheus.io/docs/concepts/metric_types/) ｜ [Understanding metric types](https://prometheus.io/docs/tutorials/understanding_metric_types/)

### 3.3 Jobs 与 Instances

#### 3.3.1 术语定义

- **_instance_（实例）**：可被抓取的 **endpoint**，通常对应**单个进程**。
- **_job_（作业）**：一组**用途相同**的 instance（例如为可扩展性或可靠性而复制的进程）。

**示例**：一个 `api-server` job 有四个复制 instance：

| instance | 地址 |
| --- | --- |
| instance 1 | `1.2.3.4:5670` |
| instance 2 | `1.2.3.4:5671` |
| instance 3 | `5.6.7.8:5670` |
| instance 4 | `5.6.7.8:5671` |

#### 3.3.2 自动附加的标签

抓取 target 时，Prometheus **自动附加两个 label** 用于标识被抓取 target：

| Label | 值 |
| --- | --- |
| `job` | target 所属的**已配置 job 名** |
| `instance` | 被抓取 target URL 的 **`<host>:<port>`** 部分 |

> 若被抓取的数据中**已存在**这两个 label，行为取决于配置项 `honor_labels`（详见 scrape_config 文档）。

#### 3.3.3 每次抓取自动写入的时间序列

每次 instance 抓取，Prometheus 会在以下时间序列中存一个 sample：

| 指标 | 含义 |
| --- | --- |
| `up{job="<job-name>", instance="<instance-id>"}` | 健康（可达）为 `1`，抓取失败为 `0`；**用于实例可用性监控** |
| `scrape_duration_seconds{job, instance}` | 抓取耗时 |
| `scrape_samples_post_metric_relabeling{job, instance}` | 应用 metric relabeling 后剩余的 sample 数 |
| `scrape_samples_scraped{job, instance}` | target 暴露的 sample 数 |
| `scrape_series_added{job, instance}` | 本次抓取新增序列的**近似**数量（*New in v2.10*） |

启用 [`extra-scrape-metrics` feature flag](https://prometheus.io/docs/prometheus/latest/feature_flags/#extra-scrape-metrics) 后**额外提供**：

| 指标 | 含义 |
| --- | --- |
| `scrape_timeout_seconds{job, instance}` | target 配置的 `scrape_timeout` |
| `scrape_sample_limit{job, instance}` | target 配置的 `sample_limit`；**未配置限制时返回 0** |
| `scrape_body_size_bytes{job, instance}` | 最近一次成功抓取响应的**未压缩**大小；因超出 `body_size_limit` 导致的抓取失败报 **-1**，其他抓取失败报 **0** |

> 引自：[Jobs and instances](https://prometheus.io/docs/concepts/jobs_instances/)

### 3.4 术语表

以下术语定义**逐条**来自官方 [Glossary](https://prometheus.io/docs/introduction/glossary/)。

| 术语 | 定义 |
| --- | --- |
| **Alert** | Prometheus 中告警规则的产物，且处于**正在触发（actively firing）**状态；告警从 Prometheus 发送到 Alertmanager。 |
| **Alertmanager** | 接收 alerts，**聚合成 groups**，**去重（de-duplicates）**，应用 **silences**，**限流（throttles）**，再向 email、Pagerduty、Slack 等发送通知。 |
| **Bridge** | 从 client library 取样本并**暴露给非 Prometheus 监控系统**的组件；例如 Python、Go、Java 客户端可导出指标到 Graphite。 |
| **Client library** | 某语言（如 Go、Java、Python、Ruby）的库，便于直接对代码埋点、编写自定义 collectors 从其他系统拉取指标并暴露给 Prometheus。 |
| **Collector** | exporter 中**代表一组指标**的部分；直接埋点时可能是单个指标，从其他系统拉取时可能是多个指标。 |
| **Direct instrumentation** | 作为程序源码**内联添加**的埋点，使用 client library。 |
| **Endpoint** | 可被抓取的**指标来源**，通常对应单个进程。 |
| **Exporter** | 与目标应用**并行运行**的二进制，暴露 Prometheus 指标，通常是**把非 Prometheus 格式的指标转换为 Prometheus 支持的格式**。 |
| **Instance** | 唯一标识 job 中某个 target 的 label。 |
| **Job** | 具有**相同目的**的一组 targets 的集合，例如监控为扩展性或可靠性而复制的同类进程组。 |
| **Mixin** | 面向特定组件或系统的**可复用、可扩展的 Prometheus alerts、recording rules 与 Grafana dashboards 集合**；通常用 `Jsonnet` 打包，可组合以构建完整监控配置，实现同类基础设施组件的标准化监控。 |
| **Notification** | 代表**一组一个或多个 alerts**，由 Alertmanager 发送至 email、Pagerduty、Slack 等。 |
| **Promdash** | 曾是 Prometheus 的**原生 dashboard builder，已弃用**，被 Grafana 取代。 |
| **Prometheus** | 通常指 Prometheus 系统的核心二进制；也可指整个 Prometheus 监控系统。 |
| **PromQL** | Prometheus Query Language，支持聚合、切片切块（slicing and dicing）、预测与 joins 等广泛操作。 |
| **Pushgateway** | **持久化 batch jobs 最近一次推送**的指标，使 Prometheus 可在其终止后再抓取这些指标。 |
| **Recording Rules** | **预计算**高频需要或计算昂贵的表达式，并把结果保存为**新的时间序列集合**。 |
| **Remote Read** | Prometheus 特性，允许在查询中**透明读取其他系统**（如长期存储）的时间序列。 |
| **Remote Read Adapter** | 并非所有系统直接支持 remote read；适配器位于 Prometheus 与另一系统之间，**转换双方的时间序列请求与响应**。 |
| **Remote Read Endpoint** | 做 remote read 时 Prometheus 通信的目标端点。 |
| **Remote Write** | Prometheus 特性，允许将摄入样本**实时发送到其他系统**（如长期存储）。 |
| **Remote Write Adapter** | 并非所有系统直接支持 remote write；适配器位于 Prometheus 与另一系统之间，**将 remote write 中的样本转换为对方可理解的格式**。 |
| **Remote Write Endpoint** | 做 remote write 时 Prometheus 通信的目标端点。 |
| **Sample** | 时间序列中某一时间点的**单个值**；在 Prometheus 中每个 sample 由一个 `float64` 值与**毫秒精度时间戳**组成。 |
| **Silence** | Alertmanager 中的**静默**，阻止 labels 匹配该 silence 的 alerts 进入通知。 |
| **Target** | 要抓取对象的**定义**，例如应用哪些 labels、连接所需认证信息，以及其他定义抓取如何发生的信息。 |
| **Time Series** | 属于**同一 metric 与同一组 labeled 维度**的时间戳值流；Prometheus 把所有数据都存为时间序列。 |

#### 术语分类速记

| 分类 | 术语 |
| --- | --- |
| 采集侧 | Target、Endpoint、Exporter、Collector、Bridge、Client library、Direct instrumentation、Instance、Job |
| 数据侧 | Time Series、Sample、Metric types（Counter/Gauge/Histogram/Summary）、PromQL |
| 告警侧 | Alert、Alertmanager、Notification、Silence、Recording Rules |
| 远程/扩展侧 | Remote Read / Remote Write（+ Adapter / Endpoint）、Pushgateway、Mixin、Promdash |

> 引自：[Glossary](https://prometheus.io/docs/introduction/glossary/)

---

## 第 4 章 架构与设计

### 4.1 设计哲学与动机

#### 4.1.1 设计文档入口（Design documents）

- 官方设计文档指向仓库 **`github.com/prometheus/proposals`**，其中可见 Prometheus 生态**过去与当前的全部提案（proposals）**。
- 若想创建新提案，阅读该仓库的 **`proposal process`**（<https://github.com/prometheus/proposals#proposal-process>）。

**Problem statements and exploratory documents（问题陈述与探索性文档）**：有时会看向更远的潜在未来。此节文档多为**探索性**，应作为“**影响集体思考**”之物，而非具体或确定内容。

| 探索性文档 | 初始日期 |
| --- | --- |
| `Prometheus is not feature complete` | 2020-05 |
| `Thoughts about timestamps and durations in PromQL` | 2020-10 |
| `Prometheus, OpenMetrics & OTLP` | 2021-03 |
| `Prometheus Sparse Histograms and PromQL` | 2021-10 |
| `Quoting Prometheus names` | 2023-01 |

（每项均链接到对应 Google Docs 文档。）

#### 4.1.2 核心设计动机

综合官方 Overview 与 FAQ，Prometheus 的设计动机可归纳为以下几点：

| 动机 | 具体体现 |
| --- | --- |
| **可靠性优先** | 作为故障时快速诊断的**首选系统**；每个 server 独立、不依赖网络存储或远程服务，基础设施其他部分损坏时仍可依赖；无需搭建大量基础设施 |
| **可靠地把告警送达人类** | 这是 Prometheus 最看重的取舍（出自 FAQ）；代价是放弃 100% 准确性 |
| **多维数据模型** | 显式 key-value labels，而非把维度隐式编码进 metric name；便于过滤、分组、匹配、下钻 |
| **单节点自治，易于运行** | 主 server 以单个单体二进制独立运行，无外部依赖；单实例可扩展至数千万活跃序列 |
| **Pull 优先** | HTTP pull 便于定位 target 是否 down、便于手动用浏览器检查健康；push 场景由 Pushgateway 兜底 |
| **面向动态环境** | service discovery 适配高度动态的云原生/微服务架构 |

**为什么选择 pull 而非 push**（官方 FAQ 的完整理由）：

| 理由 | 说明 |
| --- | --- |
| 灵活部署 | 可按需启动额外监控实例（如开发时在笔记本上） |
| 判断 down 更可靠 | 更易且更可靠地判断 target 是否 down |
| 便于人工排查 | 可手动用浏览器访问 target 检查健康 |

官方结论：整体上 pull 略优于 push，但**不应作为选型的主要原因**。必须 push 时，官方提供 **Pushgateway**。

> 💡 补充：Pull 模型的代价是“短生命周期任务”难以被抓到——这正是官方提供 Pushgateway 的原因（见术语表 Pushgateway）。

> 引自：[Design documents](https://prometheus.io/docs/introduction/design-doc/) ｜ [Overview](https://prometheus.io/docs/introduction/overview/) ｜ [Frequently asked questions](https://prometheus.io/docs/introduction/faq/)

### 4.2 整体架构与组件关系

#### 4.2.1 数据流架构

官方 Overview 对架构的描述如下：

- Prometheus 从**被埋点的 jobs** 抓取指标，**可直接抓取**；**短生命周期任务**则经中间 **push gateway**。
- 所有抓取样本**本地存储**，并在该数据上运行 **rules**——用于**聚合/记录新的时间序列**，或**生成告警**。
- 可用 **Grafana** 或其他 **API 消费者**可视化已采集的数据。
- 官方架构配图：`/assets/docs/architecture.svg`。

Tutorials 教程给出的基本架构组件（更精简的视角）：

| 组件 | 职责 |
| --- | --- |
| **Prometheus Server** | 抓取并存储指标数据的服务端 |
| **Targets to be scraped** | 被抓取目标，例如**暴露自身指标的 instrumented application**，或**暴露其他应用指标的 exporter** |
| **Alertmanager** | 基于预设规则触发告警 |
| （另有 `push_gateway`） | 该教程未涉及，见术语表与第 4.2.3 节 |

#### 4.2.2 组件清单（多数可选）

| 组件 | 仓库 / 说明 |
| --- | --- |
| 主 **Prometheus server** | `github.com/prometheus/prometheus`，抓取并存储时间序列数据 |
| **Client libraries** | 用于给应用代码**埋点** |
| **Pushgateway** | `github.com/prometheus/pushgateway`，支持**短生命周期任务（short-lived jobs）** |
| 专用 **Exporters** | 面向 HAProxy、StatsD、Graphite 等服务的指标导出器 |
| **Alertmanager** | `github.com/prometheus/alertmanager`，处理告警 |
| 各类支持工具 | — |

**实现语言**：多数组件用 **`Go`** 编写，便于以**静态二进制**构建与部署（部分组件用 Java、Python、Ruby，见 FAQ）。

#### 4.2.3 端到端数据流示意

```text
                        ┌──────────────────────────────┐
                        │      Prometheus Server        │
   ┌──────────┐  pull   │  ┌────────┐   ┌───────────┐  │
   │ 埋点应用  │ ◄───────┼──│ Scrape │──►│ 本地 TSDB  │  │
   │ /metrics │         │  └────────┘   └───────────┘  │
   └──────────┘         │        │            ▲        │
   ┌──────────┐  pull   │        ▼            │        │
   │ Exporter │ ◄───────┼──  Rules（recording / alerting）│
   └──────────┘         │        │                     │
   ┌──────────┐  push   │        ▼                     │
   │ 短生命周期│ ──────► │  ┌──────────────┐            │
   │   job    │ Pushgateway│ Alertmanager │            │
   └──────────┘         │  └──────┬───────┘            │
                        └─────────┼────────────────────┘
                                  ▼
                     email / PagerDuty / Slack / webhook ...
                        ▲
   ┌──────────┐  PromQL  │
   │ Grafana  │──────────┘ 或其它 API 消费者
   └──────────┘
```

> 💡 补充：上图为依据官方文字描述绘制的**示意关系图**，非官方原图；官方原图见 `/assets/docs/architecture.svg`。

> 引自：[Overview](https://prometheus.io/docs/introduction/overview/) ｜ [Getting started with Prometheus](https://prometheus.io/docs/tutorials/getting_started/)

### 4.3 Agent 模式（对比 Server 模式）

#### 4.3.1 是什么

**Prometheus Agent** 是内置于 Prometheus 二进制中的一种**运行模式**，具有与 server 模式**相同的 scraping APIs、语义、配置与发现机制**。该模式：

- **禁用** Prometheus 的一些常规功能：**TSDB、alerting、rule evaluations**；
- 将二进制**针对抓取与向远端 remote write 做优化**；
- 用一个**定制化的 TSDB WAL** 替代本地存储。

**Remote Write 的角色**：Prometheus Remote Write 协议把 Prometheus 采集到的**全部或子集** metrics **转发（流式）**到远端位置；你可以配置 Prometheus 把部分指标（如需，还可包含**全部 metadata 和 exemplars**）转发到一个或多个支持 Remote Write API 的位置。

**为什么用 Pull + Remote Write**：即便使用 Remote Write，Prometheus 仍用 **pull 模型**从应用采集指标，从而**理解这些不同的失败模式**。之后再把 samples 与 series 批量导出、复制（push）到 Remote Write endpoints，**限制中心侧“监控未知量”的数量**。

**Global View 用例**：从这样的 scraper 流式发送数据，使得把指标数据集中存于一处成为可能，从而支持 **Global View** 用例，实现**关注点分离**——当管理应用的团队与负责可观测性/监控 pipeline 的团队不同时尤为有用。

**本质**：Agent 模式为 remote write 用例优化 Prometheus，**禁用查询、告警与本地存储**，代之以定制 TSDB WAL。**其余全部相同**：scraping 逻辑、service discovery 与相关配置。如果你只想把数据转发到远端 Prometheus server 或任何兼容 Remote-Write 的项目，它可**作为 Prometheus 的 drop-in replacement（直接替换）**。

官方配图：`./images/prometheus_agent.png`。

#### 4.3.2 Server 模式 vs Agent 模式对比

| 维度 | Server 模式（默认） | Agent 模式 |
| --- | --- | --- |
| 本地查询 | ✅ 支持 | ❌ **不支持**（无法查询本地实例） |
| Recording rules | ✅ 支持 | ❌ **不支持**（规则必须在远端做） |
| 告警（Alerting） | ✅ 支持 | ❌ **不支持**（全部告警由远端系统完成） |
| 本地存储 | 完整 TSDB | 定制 TSDB WAL（成功后立即删除数据） |
| Scraping / SD / 配置 | ✅ | ✅ **完全相同** |
| Remote Write | ✅ | ✅ 核心用途 |
| Web UI 端口 | 9090 | **9095**（禁用查询能力，但展示 build info、configuration、targets、service discovery 信息） |
| 资源占用 | 常规 | **约为常规 server 的一小部分** |
| 存储路径 flag | `--storage.tsdb.path`（默认 `data/`，仅 server 模式） | `--storage.agent.path`（默认 `data-agent/`，仅 agent 模式） |

#### 4.3.3 Agent 模式的收益（Benefits）

| 收益 | 说明 |
| --- | --- |
| **更高效率** | 定制的 Agent TSDB WAL 在写入成功后**立即移除数据**。若无法到达远端 endpoint，则**临时持久化到磁盘**，直到远端恢复。目前**仅限两小时缓冲**，与非 agent 版 Prometheus 类似。这意味着**无需在内存中构建 chunks、也无需维护用于查询的完整 index**；Agent 模式使用的资源只是常规 Prometheus server 在类似情形下的**一小部分** |
| **更易水平扩展摄入** | Agent 模式使**摄取的水平扩展（horizontal scalability for ingestion）**更简单（见官方博客《The dream: auto-scalable metric ingestion》） |

#### 4.3.4 Agent 模式的代价（Downsides）

- **No local queries**：你无法查询本地 Prometheus 实例。
- **Recording rules are not possible**：无法为发送到 remote write 的数据做预聚合总结；规则必须在远端完成。
- **No alerting**：全部告警都必须由远端系统完成。

#### 4.3.5 怎么用

用 **`--agent`** flag 运行 Agent 模式。`--help` 输出中可见相关 flag：

```text
usage: prometheus [<flags>]

The Prometheus monitoring server

Flags:
  -h, --help                     Show context-sensitive help (also try --help-long and --help-man).
      (... other flags)
      --storage.tsdb.path="data/"
                                 Base path for metrics storage. Use with server mode only.
      --storage.agent.path="data-agent/"
                                 Base path for metrics storage. Use with agent mode only.
      (... other flags)
      --[no-]agent               Run Prometheus in 'Agent mode'.
```

**如何判断某 flag 属于哪个模式**：其余 flag 要么两类模式共用，要么只属于某一模式。看该 flag 帮助字符串的**最后一句**即可：“Use with server mode only” 表示仅 server 模式；**若没有任何此类说明，则该 flag 是共用的**。

Agent 模式**接受相同的 scrape 配置**（含相同的 discovery 选项与 remote write 选项），并暴露 **9095 端口**的 Web UI——禁用查询能力，但展示 build info、configuration、targets 与 service discovery 信息，与常规 Prometheus server 一致。

> 引自：[Prometheus Agent Mode](https://prometheus.io/docs/prometheus/latest/prometheus_agent/)

### 4.4 API 稳定性承诺

Prometheus **承诺在一个主版本内保持 API 稳定**，并努力避免对关键特性做破坏性变更。部分特性（纯装饰性的、仍在开发中的、或依赖第三方服务的）**不在此承诺范围内**。

#### 4.4.1 3.x 中被视为稳定的内容（Stable for 3.x）

| # | 稳定项 |
| --- | --- |
| 1 | 查询语言与数据模型（The query language and data model） |
| 2 | 告警与 recording 规则（Alerting and recording rules） |
| 3 | 摄入的 exposition 格式（The ingestion exposition format） |
| 4 | v1 HTTP API（被 dashboards 与 UIs 使用），**不含显式标记为 experimental 的 endpoint** |
| 5 | 配置文件格式（减去 service discovery 的 remote read/write，见下） |
| 6 | 规则/告警文件格式（Rule/alert file format） |
| 7 | Console template 语法与语义 |
| 8 | Remote write 发送（依据 [1.0 规范](https://prometheus.io/docs/concepts/remote_write_spec/)）与接收 |
| 9 | Agent 模式 |
| 10 | OTLP receiver endpoint |

#### 4.4.2 3.x 中被视为不稳定的内容（Unstable for 3.x）

任何被标记为 **experimental 或 subject to change** 的特性，包括：

- `double_exponential_smoothing` PromQL 函数（见 <https://github.com/prometheus/prometheus/issues/2458>）；
- Remote read 与 remote read endpoint；
- Server-side HTTPS 与 basic authentication；
- Service discovery 集成，**例外**为 `static_configs`、`file_sd_configs` 和 `http_sd_config`；
- 属于 server 一部分的包的 **Go APIs**；
- Web UI 生成的 **HTML**；
- Prometheus 自身 `/metrics` endpoint 中的 **metrics**；
- 精确的**磁盘格式**（on-disk format）——潜在变更将**向前兼容**并由 Prometheus 透明处理；
- **日志格式**（The format of the logs）。

#### 4.4.3 升级含义

- Prometheus 2.x 的稳定性保证见 [2.x 文档](https://prometheus.io/docs/prometheus/2.55/stability/)。
- 只要你**不使用**标记为 experimental/unstable 的特性，**在同一主版本内升级通常无需任何运维调整**，破坏风险极低。
- 任何破坏性变更都会在 release notes 中标记为 **`CHANGE`**。

#### 4.4.4 稳定性等级速查

| 等级 | 含义 | 典型对象 |
| --- | --- | --- |
| **Stable** | 主版本内保证稳定 | 查询语言、数据模型、规则格式、v1 HTTP API（非 experimental）、exposition 格式、remote write 1.0、Agent 模式、OTLP receiver |
| **Experimental / Unstable** | 可能随时变更，**不提供稳定保证** | `double_exponential_smoothing`、remote read、server-side HTTPS/basic auth、多数 SD 集成、Go APIs、Web UI HTML、自身 `/metrics`、磁盘格式、日志格式 |

> 💡 补充：LTS 支持范围明确**排除**了上述不稳定特性（Unstable features）、实验性特性（Experimental features，见 feature_flags）以及 OpenBSD 支持。详见第 5.2 节。

> 引自：[API stability guarantees](https://prometheus.io/docs/prometheus/latest/stability/) ｜ [Long-term support](https://prometheus.io/docs/introduction/release-cycle/)

---

## 第 5 章 生态与版本

### 5.1 路线图

官方 [Roadmap](https://prometheus.io/docs/introduction/roadmap/) 说明：以下仅为**近期计划实现的部分主要特性**；更完整的计划与当前工作见各仓库 issue tracker（如 Prometheus server）。

| 计划特性 | 说明 |
| --- | --- |
| **Server-side metric metadata support** | 目前 metric types 及其他 metadata **仅在 client libraries 与 exposition format 中使用**，未在 Prometheus server 持久化或利用。计划未来利用这些 metadata；**第一步**是在 Prometheus **内存中聚合**该数据，并通过**实验性 API 端点**提供 |
| **Adopt OpenMetrics** | OpenMetrics 工作组正在制定**新的指标暴露标准**；计划在 client libraries 与 Prometheus 自身支持该格式 |
| **Retroactive rule evaluations** | 增加对**回溯规则求值**的支持，利用 **backfill** |
| **TLS and authentication in HTTP serving endpoints** | TLS 与认证正逐步推广到 Prometheus、Alertmanager 与官方 exporters；该支持可让用户**安全部署 Prometheus 组件而无需反向代理**提供外部附加这些能力 |
| **Support the Ecosystem** | Prometheus 有一系列 client libraries 与 exporters，总有更多语言可支持、更多系统值得导出指标；将持续支持生态创建与扩展这些 |

> 引自：[Roadmap](https://prometheus.io/docs/introduction/roadmap/)

### 5.2 发布周期与 LTS 策略

#### 5.2.1 LTS 定义

**Prometheus LTS（Long-term support）** 是经挑选的发布版本，在**一年**延长期内接收经过挑选的 bug 修复。

#### 5.2.2 发布节奏

- 每 **6 周**开启一个新的 minor release 周期；
- **6 周后**，某个 minor release **通常不再接收 bug 修复**；
- 因此，用户受某 minor release 的 bug 影响时，**往往需升级到最新 Prometheus release**。

#### 5.2.3 升级

- 得益于 **API 稳定性保证**，升级通常**直接简单**；
- 但**新特性与增强也可能带来回归**，从而需要再次升级。

#### 5.2.4 支持范围

| 项 | 规则 |
| --- | --- |
| 修复级别 | LTS 版本**仅接收高严重度问题**的修复，即 **CVSS 评分 7.0 或更高** |
| 可追加 | 可能追加 bug 修复或文档修复 |
| 工具链 | 构建工具链也会**保持最新** |
| 承诺性质 | 此承诺为**社区尽力而为（best effort）**，欢迎贡献 |

#### 5.2.5 支持周期重叠

- 两个相邻 LTS 版本的**支持期应至少重叠一个月**；
- 目的：使依赖 Prometheus 的用户**既限制升级风险，又有社区维护的 server**。

#### 5.2.6 LTS 发布列表

- LTS 发布列表由占位符 `<!-- LTS_RELEASES_TABLE -->` **动态生成**（源文件中无具体版本数据）。

#### 5.2.7 LTS 支持的排除项（Limitations）

LTS 支持**不覆盖**：

| 排除项 | 说明 |
| --- | --- |
| API 稳定性保证中列出的**不稳定特性**（Unstable features） | 见第 4.4.2 节 |
| **实验性特性**（Experimental features） | 见 feature_flags |
| **OpenBSD 支持** | — |

**参考链接**：

- API 稳定性：<https://prometheus.io/docs/prometheus/latest/stability/>
- 特性开关：<https://prometheus.io/docs/prometheus/latest/feature_flags/>

> 引自：[Long-term support](https://prometheus.io/docs/introduction/release-cycle/) ｜ [API stability guarantees](https://prometheus.io/docs/prometheus/latest/stability/)

### 5.3 学习资源

官方 [Media](https://prometheus.io/docs/introduction/media/) 页面汇总的学习资源如下。

#### 5.3.1 社区与聚合资源

| 资源 | 说明 |
| --- | --- |
| 专门 subreddit | <https://reddit.com/r/prometheusmonitoring>，汇集全网 Prometheus 相关资源 |
| `Awesome Prometheus` | <https://github.com/roaldnefs/awesome-prometheus>，更全面的社区维护资源列表 |

#### 5.3.2 Blogs

- 本站 blog（<https://prometheus.io/blog/>）；
- **SoundCloud 宣布 Prometheus 的博文**（比本站更详尽）；
- **Robust Perception** 博客的 Prometheus 相关文章。

#### 5.3.3 Tutorials

- **Prometheus workshop** 的说明与示例代码（<https://github.com/juliusv/prometheus_workshop>）；
- **How To Install Prometheus using Docker on Ubuntu 14.04**（DigitalOcean）。

#### 5.3.4 Podcasts and interviews

- `Prometheus on FLOSS Weekly 357`（Julius Volz）；
- `Prometheus and Service Monitoring`（Changelog podcast，Julius Volz）。

#### 5.3.5 Recorded talks

| 主题 | 讲者 / 场合 |
| --- | --- |
| `Prometheus: A Next-Generation Monitoring System` | Julius Volz 与 Björn Rabenstein，SREcon15 Europe, Dublin |
| 同名演讲 | Brian Brazil，FOSDEM 2016 |
| `What is your application doing right now?` | Matthias Gruter, Transmode |
| `Prometheus workshop` | Jamie Wilkinson，Monitorama PDX 2015 |
| `Monitoring Hadoop with Prometheus` | Brian Brazil |
| `Monitoring mit Prometheus`（德语） | Michael Stapelberg, Easterhegg 2016 |
| `Prometheus in der Praxis`（德语） | Jonas Große Sundrup, MRMCD 2016 |

#### 5.3.6 Presentation slides

| 分组 | 标题 / 讲者 |
| --- | --- |
| General | `Prometheus Overview`（Brian Brazil） |
| General | `Systems Monitoring with Prometheus`（Brian Brazil，Devops Ireland Meetup） |
| General | `OMG! Prometheus`（Benjamin Staffin, Fitbit Site Operations） |
| Docker | `Prometheus and Docker`（Brian Brazil，Docker Galway） |
| Python | `Better Monitoring for Python`（Brian Brazil，Pycon Ireland） |
| Python | `Monitoring your Python with Prometheus`（Brian Brazil，Python Ireland Meetup） |

> 引自：[Media](https://prometheus.io/docs/introduction/media/)

### 5.4 官方 FAQ 整理

以下按官方 [Frequently asked questions](https://prometheus.io/docs/introduction/faq/) 的三大分组（**General / Instrumentation / Implementation**）逐条整理，采用“**问题（现象）→ 解答**”的形式。

#### 5.4.1 General（通用）

**Q：什么是 Prometheus？**
A：开源系统监控与告警工具箱，生态活跃；是 `Kubernetes` 唯一直接支持的系统，也是云原生生态事实标准。

**Q：与其他监控系统如何比较？**
A：见 [comparison 页](https://prometheus.io/docs/introduction/comparison/)（本篇第 1.5 节已完整整理）。

**Q：依赖什么？是否云原生？**
A：

- 主 server 以**单个单体二进制**独立运行，**无外部依赖**；
- 是云原生；
- 服务发现集成多数工具与云；
- 多维数据模型**可扩展至数千万活跃序列（tens of millions of active series）**，可监控大型云原生部署；
- 取舍上，Prometheus 最看重“**可靠地把告警送达人类**”。

**Q：是否支持高可用（High availability）？**
A：是。在两台或多台**独立机器**上运行**完全相同的** Prometheus server。`Thanos` 等系统可去重，许多支持 remote write 的外部系统也能去重；完全相同的告警会由 **Alertmanager 去重**；Alertmanager 通过**互联多个实例构成集群**支持高可用。

**Q：“Prometheus 不扩展”（Prometheus doesn't scale）？**
A：常属**营销说法**。单实例可优于某些自称长期存储的方案；可靠运行**数千万活跃序列**没问题。若需更多，可参考 **Scaling and Federating Prometheus** 博客与 integrations 页的长期存储系统。

**Q：用什么语言写的？**
A：多数组件用 `Go`，部分用 Java、Python、Ruby。

**Q：稳定性承诺如何？**
A：

- GitHub org 中达 **1.0.0 的仓库**大体遵循**语义化版本（semantic versioning）**，破坏性变更以**主版本递增**表示；**实验性组件例外**，会在公告中明确标注；
- **未达 1.0.0 的仓库**通常也相当稳定；
- 破坏性变更会在 release notes 标注 **`[CHANGE]`**；无正式发布的组件会明确沟通。

**Q：为什么用 pull 而非 push？**
A：HTTP pull 的优势——① 可按需启动额外监控实例（如开发时在笔记本上）；② 更易且更可靠地判断 target 是否 down；③ 可手动用浏览器访问 target 检查健康。整体上 pull 略优于 push，但**不应作为选型主要原因**。必须 push 时提供 **Pushgateway**。

**Q：如何把日志喂给 Prometheus？**
A：

- **短答**——别这么做，改用 `Grafana Loki` 或 `OpenSearch`；
- **长答**——Prometheus 收集处理 **metrics**，**不是事件日志系统**；若想从应用日志提取 Prometheus 指标，**Loki 正是为此设计**（见其 metric queries 文档）。

**Q：作者是谁？**
A：最初由 `Matt T. Proud` 与 `Julius Volz` **私下发起**，主要初期开发由 `SoundCloud` 资助；现由众多公司与个人维护扩展。

**Q：许可证？**
A：`Apache 2.0`。

**Q：Prometheus 的复数形式？**
A：经研究确定为 **'Prometheis'**；记不住时可用 "Prometheus instances"。

**Q：能否重载配置？**
A：可以。向进程发送 `SIGHUP`，或向 **`/-/reload`** 端点发 HTTP POST，即可重载并应用配置；各组件会**尽量优雅处理失败的变更**。

**Q：能否发送告警？**
A：可以，用 **Alertmanager**；支持 email、多种原生集成，以及任何人都可添加集成的 **webhook** 系统。

**Q：能否创建仪表盘？**
A：可以，生产环境**推荐 Grafana**；也有 **Console templates**。

**Q：能否改时区？为何全用 UTC？**
A：为避免**时区混淆**（尤其涉及 daylight saving time，夏令时），内部**独占使用 Unix time**，所有组件**展示用 UTC**。UI 时区选择需谨慎设计，欢迎贡献（见 issue #500）。

#### 5.4.2 Instrumentation（埋点）

**Q：哪些语言有埋点库？**
A：有多种 client libraries，详见文档；想为新语言贡献客户端，见 exposition formats。

**Q：能否监控机器？**
A：可以。**`Node Exporter`** 在 Linux 及其他 Unix 系统暴露大量机器级指标，如 CPU 使用率、内存、磁盘利用率、文件系统占用、网络带宽。

**Q：能否监控网络设备？**
A：可以。**`SNMP Exporter`** 支持 SNMP 设备；工业网络还有 **`Modbus exporter`**。

**Q：能否监控 batch jobs？**
A：可以，用 **Pushgateway**；另见 batch jobs 最佳实践。

**Q：开箱即用可监控哪些应用？**
A：见 **exporters and integrations** 列表。

**Q：能否通过 JMX 监控 JVM 应用？**
A：可以。对无法直接用 Java client 埋点的应用，可用 **`JMX Exporter`**，**独立运行或作为 Java Agent**。

**Q：埋点的性能影响有多大？**
A：各客户端与语言不一。**Java 基准显示**：Java client 递增 counter/gauge 需 **`12-17ns`**（取决于竞争）；除对延迟极敏感的代码外**可忽略**。

#### 5.4.3 Implementation（实现）

**Q：为何样本值都是 64 位浮点？**

A：

- 为**简化设计**限定为 64 位浮点；
- `IEEE 754` 双精度二进制浮点格式支持**整数精度至 2^53**；
- **原生 64 位整数**仅在需要 **2^53 以上、2^63 以下**整数精度时才有帮助；
- 原则上可实现不同样本值类型（含大整数，超过 64 位），但**目前非优先**；
- 即便 counter **每秒递增一百万次**，也需超过 **285 年**才会遇到精度问题。

#### 5.4.4 FAQ 速查索引

| 分组 | 问题 | 一句话结论 |
| --- | --- | --- |
| General | 什么是 Prometheus | 开源监控与告警工具箱，云原生事实标准 |
| General | 依赖 / 云原生 | 单体二进制、无外部依赖、云原生 |
| General | 高可用 | 多台独立机器跑相同 server + Alertmanager 集群去重 |
| General | 不扩展？ | 营销说法；单实例可跑数千万活跃序列 |
| General | pull vs push | pull 略优，但不作为选型主因；需 push 用 Pushgateway |
| General | 日志 | 别喂日志，用 Grafana Loki 或 OpenSearch |
| General | 许可证 | Apache 2.0 |
| General | 重载配置 | `SIGHUP` 或 POST `/-/reload` |
| General | 时区 | 内部 Unix time，展示统一 UTC |
| Instrumentation | 监控机器 | Node Exporter |
| Instrumentation | 网络设备 | SNMP Exporter / Modbus exporter |
| Instrumentation | batch jobs | Pushgateway |
| Instrumentation | JVM | JMX Exporter（独立或 Java Agent） |
| Instrumentation | 埋点开销 | Java 约 12-17ns，通常可忽略 |
| Implementation | 为何 64 位浮点 | 简化设计；2^53 内整数精确；极端场景 285 年才出问题 |

> 引自：[Frequently asked questions](https://prometheus.io/docs/introduction/faq/)

---

## 附录：本篇覆盖清单

本篇内容来源与章节对照表（“无正文（导航页）”的小节不产出正文，仅在此备案）。

| # | 官网页面 URL | 页面标题 | 类目 | 对应本篇章节目 |
| --- | --- | --- | --- | --- |
| 1 | <https://prometheus.io/docs/introduction/overview/> | Overview | docs | 1.1 / 1.3 / 1.4 / 4.2 |
| 2 | <https://prometheus.io/docs/introduction/first_steps/> | First steps with Prometheus | docs | 2.3 / 2.5 / 2.6 |
| 3 | <https://prometheus.io/docs/introduction/index/> | Introduction | docs | —（导航页，无正文） |
| 4 | <https://prometheus.io/docs/introduction/glossary/> | Glossary | docs | 3.4 |
| 5 | <https://prometheus.io/docs/introduction/faq/> | Frequently asked questions | docs | 5.4（并散见于 1.1 / 2.6 / 3.1 / 4.1） |
| 6 | <https://prometheus.io/docs/introduction/comparison/> | Comparison to alternatives | docs | 1.5 |
| 7 | <https://prometheus.io/docs/introduction/roadmap/> | Roadmap | docs | 5.1 |
| 8 | <https://prometheus.io/docs/introduction/release-cycle/> | Long-term support | docs | 5.2 / 4.4.4 |
| 9 | <https://prometheus.io/docs/introduction/media/> | Media | docs | 5.3 |
| 10 | <https://prometheus.io/docs/introduction/design-doc/> | Design documents | docs | 4.1 |
| 11 | <https://prometheus.io/docs/concepts/data_model/> | Data model | docs | 3.1 |
| 12 | <https://prometheus.io/docs/concepts/metric_types/> | Metric types | docs | 3.2 |
| 13 | <https://prometheus.io/docs/concepts/jobs_instances/> | Jobs and instances | docs | 3.3 |
| 14 | <https://prometheus.io/docs/concepts/index/> | Concepts | docs | —（导航页，无正文） |
| 15 | <https://prometheus.io/docs/prometheus/latest/getting_started/> | Getting started | core | 2.4 / 2.5 / 2.6 |
| 16 | <https://prometheus.io/docs/prometheus/latest/installation/> | Installation | core | 2.1 / 2.2 / 2.6 |
| 17 | <https://prometheus.io/docs/prometheus/> | Prometheus（server 文档入口） | core | —（导航页，无正文） |
| 18 | <https://prometheus.io/docs/prometheus/latest/prometheus_agent/> | Prometheus Agent Mode | core | 4.3 |
| 19 | <https://prometheus.io/docs/prometheus/latest/stability/> | API stability guarantees | core | 4.4 / 5.2.7 |
| 20 | <https://prometheus.io/docs/tutorials/getting_started/> | Getting started with Prometheus | docs | 1.1 / 2.1 / 2.4.9 / 4.2.1 |
| 21 | <https://prometheus.io/docs/tutorials/understanding_metric_types/> | Understanding metric types | docs | 3.2 |
| 22 | <https://prometheus.io/docs/tutorials/> | Tutorials | docs | —（导航页，无正文） |
| 23 | <https://prometheus.io/docs/guides/> | Guides | docs | —（导航页，无正文） |
| 24 | <https://prometheus.io/docs/alerting/> | Alertmanager | docs | —（导航页，无正文） |

**说明**：

- 第 18、19 项（Agent Mode、API stability）为完成本篇第 4 章所需的补充素材，直接取自 `handbook-src/raw/core/prometheus_agent.md` 与 `handbook-src/raw/core/stability.md`。
- 第 3、14、17、22、23、24 项以及 batch 中的 `Concepts`、`Tutorials`、`Guides`、`Prometheus Server`、`Alertmanager` 索引页均为**导航/落地页，正文为空**，无概念、命令、配置项或示例可提炼，故不产出正文内容。

---

> **第 1 篇结束。** 下一篇《第 2 篇：PromQL 与查询》将展开查询基础、操作符、查询函数、示例、HTTP API 与 Remote Read API。