rust-observability

Rust 可观测性

根据运维问题和故障模式设计遥测。日志解释离散事件，跟踪串联跨边界的工作，指标量化一段时间内的行为，性能分析则用于诊断资源消耗。不要将所有数据发送到所有信号中。

范围与路由

将此技能用于 tracing、订阅器、结构化日志、指标、OpenTelemetry、上下文传播、采样、导出器、请求关联、异步运行时诊断、脱敏和关闭时刷新。

并发正确性请转到 rust-concurrency，HTTP 中间件请转到 rust-web，安全事件策略请转到 rust-web-security，性能分析请转到 rust-performance，依赖项特性请转到 rust-cargo-build。

工作流

1. 从决策和 SLO 入手

列出运维人员必须回答的问题：请求速率和延迟、错误类别、饱和度、队列深度、重试、依赖项健康状况、任务泄漏、资源使用情况和部署标识。选择导出器之前，先定义服务名称、环境、版本、实例属性、负责人、保留期限、访问控制和成本预算。

2. 建立结构化跟踪

对有持续时间且包含嵌套工作的操作使用 tracing span；对在某一时刻发生的事实使用事件。

use tracing::{info, instrument};

#[instrument(skip(payload), fields(job.id = job_id))]
async fn process(job_id: u64, payload: &[u8]) {
    info!(payload.len = payload.len(), outcome = "accepted");
}

• 使用一致的名称和字段来表达领域含义。
• 跳过机密、正文、凭据、原始 SQL 值和大型负载。
• 记录稳定的错误类别和结果，而不是只记录格式化消息。
• 确保在轮询期间进入已插桩的 future；不要跨 .await 错误地持有 span guard。
• 在应用边界配置过滤和格式化，而不是在库内部配置。

阅读跟踪与结构化日志。

3. 设计有界指标

总量使用计数器，当前状态使用仪表，分布使用直方图。使用稳定且低基数的标签记录吞吐量、延迟、错误、饱和度、队列等待时间、重试、拒绝和资源池情况。

绝不要将用户 ID、请求 ID、包含原始路径的 URL、SQL 文本、任意错误消息或无界租户 ID 用作指标标签。根据 SLO 定义直方图的单位和桶。阅读指标与基数。

4. 传播分布式上下文

仅从可信的传输格式中提取远程跟踪上下文，创建服务端或使用者 span，并将当前上下文注入出站请求或消息。谨慎保留跨已派生任务的因果关系；分离的后台工作可能需要链接，而非继承父级。

只有在需要互操作性或厂商中立导出时才使用 OpenTelemetry。检查各信号的成熟度、crate 版本、运行时要求、批处理行为和导出器兼容性。阅读OpenTelemetry 与上下文。

5. 配置管道和关闭流程

• 在进程启动时组合订阅器和层，且仅组合一次。
• 仅通过经过身份验证并经过审计的控制使过滤器可重新加载。
• 限制导出器队列，并定义丢弃或背压行为。
• 使用明确的策略对跟踪进行采样；确保错误和罕见路径可观测，同时避免成功流量成本过高。
• 在服务关闭期限内刷新或关闭遥测提供程序。
• 避免导出器通过同一条已插桩的网络路径递归产生遥测。

6. 验证遥测行为

测试字段名称、级别、错误类别、上下文传播、脱敏、基数、禁用订阅器时的行为、导出器故障、队列饱和和关闭时刷新。使用测试订阅器或内存导出器，不要断言不稳定的格式化行。

在诊断构建中使用 tokio-console 查找长时间轮询、资源等待和泄漏的任务；不要公开其控制端点。阅读运行时与运维。

完成标准

• 将每个信号关联到一个运维问题或 SLO。
• 使用结构化 span 和事件，字段保持稳定并明确进行脱敏。
• 限制指标标签的基数，并定义直方图单位。
• 在受支持的入站、出站和消息传递边界传播跟踪上下文。
• 限制导出器成本、队列、采样和关闭时间。
• 将遥测作为行为进行测试，不与特定文本格式化工具或供应商耦合。

资源

• 跟踪与结构化日志
• 指标与基数
• OpenTelemetry 与上下文
• 运行时与运维
• 执行场景
• examples/golden-observability/：编译后的自定义跟踪层契约。

上游来源

• tracing
• tracing-subscriber
• OpenTelemetry Rust
• metrics
• tokio-console

数据隐私

此技能不会收集、存储或传输用户数据。遥测变更可能会传输生产数据；启用导出器前，请确认授权、目标位置、保留期限、脱敏方式和访问控制。