跳转到内容
PLUMEGO Go 服务显式 wiring 工具包，stdlib 优先。
中文

x/observability Primer

x/observability Primer

Section titled “x/observability Primer”

Beta — API 在 minor 版本内保持稳定。采用前请查看发布策略和扩展成熟度。

当你已经通过 x/* 家族 确认问题属于更广泛的可观测性基础设施，而不是稳定 middleware 已覆盖的传输层基础元语时，打开这一页：Prometheus 导出器、OpenTelemetry wiring、记录缓冲、滚动窗口聚合或 DB 分析助手。

x/observability 是该家族面向应用的规范且唯一入口点。两个下级包——x/observability/ops（受保护的管理员和诊断端点）和 x/observability/devtools（仅调试路由和本地性能分析）——首先通过 x/observability 访问，而不是直接打开。

稳定性与采用

Section titled “稳定性与采用”

稳定 middleware 负责传输层请求观测；x/observability 负责更高层的导出器、缓冲、适配器和诊断。生产中采用 exporter、admin 或 debug API 前，请检查 x/observability/module.yaml、发布策略 和 扩展成熟度。

什么时候从这里开始

Section titled “什么时候从这里开始”
  • 你正在 wiring Prometheus 导出器或 OpenTelemetry 管道（prometheus.go、otel.go）
  • 你正在实现记录缓冲或滚动窗口指标聚合（recordbuffer/、windowmetrics/）
  • 你正在添加 DB 分析或查询洞察助手（dbinsights/）
  • 你正在构建不属于稳定 metrics 根的功能级指标助手（featuremetrics/）
  • 你在扩展测试中需要指标或日志验证的 testkit（testmetrics/、testlog/）
  • 改动涉及下级管理端点（x/observability/ops）或调试路由（x/observability/devtools）— 先在此确认家族归属

什么时候不该从这里开始

Section titled “什么时候不该从这里开始”
  • 改动关于传输层埋点，如访问日志、request-ID 传播、HTTP 指标或分布式追踪 header — 那属于 middleware/accesslog、middleware/requestid、middleware/httpmetrics 或 middleware/tracing
  • 工作是业务指标策略或产品分析逻辑 — 保留在应用代码中
  • 改动是 core bootstrap 关注点
  • 工作是稳定 metrics 根接口 — 那是内核合约，不是适配器

当前仓库里先读哪些文件

Section titled “当前仓库里先读哪些文件”
  1. x/observability/module.yaml
  2. x/observability/observability.go
  3. x/observability/prometheus.go
  4. x/observability/otel.go
  5. x/observability/exporter.go
  6. x/observability/recordbuffer/（如果涉及缓冲）
  7. x/observability/ops/（如果涉及受保护管理端点）
  8. x/observability/devtools/（如果涉及调试路由）

公共入口点

Section titled “公共入口点”

先从这些具体 API 表面开始：

  • observability.NewPrometheusCollector 与 observability.NewPrometheusExporter：接入 scrape endpoint 和 exporter
  • observability.NewOpenTelemetryTracer：服务需要应用层 tracer adapter 时使用
  • recordbuffer.NewCollector 与 windowmetrics.NewAggregator：扩展拥有的缓冲与滚动窗口聚合
  • dbinsights.NewInstrumentedDB 与 dbinsights.NewObserver：数据库查询洞察 helper
  • testmetrics.NewMockCollector 与 testlog.New：需要可观测性断言的扩展测试

更具体的归属例子

Section titled “更具体的归属例子”
这些工作适合留在 x/observability一旦变成这些问题就应移出
Prometheus 导出器 wiring、scrape 端点注册传输层 HTTP 指标中间件 — 那属于 middleware/httpmetrics
OpenTelemetry tracer 和导出器配置分布式追踪 header 传播 — 那属于 middleware/tracing
recordbuffer：高基数指标的缓冲记录写入稳定 metrics 根接口变更
windowmetrics：滑动指标的滚动窗口聚合业务专属产品分析逻辑
dbinsights：查询延迟追踪和慢查询暴露ORM 或数据库驱动内部
featuremetrics：每功能计数器和直方图助手稳定根级别的指标基础元语
受保护管理端点 → 通过 x/observability/ops 访问让 x/observability/ops 成为竞争性家族入口点
仅调试路由和性能分析 → 通过 x/observability/devtools 访问没有显式门控就在生产环境挂载 devtools

为什么单独写这一页

Section titled “为什么单独写这一页”

可观测性同时跨越传输层（稳定 middleware 在此处理）和基础设施层（本家族在此处理）。边界的存在是为了使稳定 middleware 专注于传输基础元语。x/observability 也是守门人：x/observability/ops 和 x/observability/devtools 是下级包——不确认家族归属就直接打开它们会导致边界漂移。

下一步阅读

Section titled “下一步阅读”