简介《普罗米修斯手册普罗米修斯中文文档》是一套面向云原生监控场景的Prometheus中文参考指南适合Kubernetes运维、微服务开发者及SRE人员阅读。内容从时间序列数据库与监控系统的基本概念讲起逐步拆解Server、Exporter、Pushgateway、Alertmanager四大组件的分工说明基于YAML的目标定义、数据保留与警报规则配置并介绍在Kubernetes中使用Helm部署及ServiceMonitor自动发现服务的具体方式。PromQL部分重点讲解常用查询语法例如利用sum(rate(http_requests_total[5m]))统计请求速率帮助读者掌握指标聚合与告警设置同时覆盖静态配置、DNS、Consul、Kubernetes等多种服务发现机制并给出设计合理Metrics、避免高基数数据爆炸、依托Grafana可视化与Alertmanager多渠道通知的实践建议。压缩包为36.62MB的zip文档以HTML格式编排便于翻阅检索。已有1607人学习下载可作为构建云原生可观测体系、提升Kubernetes微服务环境监控与故障排查能力的一站式参考资料。 提到“普罗米修斯”先别急着往希腊神话那想。我在这儿说的是监控圈里的 Prometheus——那款在云原生时代几乎成了“监控默认选项”的开源系统。中文社区里关于普罗米修斯的教程和帖子多到刷不完可新手群里每天还是有人在问“数据模型到底怎么理解”“PromQL 为什么查不出数”“告警怎么一上来就炸群”。我越来越觉得缺的不是资料而是把官方文档翻译过一遍之后就没人讲透的“为什么”和“怎么办”。于是我把这些年的实操经验沉成了一份《普罗米修斯手册普罗米修斯中文文档》这篇博文就从这份手册里抽几条主线拎出来聊聊看看一套能真正落地的监控体系到底应该从哪儿入手。1. Prometheus为什么能成为监控事实标准先想明白它解决什么问题1.1 从主机监控到云原生监控拐点出在哪早期做监控大多数人接触的是 Nagios、Zabbix 这一套核心思路是“盯着主机”。部署一个 agent在配置里写死要监控哪些主机和哪些服务然后配一堆阈值超过就告警。这套思路在物理机时代很顺手机器数量稳定、服务拓扑也基本不变。可到了容器和 Kubernetes 时代麻烦就来了服务实例今天 3 个明天 30 个Pod 的 IP 随时在变服务接口拆分得越来越细。你不可能用“写死目标列表”的方式来采集监控数据。Prometheus 最聪明的地方恰恰是它的设计前提就基于“目标会动态变化”这件事抓取目标不是靠配置文件里写死而是靠服务发现机制动态找出来的。这套思维转变很重要也是我写中文文档时反复强调的不先把“动态环境”这个背景理解透后面很多配置看起来就是无根之木。比如 scrape_configs 里为什么会支持 kubernetes_sd_configs、consul_sd_configs 这种动态发现方式本质都是为了适配“目标会跑”的现实。1.2 Prometheus只解决指标监控别指望它包打天下另一个常见误区是把 Prometheus 想成“什么监控都能干”的金刚钻。其实监控领域有四大类信号指标、日志、链路追踪、事件。Prometheus 专注做的是指标这一块也就是像“请求数每秒多少”“CPU 使用率多少”“队列积压多少”这类数值型数据。日志有 Loki、ELK链路追踪有 Jaeger、SkyWalking它们和 Prometheus 是配合关系不是替代关系。我见过不少新人折腾了半天 Prometheus发现没法查日志回头骂这工具不好用。这其实是在用手册第一页就写清楚的东西定位。中文资料里“普罗米修斯”这个名字还有个副作用——很多人会把它误当成性能压测工具那是 Apache JMeter 的活儿或者和电影《普罗米修斯》扯上关联。我在手册开篇就打了个预防针它是时间序列数据库是监控采集器是告警引擎这几个身份组合在一起才是完整的 Prometheus。2. 吃透数据模型才算真正打开了监控大门2.1 一条时间序列是怎么组成的Prometheus 里所有数据都可以抽象成一条时间序列time series它由三部分组成指标名、标签集合、样本值。举个例子node_cpu_seconds_total{cpu0, modeuser} 1024.5这个结构里node_cpu_seconds_total是指标名cpu0和modeuser是标签后面的数值是采样值再附带一个毫秒级时间戳。当你在 Prometheus 的查询框里看到一个指标名配一堆标签其实你看到的是一组时间序列而不是单一的一条。标签是 Prometheus 建模能力的核心。同一个指标名配上不同标签值就能区分出维度。反过来说标签值只要有一个不同就会生成一条全新的时间序列。这个设计非常灵活但也埋了一个大坑——标签值组合爆炸也就是高基数问题。这点我在后面踩坑清单里会细说。2.2 四种指标类型Counter、Gauge、Histogram、SummaryPrometheus 客户端库提供了四种指标类型这是文档里最基础却最容易被忽略的部分类型特点典型场景Counter只增不减重启归零请求总数、错误数、任务执行次数Gauge可增可减表示当前状态CPU 使用率、内存使用量、在线人数Histogram客户端分桶统计累加计数请求延迟、响应体大小Summary客户端直接算出分位数延迟分位数但无法跨实例聚合实操里最常见的错误是把 Counter 直接拉出来看原始值。比如http_requests_total是一个 Counter你直接看图会发现它一直往上爬数值大得没意义真正有用的是计算它的变化速率——这时就需要rate()或increase()函数。Histogram 和 Summary 的区别也要分清Historygram 在服务端可以通过histogram_quantile()算 p99而 Summary 的分位数是客户端算好的跨实例聚合时会失真。2.3 job 与 instance目标命名与 Exporter 的角色在 Prometheus 的采集配置里每个被抓取的目标会被打上两个隐含标签job和instance。job代表逻辑分组比如node_exporter、mysql_exporterinstance代表具体目标地址比如192.168.1.10:9100。这两个标签是所有目标上的“通用身份信息”在查询和汇总裁体时经常用到。Exporter 在这里扮演的是翻译官的角色。你的业务系统不可能都原生暴露 Prometheus 格式的指标Exporter 就负责把你的某种系统状态操作系统、MySQL、Redis转成 Prometheus 能够理解的文本格式。比如在 Linux 主机上部署 node_exporter它默认监听 9100 端口访问/metrics路径就能看到一堆node_*开头的指标。不少中文教程喜欢一上来就堆一堆 exporter 列表但没把“Exporter 是什么”讲清楚。我写手册时特意先解释了 pull 模型和 exporter 的关系再说“从哪下载、怎么启动”这些操作细节否则读者只会抄命令一旦报错就懵。3. 从零到一部署配置里最容易忽略的细节3.1 安装方式该选哪个别上来就搬 OperatorPrometheus 有两种主流使用姿势单机部署和 Kubernetes 集群部署。本地或者测试环境我建议直接用二进制下载解压就能跑依赖极少对理解配置逻辑最有帮助。部署在服务器里可以用 Docker 一行命令起一个容器也好管理。一旦上了 Kubernetes很多人会直接上 Prometheus Operator 或 kube-prometheus-stack。但我的建议是刚开始别上来就搞 Operator先在本地把 prometheus.yml 的结构搞懂知道 global 和 scrape_configs 是干嘛的再用 Operator 的时候你才看得懂它帮你生成的配置。否则出了问题你在那一大堆 CRD 和 PrometheusRule 中间根本找不到方向。常用 exporter 和端口也列一份方便对照Exporter默认端口用途node_exporter9100主机 CPU、内存、磁盘、网络指标mysqld_exporter9104MySQL 服务状态和性能指标redis_exporter9121Redis 实例指标blackbox_exporter9115基于 HTTP/HTTPS/TCP/ICMP 的服务探测cadvisor8080容器 CPU、内存、网络指标3.2 prometheus.yml 核心配置scrape_configs 是入口一份最小可用配置非常简单global: scrape_interval: 15s evaluation_interval: 15s scrape_configs: - job_name: node static_configs: - targets: [localhost:9100]global段设置全局抓取频率和规则评估频率scrape_configs定义要抓哪些目标。这里的job_name会作为 job 标签出现在所有该任务的时间序列上targets就是具体抓取端点。实际操作中比配置本身更重要的是“目标怎么来”。静态配置适合环境稳定的小规模场景稍微大一点就可以用file_sd_configs做文件动态发现或者接入consul_sd_configs、kubernetes_sd_configs。文件动态发现是我用过成本最低的方案维护一个 JSON 或 YAML 文件Prometheus 会周期性重读它目标增删直接改文件不用重启服务。3.3 存储参数和部署形态单机之外再想高可用Prometheus 单机自带本地 TSDB 存储数据放在--storage.tsdb.path指定的目录默认保留 15 天。你可以在启动参数里调长保留周期./prometheus --storage.tsdb.path/data/prometheus --storage.tsdb.retention.time30d很多人会忽略的是单机 Prometheus 天然不做高可用。如果你担心它挂了可以在后面接 Thanos 或 VictoriaMetrics 做长期存储和联邦查询在 Kubernetes 生态里Prometheus Operator 加 Thanos 是一个很常见的组合。但我的建议是先把单机跑明白看到数据稳定出图了再考虑分布式扩展别一上来就把架构堆得珠穆朗玛峰一样高。4. PromQL手册里最值得精读的一章4.1 瞬时向量和范围向量查询里的两个核心概念PromQL 不是普通的 SQL它操作的是向量。先说两个必须分清的概念瞬时向量instant vector某个时间点上的时间序列值集合例如node_cpu_seconds_total查询出来的是“当前这一刻”各个序列的值。范围向量range vector一段时间范围内的值集合用方括号表示例如node_cpu_seconds_total[5m]取的是近 5 分钟所有采样点。很多新手查不出数据问题就出在混合了这两类向量。比如对着rate(node_cpu_seconds_total[5m])这个查询它内部的[5m]先产生一个范围向量rate函数再算出每秒变化率输出的是瞬时向量。如果你想把结果画成图需要的是瞬时向量类型。明白了这一层你看很多复杂的 PromQL 表达式就能拆解了。4.2 掌握这一组函数应付日常查询就够了PromQL 自带上百个函数但日常真正高频的没那么多rate(v range-vector)计算范围向量在单位时间内的平均增长率是 Counter 类指标最常用的函数。irate(v range-vector)计算范围向量里最后两个样本点的瞬时增长率适合观察尖峰绘制的图更灵敏但锯齿感强。increase(v range-vector)计算范围向量覆盖的时间段内的总增量。sum(expression)把多个时间序列按维度求和。topk(k, expression)取值最大的前 k 条序列。histogram_quantile(φ, v)根据 Histogram 的 bucket 计算分位数。一个实际查询例子CPU 使用率100 - avg(rate(node_cpu_seconds_total{modeidle}[5m])) * 100再比如 HTTP 请求延迟 p99如果指标名是http_request_duration_seconds_buckethistogram_quantile(0.99, sum(rate(http_request_duration_seconds_bucket[5m])) by (le))这里注意by (le)这个聚合短语le是 histogram bucket 的上边界标签计算分位数时必须按le维度聚合并保留histogram_quantile才能正确算出 p99。4.3 PromQL 的几条入门红线我在手册里专门列过几条新手必踩的雷不要对 Counter 用avg或max它不断累加直接用这些聚合函数得到的是个毫无参考意义的数。不要用count代替rate算速率count数的是序列条数不是值大小。不要忽略标签匹配器的写法。~是正则匹配正则要是写得太宽比如job~.*很可能会把无关序列全捞出来查询慢到怀疑人生。5. 告警链路规则、收敛与通知不是配完就完事5.1 告警规则写在 Prometheus 还是 AlertmanagerPrometheus 的告警规则写在 prometheus.yml 同目录的规则文件里通过rule_files加载。一条告警规则的核心字段是expr、for、labels、annotationsgroups: - name: node_alerts rules: - alert: NodeDown expr: up{jobnode} 0 for: 1m labels: severity: critical annotations: summary: Instance {{ $labels.instance }} down description: {{ $labels.instance }} has been down for more than 1 minuteexpr是要持续为真的查询表达式for是持续时间比如上面的“连续 1 分钟发现 up 等于 0 才触发”这是防止偶发抖动误报的关键参数。告警状态依次是 inactive未触发、pending已命中但未到 for 时长、firing正式触发firing 之后才会推给 Alertmanager。5.2 Alertmanager 的三大收敛武器如果没有 Alertmanager一条服务挂了可能导致几十条关联告警全部轰炸你的手机。Alertmanager 就是来做减法的地方核心机制有三个分组、抑制、静默。分组grouping把同一类目下的告警合并成一条通知。比如同一个 service 下多个实例同时 Down默认配置下不会发几十条邮件而是合在一起。抑制inhibition高等级告警出现后抑制那些相关的低等级告警。比如某台机器完全宕机了那上面 MySQL 挂了的告警就不要再报了反正报了也没人能在那台机器上操作。静默silence在维护窗口期按标签精确匹配暂时屏蔽掉某些告警。一个简要的 alertmanager.yml 示例route: receiver: default group_by: [alertname, cluster] group_wait: 30s group_interval: 5m repeat_interval: 4h receivers: - name: default email_configs: - to: opsexample.com webhook_configs: - url: http://your-webhook-service/hook我可以这么说把 90% 的精力花在写告警规则上的人到头来都被通知风暴折磨反而把 30% 精力花在配置分组和收敛上的人告警体验会舒服很多。5.3 工程实践怎么让告警真正被处理告警文本里一定要有可操作的排障信息。annotations里写清“去看哪个 Grafana 面板”“这个服务的历史基线是多少”“有没有标准应急预案链接”。纯英文的模板变量也有作用{{ $labels.instance }}会渲染成实际目标地址、{{ $value }}会渲染成当前数值别把这些变量写成死文本。6. 手册最后附的一页踩坑清单与学习路径建议6.1 高基数标签设计最大的一道坎Prometheus 的多维标签可以让数据查询非常方便但代价是底层时间序列数量会急剧膨胀。最经典的负面案例是把 request_id 这种唯一值直接做成标签。每个请求都会生成新序列Prometheus 的 TSDB 会被海量序列拖垮查询和存储一起变慢。在实际采样中凡是“值域很大且增长无界”的字段都不适合做标签比如用户 ID、订单号、IP 地址这种。解决办法是用 relabel 规则把不需要的高基数标签删除或者在客户端埋点时就只暴露固定维度的标签集合。6.2 时间不同步一个被大量中英文文档一言带过的坑Prometheus 是一个时间序列系统对时间同步极其敏感。如果被采集的目标节点时钟和 Prometheus 服务端偏差过大数据点的时间戳对不上可能出现“图是断的”甚至查询结果混乱。node_exporter 采集到的数据是好的但时间不对齐Grafana 面板上就会缺一大截。稳定性第一件事所有参与采集的机器都统一走 NTP 时间同步。6.3 查询慢别等卡了才想起 recording rule线上 PromQL 慢很多时候是因为每次查询都要现算大量原始序列。一个常见优化手段是记录规则recording rule预先把高频查询的计算结果保存为一条新指标查询时直接查结果groups: - name: recording_rules rules: - record: job:node_cpu_usage:avg_rate5m expr: 100 - avg(rate(node_cpu_seconds_total{modeidle}[5m])) * 100查询时直接job:node_cpu_usage:avg_rate5m就能拿到算好的值性能提升肉眼可见。6.4 中文术语的坎文档里必须保留英文原文我在整理中文文档时发现最影响新手理解的其实是术语翻译。scrape 有人叫“抓取”、有人叫“拉取”target 有人叫“目标”有人叫“靶子”job/instance 的译法更是五花八门。我的处理方式是在中文里保留英文术语或中英对照比如“抓取scrape”“目标target”“任务job”这样和官方文档、社区讨论对得上不会被不同译名绕晕。6.5 给新手的路径五步走别急着上 Operator如果让我给读者一条最省时间的学习路径我会建议这样本地下载二进制启动 Prometheus访问/metrics看内置指标写一个最简单的 prometheus.yml 接入 node_exporter在 Prometheus 页面里执行几条 PromQL最后配一条最简单的告警连通邮件或 webhook。这五步跑通后你再碰 Operator、Thanos、VictoriaMetrics会发现它们全是在这套骨架上做管理或增强而不会在一个又一个组件里迷路。这套路径也是我整理中文手册时的主线具体内容都按这条路径展开铺陈。本文还有配套的精品资源点击获取