Prometheus：用PromQL管理多维时序监控与告警
给云原生团队做时序监控和告警，靠PromQL与HTTP Pull区别于推送式采集。
GitHub prometheus/prometheus 更新 2026-11-07 分支 main 星标 67.2K 分叉 11.0K
Go 时序数据库 PromQL HTTP Pull 服务发现 云原生

🧭 决策指南

为什么现在热： 无法从材料判断

适合，如果你

  • 你需要用PromQL查询带键值维度的多维时序指标。
    README“Features”列出multi-dimensional data model与PromQL。
  • 你的目标可通过HTTP Pull、service discovery或static configuration暴露。
    README“Features”列出HTTP pull model、service discovery和static configuration。
  • 你需要让批处理任务经由intermediary gateway推送时序数据。
    README“Features”说明批处理任务支持经由intermediary gateway pushing time series。

不适合，如果你

  • 你计划把prometheus/prometheus直接嵌入Go应用并依赖稳定库API。
    README“Using Prometheus as a Go Library”明确说该仓库不是为library设计，作为library可能出现错误。
  • 你准备在本地用make docker构建可直接工作的Docker镜像。
    README“Building the Docker image”说明make docker仅供CI使用，本地不会生成fully working image。

前置条件

  • Docker镜像可从Quay.io或Docker Hub获取；源码构建需要Go为go.mod指定版本或更高版本。
  • 源码构建还需要NodeJS为web/ui/.nvmrc指定版本或更高版本，以及npm 10或更高版本。
  • React UI资源需要显式运行make assets或make build构建。
  • Docker images are available from Quay.io or Docker Hub; source builds require the Go version specified in go.mod or greater.
  • Source builds also require the NodeJS version specified in web/ui/.nvmrc or greater, plus npm version 10 or greater.
  • React UI assets require an explicit make assets or make build step.

第一步命令（README 原文）

docker run --name prometheus -d -p 127.0.0.1:9090:9090 prom/prometheus

要注意

  • go install构建时，Prometheus会从web/ui/static读取Web资源，且React UI默认未包含。
    README“Building from source”说明需从克隆仓库根目录运行，并显式执行make assets或make build。
  • 启用或移除服务发现插件需使用remove_all_sd和enable_kubernetes_sd等Go build tags。
    README“Service discovery plugins”给出remove_all_sd与enable__sd构建标签。
  • Remote Write protobuf标为experimental，不能等同于稳定库接口。
    README“Remote Write”明确将buf.build上的Remote Write protobuf标为experimental。

替代方案

  • prometheus/client_golang：当需求是为Go应用提供Prometheus客户端库，而不是运行独立监控程序时。
    README“Using Prometheus as a Go Library”
  • prometheus/common：当需求是复用Prometheus生态的Go通用库，而不是部署prometheus/prometheus服务时。
    README“Using Prometheus as a Go Library”

材料未说明

  • README未给出单节点可承载的指标量、查询并发或数据保留上限。
  • README未说明生产部署所需的磁盘类型、内存规模或高可用故障切换方案。
  • README未给出HTTP Pull失败重试、目标认证或TLS配置细节。
  • README未说明PromQL与现有Grafana版本或其他Dashboard系统的兼容矩阵。
  • The README does not specify single-node metric capacity, query concurrency, or retention limits.
  • The README does not describe required production disk types, memory sizes, or high-availability failover design.
  • The README does not provide details on HTTP pull retries, target authentication, or TLS configuration.
  • The README does not provide a compatibility matrix for PromQL with Grafana versions or other dashboard systems.

💡 深度解析

6
不适合 我维护一个 Go 服务，想直接 import prometheus/prometheus 的内部包，把 PromQL、规则评估或存储能力嵌入现有程序；这个仓库适合作为稳定 Go 库吗？
适合读者： 希望在自己的 Go 服务中直接嵌入 Prometheus、而不是运行独立监控进程的 Go 平台开发者

不适合，因为 README 明确说明该仓库构建的是独立程序，并未按可复用库的稳定性设计内部 API。

  • “Using Prometheus as a Go Library”章节直接写明 repository builds a stand-alone program and is not designed for use as a library。
  • README 还警告，作为库使用时可能遇到 only surface when used as a library 的错误，说明内部接口不能视为稳定集成边界。
  • 对可复用能力，README 指向 prometheus/common 和 prometheus/client_golang，而不是承诺 prometheus/prometheus 的内部包。
  • 如果你的需求是 Remote Write protobuf，README 提供了独立地址，但同时标注 This is experimental；因此它也不等同于稳定的 Prometheus 嵌入式运行时。
  • README Using Prometheus as a Go Library: “builds a stand-alone program and is not designed for use as a library”
  • README Using Prometheus as a Go Library: “you may encounter errors that only surface when used as a library”
  • README Using Prometheus as a Go Library: “prometheus/common” and “prometheus/client_golang” are designed as reusable libraries
  • README Remote Write: “This is experimental.”
go get buf.build/gen/go/prometheus/prometheus/protocolbuffers/go@latest
材料未说明：README 未说明 prometheus/common 或 prometheus/client_golang 的具体 API 是否覆盖 PromQL、规则评估或本地存储嵌入需求。；README 未给出 prometheus/prometheus 内部包的版本兼容策略或迁移承诺。
适合 我只有一个监控节点，想用官方 Docker 镜像采集主机和服务指标，并在 127.0.0.1:9090 查看结果；Prometheus 是否适合？
适合读者： 希望在本地或单节点环境运行自主监控系统、只愿意使用官方 Docker 镜像的中小型基础设施运维工程师

适合，因为 Prometheus 可以作为不依赖分布式存储的自治单节点运行，并且官方提供 Docker 镜像。

  • README 的“Features”说明 single server nodes are autonomous，适合只有一个监控节点的部署。
  • 它通过 HTTP pull 从 configured targets 按给定间隔采集指标，并能在同一系统中查询、绘图和触发告警。
  • “Docker images”章节明确列出 Quay.io 和 Docker Hub，并给出了暴露 9090 端口的启动命令。
  • 但 README 没有承诺单节点的容量上限、跨区域容灾或高可用能力；当数据量和故障容忍要求提高时，需要额外的联邦或 Remote Write 架构。
  • README Features: “No dependency on distributed storage; single server nodes are autonomous”
  • README Features: “An HTTP pull model for time series collection”
  • README Docker images: “docker run --name prometheus -d -p 127.0.0.1:9090:9090 prom/prometheus”
  • 项目数据：description 为 “The Prometheus monitoring system and time series database.”
docker run --name prometheus -d -p 127.0.0.1:9090:9090 prom/prometheus
材料未说明：README 未说明单节点可承载的目标数量、样本写入速率、磁盘容量和默认保留周期。；README 未说明生产环境的备份、故障切换和认证配置。
适合 我需要修改 Go 服务、构建 React UI，并用构建标签只保留 Kubernetes 服务发现；这个仓库适合作为可定制源码项目吗？
适合读者： 使用 Go、Node.js、npm 和 React 维护监控平台源码、希望定制服务发现插件或 Web UI 的项目贡献者

适合，但前提是你接受同时维护 Go、Node.js、npm、React 和 Makefile 构建链路。

  • README 的“Building from source”要求 Go 版本符合 go.mod、NodeJS 版本符合 web/ui/.nvmrc，并要求 npm 10 或更高。
  • make build 会构建 prometheus 和 promtool，并把 Web 资源编译嵌入；make assets 专门构建 React UI。
  • “Service discovery plugins”章节提供 remove_all_sd 与 enable_kubernetes_sd 构建标签，能够裁剪插件并重新启用 Kubernetes 服务发现。
  • 项目数据表明主语言是 Go，同时包含 TypeScript、JavaScript 等代码；但 README 没有说明自定义插件的稳定 API，并明确不认可当前 out-of-tree plugins。
  • README Building from source: “NodeJS: Version specified in [.nvmrc]” and “npm: Version 10 or greater”
  • README Makefile targets: “build” includes building and compiling in web assets; “assets” builds the React UI
  • README Service discovery plugins: “remove_all_sd” and “enable_kubernetes_sd”
  • 项目数据：main_language 为 Go；language_distribution 包含 TypeScript、JavaScript
git clone https://github.com/prometheus/prometheus.git
材料未说明：README 未提供具体 Go、NodeJS 版本号，只要求读取 go.mod 和 .nvmrc。；README 未说明服务发现插件的稳定扩展接口，也未给出自定义 React UI 的兼容性边界。
适合 我需要部署多个 Prometheus 实例，并按层级或横向方式汇总部分指标；Prometheus 是否能支持这种联邦架构？
适合读者： 需要把多个 Prometheus 实例按组织层级或区域汇总、同时保留分层监控的 SRE 平台工程师

适合，因为 Prometheus README 明确提供 hierarchical and horizontal federation，并且项目洞察将联邦与 Remote Write列为从单实例扩展到多层级部署的路径。

  • “Features”章节直接列出“Support for hierarchical and horizontal federation”，与多实例分层或横向汇总需求一致。
  • 多维标签模型和 PromQL 使汇总后的指标仍可按服务、实例、区域或版本进行过滤与聚合。
  • 单节点自治意味着每个区域或集群可以独立运行，不必一开始引入外部分布式存储。
  • 但 README 没有说明联邦选择哪些指标、数据延迟、重复数据、跨区域故障恢复和长期保存策略；Remote Write章节还明确称其 protobuf library 为 experimental。
  • README Features: “Support for hierarchical and horizontal federation”
  • README Features: “No dependency on distributed storage; single server nodes are autonomous”
  • README Remote Write: “This is experimental.”
  • 项目洞察 market_gap： “联邦和Remote Write等能力则为更大规模或分层监控场景提供扩展路径”
材料未说明：README 未说明联邦端点配置、指标筛选规则、跨实例认证和网络拓扑要求。；README 未说明 Remote Write 的兼容性承诺、重试行为、数据延迟和远端存储实现。
适合 我运行 Kubernetes 工作负载，实例会频繁创建和销毁；我想用服务发现代替手工静态配置，并按服务、实例等标签查询，Prometheus 是否适合？
适合读者： 维护 Kubernetes 动态工作负载、需要让监控目标随服务变化自动更新的云原生 SRE

适合，因为 Prometheus 原生支持服务发现、HTTP pull，以及由指标名和键值标签组成的多维时间序列。

  • README 的“Features”列出 service discovery or static configuration，能够覆盖动态目标和固定目标两种管理方式。
  • 同一章节说明时间序列由 metric name 和 key/value dimensions 定义，因此可以按服务、实例等维度使用 PromQL 过滤和聚合。
  • README 的构建标签示例还展示了 enable_kubernetes_sd，可在裁剪服务发现插件后重新启用 Kubernetes 服务发现。
  • 但 README 没有给出 Kubernetes 版本兼容矩阵，也没有规定目标数量、标签基数或抓取间隔的容量边界；这些会直接影响内存、存储和查询成本。
  • README Features: “Targets are discovered via service discovery or static configuration”
  • README Features: “A multi-dimensional data model (time series defined by metric name and set of key/value dimensions)”
  • README Service discovery plugins: “enable_kubernetes_sd”
  • 项目洞察：技术方案包含“PromQL进行过滤、聚合、计算和时间窗口分析”
docker run --name prometheus -d -p 127.0.0.1:9090:9090 prom/prometheus
材料未说明：README 未说明 Kubernetes 服务发现所需的 RBAC 配置、支持的 Kubernetes 版本和具体 scrape 配置。；README 未说明动态目标规模与标签基数的性能阈值。
视情况 我的批处理任务是短生命周期的，任务结束后就无法被 Prometheus 持续拉取；我是否应该用 Pushgateway 推送指标？
适合读者： 负责短生命周期批处理任务、任务结束后无法持续暴露 HTTP 指标的 SRE

视情况，因为 README 明确支持通过中间 Gateway 推送批处理时间序列，但它不是对所有应用指标的通用替代方案。

  • README 的“Features”列出“Pushing time series is supported via an intermediary gateway for batch jobs”，直接覆盖任务结束后无法持续被拉取的场景。
  • 默认模型仍是 HTTP pull，Prometheus 会从 configured targets 按给定间隔采集；Pushgateway 是针对批处理的例外路径。
  • 项目洞察指出，Pushgateway 适合特定短生命周期任务，指标生命周期和过期清理处理不当可能留下旧指标。
  • 因此是否采用取决于任务的指标生命周期、清理方式和重复推送语义；README 没有说明这些细节的标准配置。
  • README Features: “Pushing time series is supported via an intermediary gateway for batch jobs”
  • README 开头: “It collects metrics from configured targets at given intervals”
  • 项目洞察 common_pitfalls： “错误使用Pushgateway……可能遗留过期指标”
  • 项目洞察 usage_limitations： “默认HTTP Pull模型要求Prometheus能够访问目标”
材料未说明：README 未给出 Pushgateway 的部署命令、清理接口、标签生命周期规则和批处理失败时的指标语义。；README 未说明 Pushgateway 在当前规模下的容量、持久化和高可用方式。

✨ 核心亮点

  • PromQL查询多维指标，支持名称与键值维度
  • 单节点自治，不依赖分布式存储系统
  • HTTP Pull采集，兼容服务发现与静态配置
  • 支持批处理Gateway推送与层级、横向联邦

🔧 工程化

  • 按配置目标定时采集指标，评估规则并触发告警
  • 提供PromQL查询、图形展示与多种Dashboard支持
  • Docker可用9090端口启动，make build编译Web资源

⚠️ 风险

  • 仓库明确说明prometheus/prometheus不适合作为Go库
  • go install需从源码根目录运行并处理React资源
  • make docker仅供CI使用，本地不会生成完整可用镜像

👥 适合谁？

  • 需要Go生态监控、PromQL查询和服务发现的团队
  • 使用Docker或Kubernetes服务发现的云原生运维团队