hanjm 的 Prometheus 笔记：把 Go 服务指标接入 Grafana 观测（imhanjm-prometheus-grafana）
从服务内部数据到监控指标
应用运行时会产生许多有用状态：请求数量、错误数量、处理耗时、协程数、数据库连接数和消息队列延迟等。若仅依靠日志排查，开发者通常要在大量文本中搜索；将重要状态转换为结构化指标后，就可以按时间观察变化，并在需要时与业务事件对照。
文章从 Go 服务的运行状态出发，提到通过 Prometheus SDK 暴露 CPU、内存、协程、线程、文件描述符和重启次数等指标。还举例说明可在日志封装层统计 Error 数量、在消息队列客户端统计发送和消费时延、在数据库封装层观察连接池状态，或在 HTTP Middleware 记录请求数量、耗时和响应码。
指标如何被 Prometheus 收集
文章介绍的模型是 Pull 抓取：应用把指标通过 HTTP 接口暴露出来，Prometheus 根据配置定期访问目标并读取指标。应用本身不必主动推送数据到一个固定接收端，抓取端可以集中管理目标和抓取周期。对于服务数量变化的环境，Prometheus 还可以使用服务发现配置动态获取目标，而不必只依靠手工维护静态地址。
一条指标记录通常包含指标名称、标签、数值和时间信息。指标名称表达观测对象，标签提供维度，数值则记录当前测量结果。文章举例使用 job 和 instance 等标签描述目标来源，也展示了通过配置给目标增加额外固定标签的方式。标签让同一个指标可以按服务、实例或其他维度筛选和聚合。
使用标签时应优先选择有限且有稳定含义的维度，例如服务名或状态类型。若把每次请求的唯一 ID 等高变化值放入标签，时间序列数量可能迅速增长，给存储和查询带来负担。文章未将这一点作为主要篇幅，但它是设计埋点时需要一起考虑的工程边界。
常见指标类型与适用场景
文章介绍了几类常见指标。Counter 是累计计数器，适合请求总量或错误总数等只增不减的事件；服务重启后计数可能从头开始，查询时应结合时间序列的变化理解。Gauge 用于可升可降的瞬时数值，例如当前内存使用量、正在处理的任务数量或打开的连接数。
Histogram 用于观察数值分布，常见场景是请求响应时间或响应体大小。它把观测值按设定区间累积到 bucket，便于从大量请求中分析延迟分布。Summary 也是围绕观测值分布的一类指标，但适用方式和聚合能力与 Histogram 不同。选择类型时，应先确定想回答的问题是“发生了多少次”“当前是多少”还是“数值分布怎样”。
从 SDK 埋点到仪表盘
Go SDK 让应用代码能够定义指标并更新其数值。常见做法是在业务边界附近埋点，例如 HTTP 请求入口、消息处理流程和数据库连接池封装。埋点应围绕可观察的问题设计，而不是为了收集尽可能多的数据。指标名称、标签和单位需要清晰一致，后续查询和仪表盘才能被团队理解。
当 Prometheus 抓取到指标后，Grafana 可以将查询结果转换成图表和仪表盘。单个指标曲线有时难以解释，结合请求量、错误率、延迟和资源使用情况一起观察，通常更容易判断服务在某个时间段发生了什么。仪表盘也适合用作排查入口，但不能替代对日志、追踪和代码变更的进一步分析。
服务发现与目标维护
静态抓取配置适合目标固定且规模较小的场景；目标数量变化频繁时，逐个编辑配置会增加维护成本。文章介绍 Prometheus 支持多种服务发现方式，也可以通过文件发现读取外部程序定期生成的目标列表。监控系统随后加载更新后的目标配置，减少人工同步地址的工作。
使用服务发现时，需要明确目标登记、移除和标签赋值规则。失效目标应能及时从发现结果中移除，新增目标也应得到一致的服务标签。否则仪表盘可能混入重复实例、过期实例或命名不一致的数据。观测配置与应用部署流程配合，才能让监控数据与实际运行服务保持同步。
设计有用的业务指标
指标是否有用，取决于它能否帮助回答运维或产品问题。错误日志数量可以帮助发现异常趋势；消息队列客户端可观察发送耗时、消费耗时和处理失败；数据库连接池可用于识别连接耗尽或利用不足；HTTP 请求的数量、响应时间和响应码则能呈现接口健康状况。
采集指标前，可以先问清楚：谁会在什么情况下查看它、异常时希望采取什么动作、统计范围和单位是什么。指标数量过少可能无法定位问题，过多则会增加维护和查询成本。为每个指标定义名称、单位、标签和解释，有助于减少不同开发者之间的理解差异。
读这篇旧实践时的版本边界
这篇文章发表于 2019 年，示例中的 SDK、配置字段、指标术语和 Grafana 面板操作都属于当时的技术环境。Prometheus、Go 客户端库和 Grafana 会持续发展，某些代码或命令可能已经变化。因此它适合帮助读者建立从 SDK 到抓取再到可视化的整体认识，复用具体配置前仍应查阅当前版本文档并在测试环境验证。
hanjm’s blog 还包含其他 Go 和后端工程内容，可从首页及标签归档继续浏览。对刚开始搭建监控链路的开发者，这篇文章提供了一个清晰的模块地图：应用定义指标、抓取端读取目标、服务发现维护目标列表、Grafana 呈现时间序列。理解各部分职责后，再根据当前环境选择合适的 SDK、配置和面板方式。