外观
可观测性总览
平台的可观测性由四条线组成:指标、日志、告警三条信号线,加审计哈希链这条信任线。前者的代码基座是 platform-obs(五个模块:metrics、tracing_setup、audit、audit_verify、health),审计链的巡检执行者是 svc-operator。当前形态是自采的 Prometheus 文本指标与 tracing JSON 日志,OTLP 导出与独立 Trace 后端尚未接入,跨信号关联靠 trace_id 字段而非 TraceID 索引。
信号流全景
图里有一条容易忽略的回线:svc-operator 本身是指标的生产者,它巡检数据库里的审计链,把断链结论写回指标系统,再由 vmalert 消费。这条从数据库事实到指标的通路让审计完整性进入了与其他信号同一套的告警体系,不需要独立的监控系统。
各信号的来源与去处
| 信号 | 产生 | 暴露 | 采集 | 消费 |
|---|---|---|---|---|
| 指标 | metrics::global 七个平台族 + 各域自注册族 | /metrics(全部服务) | vmagent(pod 注解) | VictoriaMetrics、Grafana、vmalert |
| 日志 | tracing_setup::init(JSON、EnvFilter、RFC3339 UTC 秒精度) | stdout | Promtail / Vector(部署面职责) | Loki(部署面) |
| Trace | 网关 trace_mw 生成或透传 traceparent | 无导出器 | 无 | 靠 trace_id 在 problem+json、审计事件、日志三处同值反查 |
| 审计 | AuditEvent::seal(sha256 链) | 各服务 PG 的 audit_events 表 | 无(同事务写入) | svc-operator 巡检 + 合规证据 |
源码侧与部署侧的职责边界要分清:进程内产出(指标注册表、日志格式、审计写入)在源码;采集与存储后端(vmagent、VictoriaMetrics、Loki、Grafana 的部署与保留策略)在部署面,源码只提交 vmalert 规则、alertmanager 路由与 Grafana 面板定义(监控部署目录)。
trace_id 是当前的关联键
OTel 导出链路未接,跨信号关联的现实手段是 trace_id 同值出现在三处:
- 网关
trace_mw(svc-gateway 的 middleware.rs)从请求头读 W3Ctraceparent,缺失则生成一个同形态的值(两段 UUIDv7 simple 形态拼成00-{trace}-{span}-01),并把 trace 段回写到响应头x-trace-id。客户端报障时提供这个头即可反查。 - problem+json 错误体携带
trace_id(错误码体系见 platform-core 的 error.rs)。 - 审计事件有独立的
trace_id字段,网关与各服务的结构化日志按各自打点携带。
排障动作因此很直接:拿到 x-trace-id 后,在 Loki 里按 trace_id 检索日志、在审计查询面按 trace_id 检索事件,三条线对时间轴即可还原一次请求的完整路径。
W3C traceparent 的常量定义已备于 platform-grpc,属于传播已就绪、导出未接线的状态;正式的采样策略(头部采样 1%、慢请求与错误强制保留、编排实例全采)要在 OTel SDK 接入后才能落地。当前没有全局采样这回事,不要在排障预期里假设某条日志被采样掉了:日志进不进 Loki 只取决于部署面的采集配置。
健康面三件套
platform-obs 的 health.rs 提供三个 handler,各服务的 HTTP 面按需挂载:
| 端点 | 行为 | 用途 |
|---|---|---|
/healthz | 恒 200,响应体 ok | 存活探针:进程在即活,不查依赖 |
/ready | 依赖探测全过 200 {"status":"ok"};有失败项 503 {"status":"unavailable","failed":[...]} | 就绪探针:failed 数组即失败依赖清单 |
/metrics | 渲染进程级注册表,Content-Type text/plain; version=0.0.4; charset=utf-8 | 指标抓取 |
readiness 的语义边界值得强调:探测清单由各服务自己的 ready handler 决定(PG 池、总线消费面等,各服务口径不同),ready_response 只负责渲染。排障时看到 503,先看 failed 数组里的依赖名,再去看对应依赖的专项告警(例如 PG 层面的 PgPrimaryUnavailable)。
healthz 与 ready 的分工是刻意的:存活探针失败触发重启,就绪探针失败只是摘除流量。如果把依赖检查放进 healthz,一次 PG 抖动会让全部 Pod 被重启,放大故障;分开后 PG 抖动只表现为服务暂时不接流量。
从一次请求看信号的产生
以北向一次写请求为例,四条线各自在哪个环节亮起:
- 网关
trace_mw生成或透传 trace_id,回写响应头;请求量与时延在响应返回时打点(指标线); - 认证、限流、授权各中间件按结果留结构化日志(日志线);
- 变更类操作经审计埋点构造事件,随业务事务落库并 seal 进哈希链(信任线);
- 抓取、评估、巡检周期性消费以上产物,异常时告警触达值班(告警线)。
分进程与 all-in-one 两种部署形态的暴露面差异:分进程形态每个服务各自挂 /metrics(operator 在 9101),vmagent 按 pod 注解逐个抓取;all-in-one 形态全部服务并入一个进程,网关 /metrics 输出的是同一注册表(operator 不再单独监听),抓取面收敛为一个端点。指标内容两种形态一致,区别只在抓取拓扑。
当前形态的边界
如实列出这套体系现在不做什么,避免读者按完整 OTel 栈的预期排障:
| 项 | 现状 | 影响 |
|---|---|---|
| OTLP 导出 | 未接(规划 M4) | 无独立 Trace 后端,跨信号靠 trace_id 字段反查 |
| 日志采样 | 无 | 日志量由打点纪律与 filter 控制,不由采样控制 |
| 级别热更 | 无 | 调整级别需重启进程 |
| Loki / VM 保留策略 | 部署面配置 | 交付物料不含,接手部署先确认保留期 |
| 基础设施指标 | 部署面 exporter | up、pg_、nats_、kube_* 不在假绿守卫范围 |
这些边界与 platform-obs 的 lib.rs 的模块注释口径一致:当前形态是进程内 JSON 结构化日志加进程外采集,采样与导出策略待 OTel SDK 接入后落实。
读数入口
- 面板:Grafana
rustsvc-overview(uid 同名),数据源 VictoriaMetrics。 - 指标目录:reference/metrics,含全部平台族与瓦片族的标签语义与告警关联。
- 排障按现象走排障中心。
各分页的主题划分:
| 页 | 主题 | 适合谁 |
|---|---|---|
| 日志 | 输出形态、时间戳实现、级别约定、排障检索键 | 服务开发者、值班 |
| 指标 | 注册表机制、桶与基数、PromQL 口径、假绿防线 | 服务开发者、面板维护者 |
| 告警体系 | 14 条规则、分级路由、runbook 联动、operator 巡检 | 值班、运维 |
| 审计哈希链 | canonical 形态、锚点串行化、断链检测、合规映射 | 安全与合规、存储设计者 |
| OTLP 可观测双轨 | Prom pull 主轨与 OTLP 推送副轨的分工与门控 | 平台接入者、SRE |
相关页面
- 日志 · 指标 · 告警体系 · 审计哈希链 · OTLP 可观测双轨
- svc-operator 运维任务 · Runbook 索引