x/observability/devtools Primer
x/observability/devtools Primer
Section titled “x/observability/devtools Primer”实验性 — API 兼容性未冻结。采用前请先评估。查看发布策略了解当前成熟度。
当你已经通过 x/observability Primer 确认问题明确属于开发时调试路由时，打开这一页：本地性能分析端点、环境快照 payload、开发指标暴露或 pubsub 调试助手。
x/observability/devtools 是 x/observability 家族内的下级仅调试包。在直接打开本包之前，先在 x/observability 中开始更广泛的可观测性工作。没有显式门控，devtools 绝不能挂载到生产环境。
什么时候从这里开始
Section titled “什么时候从这里开始”- 你正在添加或修改用于本地开发检查的调试路由（
/_debug/...） - 你正在实现用于开发诊断的运行时或配置快照 payload
- 你正在在调试端点暴露开发指标
- 你正在构建本地热重载工作流的环境重载助手
- 你正在添加用于检查进程内主题状态的 pubsub 调试助手（
pubsubdebug/）
什么时候不该从这里开始
Section titled “什么时候不该从这里开始”- 工作是更广泛的可观测性基础设施，如 Prometheus 导出器或 OTel wiring — 从 x/observability Primer 开始
- 改动关于生产环境中的受保护管理端点 — 那属于
x/observability/ops - 工作需要稳定根入口点或 core bootstrap 变更
- 你打算在没有显式开发门控的情况下在生产二进制中挂载 devtools 路由
当前仓库里先读哪些文件
Section titled “当前仓库里先读哪些文件”x/observability/devtools/module.yamlx/observability/devtools/devtools.gox/observability/devtools/devcollector.gox/observability/devtools/pubsubdebug/
更具体的归属例子
Section titled “更具体的归属例子”这些工作适合留在 x/observability/devtools | 一旦变成这些问题就应移出 |
|---|---|
devtools.go：调试路由注册和 handler wiring | 生产管理端点 — 那属于 x/observability/ops |
devcollector.go：收集和暴露运行时快照和配置状态 | 稳定指标或日志根接口变更 |
| 本地热重载工作流的环境重载端点 | 生产配置管理或运行时配置 API |
pubsubdebug：本地开发期间检查进程内 broker 状态 | 生产 broker 监控或运营诊断 |
为什么单独写这一页
Section titled “为什么单独写这一页”调试工具在开发中有价值，但在生产中危险。x/observability/devtools 是仅调试路由的显式归属，使它们无法意外迁移到 x/observability/ops、x/observability 或 core。不变量是按需挂载：devtools 路由必须在仅限开发的 wiring 路径中显式注册，永远不通过 package init 或自动发现。