Prometheus 配置文件 prometheus.yml 全解析：scrape_configs 与全局设置一次讲透的完整清单

Prometheus 配置文件 prometheus.yml 全解析scrape_configs 与全局设置一次讲透的完整清单【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheusPrometheus普罗米修斯是开源监控界最主流的监控系统和时序数据库它的行为几乎完全由一个 YAML 文件prometheus.yml决定多久抓一次指标、从哪里抓取、告警发到哪、数据写到哪里全在这个文件里。本文面向新手用一份完整清单讲透prometheus.yml 全局设置global与scrape_configs抓取任务两大核心并覆盖 rule_files、remote_write 等其余小节帮你一次读懂、不再查文档。一、先搞懂prometheus.yml 是怎么生效的指定文件Prometheus 启动时通过命令行参数--config.file指定配置文件路径官方默认示例就是prometheus.yml。热加载改完配置不用重启——发送SIGHUP信号或调用/-/reload接口即可让新配置立即生效如果新配置有语法错误旧配置会继续保留不会把进程搞挂。一份完整合法示例仓库里自带了一份全参数示范文件 config/testdata/conf.good.yml配合权威文档 docs/configuration/configuration.md 阅读是学习这个文件最快的路径。 记忆口诀命令行参数管系统级数据存哪、保留多久prometheus.yml 管业务级抓谁、怎么抓、怎么告警。二、prometheus.yml 的 7 大板块总览整个配置文件由几个平级小节组成对应源码中的 Config 结构体。新手不必全背先建立全局印象小节作用一句话新手优先级global全局默认值 外部标签⭐⭐⭐ 必会rule_files加载告警规则 / 记录规则文件⭐⭐⭐ 必会scrape_configs定义抓取任务核心⭐⭐⭐ 必会alerting配置 Alertmanager 地址⭐⭐ 常用remote_write把时序数据推送到外部存储⭐⭐ 常用remote_read从外部存储读回历史数据⭐ 进阶storageTSDB 存储保留策略⭐ 进阶global: scrape_interval: 15s rule_files: - first.rules scrape_configs: - job_name: prometheus static_configs: - targets: [localhost:9090]三、全局设置 global一次看懂 10 个关键参数global里的值是整个实例的默认值每个 scrape job 没单独设置时都会继承它。以下是 GlobalConfig 结构体 中最值得了解的部分3.1 时间与间隔参数默认值说明scrape_interval1m全局默认抓取间隔如15sscrape_timeout10s单次抓取超时必须 ≤ scrape_interval最常见的报错点evaluation_interval1m规则告警/记录评估频率3.2 外部标签与日志external_labels给所有对外发出的数据联邦、remote_write、Alertmanager统一打上的标签是区分哪台 Prometheus 上报的的标准做法例如monitor: codelab。query_log_file把 PromQL 查询写入日志文件排查慢查询的利器。scrape_failure_log_file抓取失败详情日志定位为什么这个目标抓不到时非常有用。3.3 安全阀系列防止指标爆炸参数作用sample_limit单次抓取最多接收的样本数target_limit单个 job 最多接受的唯一目标数label_limit单个样本最多允许的标签数body_size_limit单次抓取响应体大小上限这些限额参数默认都是 0不限制生产环境建议按需设置避免某个异常目标把内存打爆。⚠️ 新手最常踩的坑scrape_timeout写成了比scrape_interval还大的值配置校验直接失败。记住超时永远要小于间隔。四、核心重点scrape_configs 抓取配置详解scrape_configs是全文档篇幅最大、也最核心的一节。每个列表元素就是一个抓取任务job对应源码 ScrapeConfig 结构体。一个最小可用的 job 长这样scrape_configs: - job_name: prometheus static_configs: - targets: [localhost:9090, localhost:9191] labels: my: label4.1 job_name给任务起个名job_name是每个 job必填项缺了会直接报job_name is empty错误。它会自动写入每条时序的job标签——之后你在查询面板里按 job 筛选数据靠的就是它。4.2 目标怎么来三大发现方式Prometheus 抓取的目标地址来自三类服务发现Service Discovery配置可混合使用方式配置键适用场景静态配置static_configs固定 IP / 主机名新手首选文件发现file_sd_configs用 JSON/YAML 文件动态更新目标生态发现kubernetes_sd_configs、consul_sd_configs、dns_sd_configs等K8s、Consul、DNS、云平台AWS/Azure 等 30 种例如接入 Kubernetes 只需声明role并指向 API Server完整示例见 conf.good.yml- job_name: service-kubernetes kubernetes_sd_configs: - role: endpoints api_server: https://localhost:12344.3 抓取行为参数metrics_path、scheme 与两个 honor参数默认值说明metrics_path/metrics抓取路径联邦抓取常设为/federateschemehttp协议https 需配合tls_confighonor_labelsfalse为 true 时保留目标自带的标签同名标签不被覆盖honor_timestampstrue是否尊重指标自带的采集时间戳联邦场景通常要设为 falsehonor_labels的典型场景目标端已经自己打了instance标签但 Prometheus 抓取时会强制改写它设为true即可保留目标原始标签避免标签被覆盖。4.4 relabel_configs标签处理的瑞士军刀relabel标签重写是 Prometheus 最强大也最易被低估的特性规则定义在 model/relabel/ 包中。两类用途要分清relabel_configs目标重写抓取之前执行用来过滤目标、改job/instance标签、做分片如按 hashmod 只抓 1/8 的目标。metric_relabel_configs指标重写抓取之后执行最常用于丢弃不需要的指标直接降低数据量metric_relabel_configs: - source_labels: [__name__] regex: expensive_metric.* action: drop常用action值replace替换默认、keep/drop保留/丢弃、hashmod分片、labelmap/labeldrop/labelkeep批量处理标签。4.5 job 级覆盖小 job 个性化设置job 里可以重复写scrape_interval、sample_limit等参数来覆盖 global 默认值——比如慢接口单独设scrape_interval: 50s、scrape_timeout: 5s高频接口单独调小间隔互不影响。五、其余小节速查清单30 秒看懂rule_filesglob 规则加载告警规则与记录规则如- my/*.rules文件格式见 docs/configuration/recording_rules.md。alerting指向 Alertmanager 地址可写多个实现冗余不配置就不发告警。remote_write把本地 TSDB 的数据推到外部存储如 Thanos、Cortex、云监控支持限流、重试、write_relabel_configs过滤Agent 模式的核心就是只写不查上图架构中的 remote write 链路。remote_read查询时合并外部存储的历史数据。storage.tsdb控制本地保留策略retention.time如15d与retention.size如50GB二选一另支持out_of_order_time_window乱序写入窗口。六、上手清单验证配置 避坑指南改前先备份改后先验证再 reload——项目自带的 promtool 就是干这个的promtool check config prometheus.yml一条命令就能把语法和逻辑错误全部报出来测试用例见 promtool check 相关。scrape_timeoutscrape_interval→ 直接校验失败改成超时小于间隔。job 抓不到数据→ 先看/targets页面再配合scrape_failure_log_file定位是路径错、认证错还是超时。标签被莫名改写→ 检查是否漏配honor_labels或 relabel 规则写错了target_label。想确认某条参数是否合法→ 官方 schema 文档 docs/configuration/configuration.md 中每个参数都有[ 参数 | 默认值 ]的标准标注。掌握globalscrape_configs这两节你就覆盖了 prometheus.yml 90% 的日常使用场景剩下的 remote_write、alerting 等小节按上面速查清单按需查阅即可。祝配置顺利监控无忧 【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考