可观测性

可观测性

v1.0.x · 已更新 2026-07-07

AiHummer 可观测性已经 两个表面: 该网关充当一个 普罗米修斯 GET /metrics 端点，您可以抓取基本内容，并且它可以选择性地 通过 OTLP 推送遥测 到你配置的 OpenTelemetry 端点。抓取 /metrics 用于基线监控；对于跟踪和丰富的指标，将 AiHummer 指向您的 OTLP 收集器，并使用捆绑的 Grafana 仪表板可视化数据。

[!NOTE] pprof（/debug/pprof) 是不暴露。

普罗米修斯 `/metrics` 端点

GET /metrics 以文本格式向 Prometheus 提供指标，无需额外设置。只公开非敏感的测量值——构建信息、进程运行时间和运行时、数据库连接池状态以及就绪测量值；无租户数据，无机密信息，无每请求标签。对于追踪和丰富指标，请使用 OTLP 推送。

OTLP 推送

设置一个变量以开启遥测：

# gateway.env — export telemetry to your OTLP collector
AIHUMMER_OTEL_ENDPOINT=http://otel-collector:4317

与 AIHUMMER_OTEL_ENDPOINT 设置后，网关会将遥测数据推送到该收集器。从那里，将其路由到你的后端（Tempo、度量存储、日志）并进入 Grafana。

恐慌与错误处理

错误报告 从不发送到外部任何地方：网关不包含任何外部错误追踪器客户端，也没有任何外部 DSN——有关您的错误的数据永远不会离开您的边界。

尽管如此，对恐慌的抵御能力仍然是完整的：

HTTP 处理器中的恐慌会变成一个普通的错误响应（一个携带 AIH-… 信封的 500）——进程不会死掉，并继续处理其余请求；
后台 goroutine 中的恐慌同样会被恢复，不会让网关宕机。

这两种情况都会进入结构化日志——在日志页面（见下文）或通过 journalctl 查看。

管理员界面中的实时日志

管理员界面的日志页面是网关日志的实时尾部：每隔几秒会自动拉入新行，当你在底部时会自动滚动。工具栏有一个 直线搜索 和一个 电平滤波器 (全部 / 错误 / 警告 / 信息 / 调试)。其他几个页面（仪表板、会话、频道）也会自动刷新，长列表（审计、变更、通知等）通过“显示更多”按钮逐页加载。

每个服务的完整日志仍然保存在 systemd 中 — aihummer logs [unit] 或者 journalctl -u aihummer-gateway.

Grafana 仪表板

随发行版提供现成的 Grafana 仪表板。将它们导入到你的 Grafana 实例中，以获取操作视图，而无需从零构建面板。

看什么

这些是告诉你系统健康且周转顺畅的信号：

信号	为什么这很重要
响应延迟	代理回合的端到端响应性
错误率	失败的转弯/请求——问题的第一个迹象
交付安排	回复是否实际到达频道
待交付	未送达回复的积压；持续增长意味着交付停滞

持续上升 待处理或多次失败的交付 这是交付积压的最清晰的早期警告——在推出和事件期间注意观察它。

系统端点

除了 OTLP 外，网关还提供一些小型 HTTP 端点，可用于探测、时钟和客户端诊断：

方法	终端	目的
`GET`	`/metrics`	Prometheus 指标（构建、运行时、数据库连接池、就绪状态）
`GET`	`/healthz`	活体 + 版本
`GET`	`/readyz`	就绪（检查 Postgres；如果宕机返回 503）
`GET`	`/v1/ping`	轻量级可达性检查
`GET`	`/v1/time`	服务器时间
`POST`	`/v1/client-log`	摄取客户端日志事件

健康和就绪探针的详细内容在以下部分中进行了介绍 systemd 和健康检查.

接下来去哪儿

探针和生产前的飞行检查清单： systemd 和健康检查.
在滚动升级期间要观看的内容：升级政策.

普罗米修斯 /metrics 端点