SuperAPI AI 工具集

rust-observability

编程与开发

查看项目

更新于 10-16 07:14

技能介绍

本技能用于给 Rust 服务添加生产可观测性,由三支柱组成:日志/追踪(tracing + tracing-subscriber)、分布式追踪(tracing-opentelemetry + opentelemetry-otlp)、指标(metrics + metrics-exporter-prometheus)。

主要能力:通过 init_tracing 配置订阅器,按环境选择过滤级别与输出格式——生产环境输出 JSON 供日志聚合(如 ELK、Loki),本地开发用 pretty 格式;用 #[instrument(skip(...), fields(...))] 或 info_span! 手动创建 span 标注函数;用 opentelemetry_otlp 的 SpanExporter 经 with_tonic 与 with_endpoint(如 http://localhost:4317)导出,设置 service.name、service.version 等 Resource,并用 shutdown_tracer_provider 在优雅关闭时刷新;用 TraceContextPropagator 与 axum/tower-http 的 TraceLayer 做 HTTP 上下文传播与提取父 span;用 PrometheusBuilder 安装记录器,在 /metrics 路由通过 handle.render() 暴露指标,记录 counter、gauge、histogram,并按需自定义 histogram 桶。

推荐做法:指标命名遵循 <namespace><subsystem><name>_<unit> 与 snake_case;为每请求生成或透传 x-request-id 并写入 span 与响应头;用 EnvFilter 的 try_from_default_env 读取环境变量。约束包括:禁止 println!/eprintln! 记录日志,禁止记录敏感数据(密码、令牌、PII,用 skip 跳过),保持指标基数有界,优雅关闭时必须刷新,优先用 #[instrument] 而非手动 span。资料还给出 Cargo 依赖版本与 tracing/otel/prometheus/full-observability 特性开关,以及分研究、设计、实现、验证、校验五阶段的检查清单。适用场景为 Rust 后端服务、Web/HTTP 服务与需要跨服务追踪、指标导出的生产系统。限制:具体版本兼容性与运行环境要求请以实际依赖文档为准,资料未提供性能基准数值之外的更多细节。