在这里插入图片描述

👋 大家好，欢迎来到我的技术博客！
📚 在这里，我会分享学习笔记、实战经验与技术思考，力求用简单的方式讲清楚复杂的问题。
🎯 本文将围绕Prometheus这个话题展开，希望能为你带来一些启发或实用的参考。
🌱 无论你是刚入门的新手，还是正在进阶的开发者，希望你都能有所收获！

文章目录

Prometheus - 核心数据模型：指标 / 标签 / 时间序列全面理解

在现代可观测性（Observability）体系中，Prometheus 已经成为监控和告警领域的事实标准。自 2012 年由 SoundCloud 开发以来，它凭借其简洁而强大的数据模型、高效的存储机制以及灵活的查询语言 PromQL，赢得了广泛的应用。然而，要真正掌握 Prometheus，必须深入理解其核心数据模型——指标（Metric）、标签（Label） 和 时间序列（Time Series）。这三者构成了 Prometheus 的基石，决定了我们如何采集、存储、查询和分析系统状态。

本文将从零开始，系统性地剖析 Prometheus 的核心数据模型，结合 Java 代码示例、可视化图表和实际应用场景，帮助你构建对这一强大工具的完整认知。无论你是 DevOps 工程师、SRE、后端开发者，还是刚刚接触监控系统的新手，都能从中获得实用的知识和启发。

什么是 Prometheus？

Prometheus 是一个开源的系统监控和告警工具包，最初由 SoundCloud 开发，并于 2016 年成为继 Kubernetes 之后第二个加入 CNCF（Cloud Native Computing Foundation）的项目。它的设计哲学强调 拉取（Pull）模型、多维数据模型 和 强大的查询能力。

与传统的监控系统（如 Nagios、Zabbix）不同，Prometheus 不依赖于中心化的数据收集代理，而是通过定期从目标服务的 HTTP 端点“拉取”指标数据。这种设计使得服务本身可以自主暴露其运行状态，而无需外部侵入式配置。

但这一切的基础，都建立在其独特的 多维时间序列数据模型 之上。接下来，我们将逐层拆解这一模型。

指标（Metric）：监控的基本单位

在 Prometheus 中，指标（Metric） 是描述系统某个可观测特征的命名数据流。它是监控的最小语义单元，代表了某种可度量的数值随时间的变化。

指标的命名规范

Prometheus 对指标命名有明确的约定：

  • 使用 下划线分隔的小写 ASCII 字符（如 http_requests_total）
  • 名称应具有 语义清晰性，通常包含 应用前缀（如 myapp_http_requests_total）
  • 避免使用保留字（如 process_、go_ 等，这些通常由客户端库自动提供）

✅ 良好命名：api_request_duration_seconds
❌ 不良命名：APIRequestDuration、api.request.duration

指标的类型

Prometheus 定义了四种基本的指标类型，它们在客户端库中表现为不同的数据结构，但在存储时都会被统一转换为 时间序列：

  1. Counter（计数器）
    单调递增的累计值，用于记录事件发生的总次数。例如：HTTP 请求数、错误数、任务完成数。
    ⚠️ 注意：Counter 只能增加或重置为 0（如进程重启），不能减少。

  2. Gauge（仪表盘）
    可任意增减的瞬时值，用于表示当前状态。例如：内存使用量、队列长度、温度。

  3. Histogram（直方图）
    用于统计观测值的分布情况（如请求延迟）。它会自动创建多个时间序列：

    • _bucket{le="..."}：小于等于某阈值的观测值数量
    • _count：总观测次数
    • _sum：所有观测值的总和

  4. Summary（摘要）
    类似 Histogram，但直接计算分位数（如 P95、P99）。由于分位数无法在服务端聚合，官方推荐优先使用 Histogram。

📌 提示：虽然存在四种类型，但 Prometheus 服务器本身并不“知道”原始类型——所有数据最终都以 <metric_name>{<labels>} value 的形式存储。类型信息主要用于客户端库生成正确的指标结构。

标签（Label）：赋予指标维度的灵魂

如果说指标是骨架，那么 标签（Label） 就是赋予其血肉和灵魂的关键。标签是以键值对（key-value）形式附加在指标上的元数据，用于对同一指标进行多维度切分。

为什么需要标签？

考虑一个简单的场景：你的服务部署在多个实例上，每个实例处理不同类型的请求。如果没有标签，你只能看到全局的 http_requests_total = 1000，但无法回答以下问题：

  • 哪个实例处理了最多的请求？
  • POST 请求和 GET 请求的比例是多少？
  • /api/v1/users 接口的错误率是否异常？

通过引入标签，我们可以将单一指标拆分为多个 时间序列，每个序列代表一个唯一的维度组合：

http_requests_total{method="GET", path="/api/v1/users", instance="10.0.0.1:8080"} 120
http_requests_total{method="POST", path="/api/v1/users", instance="10.0.0.1:8080"} 30
http_requests_total{method="GET", path="/api/v1/orders", instance="10.0.0.2:8081"} 85

这样，Prometheus 就能支持极其灵活的查询和聚合操作。

标签的最佳实践

  • 避免高基数（High Cardinality）标签：如用户 ID、请求 ID、时间戳等唯一值。这会导致时间序列数量爆炸，压垮存储和查询性能。
  • 使用有意义的键名：如 job、instance、method、status_code，而非 tag1、field2。
  • 区分静态标签与动态标签：静态标签（如 region、env）可在 scrape 配置中注入；动态标签（如 path、user_type）需在应用代码中生成。

🔍 高基数陷阱示例：若为每个用户生成一个 user_id 标签，100 万用户将产生 100 万条时间序列，极易导致 OOM（Out of Memory）。

时间序列（Time Series）：数据的最终形态

在 Prometheus 中，时间序列（Time Series） 是指标名称与一组标签的唯一组合所对应的数据流。它是数据存储和查询的基本单位。

时间序列的定义

一个时间序列由以下两部分唯一确定：

  1. 指标名称（Metric Name）
  2. 标签集合（Label Set）

例如：

http_requests_total{method="GET", status="200"}

这个组合就定义了一个独立的时间序列。即使指标名称相同，只要标签集合不同，就是不同的时间序列。

时间序列的内部结构

每条时间序列实际上是一系列 样本（Sample） 的集合，每个样本包含：

  • 时间戳（Timestamp）：通常以毫秒为单位的 Unix 时间
  • 数值（Value）：浮点数（Prometheus 所有值均为 float64）

因此，一条时间序列在逻辑上可表示为：

[ (t1, v1), (t2, v2), (t3, v3), ... ]

Prometheus 默认每 15 秒抓取一次数据（可通过 scrape_interval 配置），因此每个时间序列大约每 15 秒新增一个样本点。

时间序列的生命周期

  • 创建：当 Prometheus 首次从目标抓取到某个指标+标签组合时，自动创建时间序列。
  • 更新：每次抓取时，若该组合存在，则追加新样本；若不存在，则视为该序列已消失（可能因服务重启或标签变化）。
  • 删除：Prometheus 不会主动删除时间序列，即使目标不再上报。但可通过 tsdb 工具或配置 retention_time（默认 15 天）来清理旧数据。

💡 重要概念：时间序列的标识符 = 指标名 + 所有标签（按字典序排序）。这意味着 {a="x", b="y"} 和 {b="y", a="x"} 被视为同一个序列。

指标、标签与时间序列的关系

现在，让我们用一个 Mermaid 图表 来直观展示三者之间的关系：

渲染错误: Mermaid 渲染失败: Parse error on line 4: ... C --> D[样本 Sample: (timestamp, value)] -----------------------^ Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got 'PS'

从图中可以看出：

  • 一个指标（如 http_requests_total）可以衍生出多个时间序列。
  • 每个时间序列由唯一的标签组合定义。
  • 每个时间序列包含按时间顺序排列的样本点。

这种 多维数据模型 是 Prometheus 强大查询能力的基础。你可以轻松地按任意标签维度进行过滤、聚合、计算比率等操作。

Java 应用集成 Prometheus：实战示例

理论理解之后，让我们通过 Java 代码看看如何在实际应用中暴露指标。我们将使用官方推荐的 Prometheus Java Client。

1. 添加依赖

首先，在 pom.xml 中添加依赖：

<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient</artifactId>
    <version>0.16.0</version>
</dependency>
<dependency>
    <groupId>io.prometheus</groupId>
    <artifactId>simpleclient_servlet</artifactId>
    <version>0.16.0</version>
</dependency>

🔗 官方文档：Prometheus Java Client GitHub（注意：此处仅为说明，不提供具体链接地址）

2. 定义并注册指标

下面是一个 Spring Boot 应用中的示例，展示如何使用 Counter、Gauge 和 Histogram：

import io.prometheus.client.Counter;
import io.prometheus.client.Gauge;
import io.prometheus.client.Histogram;
import io.prometheus.client.exporter.MetricsServlet;
import org.springframework.boot.web.servlet.ServletRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class PrometheusConfig {

    // 定义一个 Counter：记录总请求数
    public static final Counter REQUESTS_TOTAL = Counter.build()
            .name("http_requests_total")
            .help("Total HTTP requests")
            .labelNames("method", "path", "status") // 定义标签
            .register();

    // 定义一个 Gauge：记录当前活跃连接数
    public static final Gauge ACTIVE_CONNECTIONS = Gauge.build()
            .name("active_connections")
            .help("Current active connections")
            .register();

    // 定义一个 Histogram：记录请求处理耗时
    public static final Histogram REQUEST_DURATION = Histogram.build()
            .name("http_request_duration_seconds")
            .help("HTTP request duration in seconds")
            .buckets(0.01, 0.05, 0.1, 0.5, 1.0, 5.0) // 自定义桶
            .labelNames("method", "path")
            .register();

    // 注册 /metrics 端点
    @Bean
    public ServletRegistrationBean<MetricsServlet> metricsServlet() {
        return new Servlet_registration_bean<>(new MetricsServlet(), "/metrics");
    }
}

3. 在业务逻辑中使用指标

在 Controller 中埋点：

import org.springframework.web.bind.annotation.*;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@RestController
public class UserController {

    @GetMapping("/api/v1/users")
    public String getUsers(HttpServletResponse response) {
        // 开始计时
        Histogram.Timer timer = PrometheusConfig.REQUEST_DURATION
                .labels("GET", "/api/v1/users")
                .startTimer();

        try {
            // 模拟业务逻辑
            Thread.sleep(100);
            
            // 成功响应
            PrometheusConfig.REQUESTS_TOTAL
                    .labels("GET", "/api/v1/users", "200")
                    .inc(); // 增加计数
            
            return "User list";
        } catch (Exception e) {
            // 错误响应
            PrometheusConfig.REQUESTS_TOTAL
                    .labels("GET", "/api/v1/users", "500")
                    .inc();
            response.setStatus(500);
            return "Error";
        } finally {
            timer.close(); // 自动记录耗时
        }
    }

    @PostMapping("/api/v1/users")
    public String createUser(@RequestBody String user) {
        PrometheusConfig.ACTIVE_CONNECTIONS.inc(); // 进入时增加
        try {
            // 模拟创建用户
            Thread.sleep(50);
            PrometheusConfig.REQUESTS_TOTAL
                    .labels("POST", "/api/v1/users", "201")
                    .inc();
            return "Created";
        } finally {
            PrometheusConfig.ACTIVE_CONNECTIONS.dec(); // 退出时减少
        }
    }
}

4. 查看暴露的指标

启动应用后，访问 http://localhost:8080/metrics，你将看到类似如下输出：

# HELP http_requests_total Total HTTP requests
# TYPE http_requests_total counter
http_requests_total{method="GET",path="/api/v1/users",status="200",} 5.0
http_requests_total{method="POST",path="/api/v1/users",status="201",} 2.0

# HELP active_connections Current active connections
# TYPE active_connections gauge
active_connections 0.0

# HELP http_request_duration_seconds HTTP request duration in seconds
# TYPE http_request_duration_seconds histogram
http_request_duration_seconds_bucket{method="GET",path="/api/v1/users",le="0.01",} 0.0
http_request_duration_seconds_bucket{method="GET",path="/api/v1/users",le="0.05",} 0.0
http_request_duration_seconds_bucket{method="GET",path="/api/v1/users",le="0.1",} 3.0
http_request_duration_seconds_bucket{method="GET",path="/api/v1/users",le="0.5",} 5.0
http_request_duration_seconds_bucket{method="GET",path="/api/v1/users",le="+Inf",} 5.0
http_request_duration_seconds_count{method="GET",path="/api/v1/users",} 5.0
http_request_duration_seconds_sum{method="GET",path="/api/v1/users",} 0.48

注意：

  • 每个指标都有 # HELP 和 # TYPE 注释，便于理解和解析。
  • Histogram 自动生成了 _bucket、_count、_sum 系列。
  • 所有值均为浮点数（即使计数也是 5.0）。

高级话题：标签的动态管理与性能考量

动态标签的陷阱

在上面的 Java 示例中，我们将 path 作为标签。但如果路径包含用户 ID（如 /api/v1/users/123），就会导致高基数问题：

// 危险！不要这样做
.labels("GET", "/api/v1/users/" + userId, "200")

正确做法是 泛化路径，使用占位符：

// 安全做法
.labels("GET", "/api/v1/users/{id}", "200")

或者在 Web 框架层面统一处理（如 Spring 的 @RequestMapping 路径模板）。

标签的注入方式

除了在代码中定义标签，还可以通过 Prometheus 的 relabeling 机制在抓取时动态添加或修改标签：

scrape_configs:
  - job_name: 'myapp'
    static_configs:
      - targets: ['localhost:8080']
        labels:
          env: 'production'
          region: 'us-east-1'

这样，所有来自该 job 的指标都会自动带上 env 和 region 标签，无需修改应用代码。

时间序列数量的监控

Prometheus 自身也暴露了关于时间序列数量的指标：

  • prometheus_tsdb_head_series: 当前活跃的时间序列数
  • prometheus_target_scrapes_sample_out_of_order_total: 样本乱序的次数（可能影响性能）

你可以设置告警规则，当时间序列数超过阈值时触发通知，防止存储爆炸。

查询与聚合：利用多维模型的力量

有了指标和标签，我们就可以使用 PromQL（Prometheus Query Language） 进行强大的分析。

基础查询

  • 查询所有 http_requests_total：

    http_requests_total

  • 按状态码过滤：

    http_requests_total{status="500"}

  • 计算 QPS（每秒请求数）：

    rate(http_requests_total[5m])

聚合操作

  • 按方法聚合总请求数：

    sum by (method) (http_requests_total)

  • 计算错误率：

    sum(rate(http_requests_total{status=~"5.."}[5m]))
  /
sum(rate(http_requests_total[5m]))

  • 获取 P95 延迟（基于 Histogram）：

    histogram_quantile(0.95, 
  sum by (le, method, path) (
    rate(http_request_duration_seconds_bucket[5m])
  )
)

📊 提示：Prometheus 的聚合操作是 向量化 的，可以同时对成千上万的时间序列进行计算，这是其高性能的关键。

常见误区与最佳实践

误区 1：滥用 Summary

许多开发者习惯使用 Summary 计算分位数，但由于其分位数是在客户端计算的，无法跨实例聚合。例如，两个实例各自的 P99 无法合并成全局 P99。

✅ 正确做法：使用 Histogram，让 Prometheus 在服务端计算分位数，支持任意维度聚合。

误区 2：忽略标签顺序

虽然 Prometheus 内部会对标签按键名排序，但在编写 PromQL 时，建议保持一致的标签顺序，提高可读性。

误区 3：过度细化指标

不要为每个微小差异创建新指标。例如，不要同时使用 http_requests_success_total 和 http_requests_error_total，而应使用一个 http_requests_total 加 status 标签。

最佳实践总结

  • 指标命名：清晰、一致、带前缀
  • 标签设计：低基数、有意义、避免唯一值
  • 类型选择：优先 Counter/Gauge/Histogram，慎用 Summary
  • 路径泛化：Web 路径使用模板，避免用户 ID 等动态部分
  • 监控自身：关注 prometheus_tsdb_head_series 等内部指标

结语：构建可观测性的基石

Prometheus 的核心数据模型——指标、标签与时间序列——看似简单，却蕴含着强大的表达能力。它通过 多维切片 的思想，将复杂的系统状态转化为可查询、可聚合、可告警的数据流。这种设计不仅契合云原生环境的动态性，也为开发者提供了极大的灵活性。

在实际应用中，理解这一模型能帮助你：

  • 设计更合理的监控指标
  • 避免性能陷阱（如高基数）
  • 编写出高效的 PromQL 查询
  • 构建真正有用的告警规则

正如 Prometheus 官方文档所言：“Instrumentation is not just about collecting data, but about collecting the right data in the right way.”

希望本文能为你打开 Prometheus 数据模型的大门。动手实践吧，在你的下一个 Java 项目中嵌入指标，观察系统的行为，让数据驱动你的决策！🚀

🔗 延伸阅读：

Happy Monitoring! 🎯

🙌 感谢你读到这里！
🔍 技术之路没有捷径，但每一次阅读、思考和实践，都在悄悄拉近你与目标的距离。
💡 如果本文对你有帮助，不妨 👍 点赞、📌 收藏、📤 分享 给更多需要的朋友！
💬 欢迎在评论区留下你的想法、疑问或建议，我会一一回复，我们一起交流、共同成长 🌿
🔔 关注我，不错过下一篇干货！我们下期再见！✨

# prometheus
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

学术合规性如何？8款AI论文平台排名，毕业答辩稳了！

avatar AtomGit开源社区

【顶级EI复现】考虑用户行为基于扩散模型的电动汽车充电场景生成（ Python + PyTorch代码实现）

针对大规模电动汽车无序充电对配电网稳定运行带来的挑战，传统统计建模方法难以刻画用户行为驱动下充电负荷的强随机性、时序依赖性与多维耦合特征，难以生成贴合实际运行规律的充电场景。为此，本文提出一种基于条件去噪扩散概率模型的电动汽车充电场景生成方法。首先，基于充电起始时刻、充电时长、充电功率、用户出行习惯等多维信息，构建用户个体与场站集群两层级行为特征矩阵，搭建多层级充电场景生成框架；

avatar AtomGit开源社区

LLM结构化输出工程：让AI返回你想要的格式

但在生产系统中，你的下游代码需要的不是一段流畅的自然语言，而是可解析的、格式固定的结构化数据。：如果用本地模型，Outlines的约束解码比提示词方式可靠100倍结构化输出是LLM工程化的基础设施，掌握它，你的AI应用才能真正稳定地运行在生产环境中。—## 四、本地模型的结构化输出：Outlines当你使用Llama、Qwen、Mistral等本地模型时，无法依赖云端API的结构化输出能力。：越复

avatar AtomGit开源社区