机器人可观测性是指能够从发出的证据重建内部软件执行和外部物理行为的能力。显示节点存活的屏幕无法解释为何移动操作员选择错误对象、使用陈旧变换并进入恢复状态。
日志记录事件，指标汇总测量，追踪跨组件工作。机器人还需要传感器和执行器证据、时钟同步质量、任务身份和配置沿革，因为物理事件涉及跨界面设备、车队服务和人工操作。
本指南应与 机器人延迟预算指南 及 数据集谱系指南一起使用。收集必须遵守网络安全、隐私、保留和安全约束。
围绕问题和事件设计可观测性
从决策开始：哪个任务失败了，哪个命令到达执行器，感知输入有多久，运行了哪个配置，以及延迟或状态分歧从哪里开始。每个问题定义证据、相关性和保留需求。
对从任务分配到规划、推断、控制、设备响应和任务结果的关键路径进行仪器化。避免在没有调查用例和资源预算的情况下收集所有可能的字段。
给日志、指标和追踪分配不同的工作
结构化日志捕捉离散事件及其上下文。度量汇总值随时间变化，用于警报和趋势检测。追踪表示操作作为组件间的相关跨；这些单独无法替代原始物理证据。
官方 的OpenTelemetry信号文档 将跟踪、指标、日志和行李列为支持的类别。地图机器人概念应谨慎而非假设云服务语义规范自动适用于运动和硬件。
| 信号 | 最好的问题 | 机器人示例 | 误用则失效 |
|---|---|---|---|
| 日志 | 发生了什么事件 | 安全停止理由 | 自由文本无法关联 |
| 度规 | 多少或多频繁 | P95指挥年龄 | 原始ID的基数爆炸性 |
| 追踪 | 时间去了哪里 | 任务到执行跨度 | 缺失上下文会断开链条 |
| 录音 | 实际发生了什么 | 图像、关节与命令 | 存储与隐私过载 |
| 配置快照 | 具体是什么 | 模型、地图与校准 | 事件无法复制 |
跨边界传播一个操作身份
创建具有明确生命周期的车队、机器人、任务、任务、尝试和恢复标识符。在服务呼叫、队列和设备命令之间，携带跟踪和跨越上下文，同时在重试工作时保持物理事件身份可见。
W3C Trace Context 建议 标准化了分布式上下文的traceparent和tracestate。在兼容接口使用其规则，并为现场总线、 ROS消息和离线录制定义显式映射。
把时钟同步质量纳入每一个延迟申报中
不同时钟的时间戳在不确定偏移、漂移和不确定性的情况下不能安全减去。记录时钟源和同步状态，并使用单调时间处理局部时钟修正可能跳跃的时段。
当同步下降时，保持事件顺序和不确定性，避免发布虚假的精确延迟。关联传感器暴露、消息到达、回调开始、推理完成、命令应用和测量运动。
使用结构化日志和稳定模式
包括事件名称、严重度、时间戳和时钟、操作ID、组件和版本、机器人状态、原因代码以及有界诊断字段。保留人类可读的文本作为解释，而非唯一机器可查询的值。
OpenTelemetry的 日志规范 支持通过TraceId和SpanId进行相关。保留原始设备错误代码和映射版本，以确保归一化不会抹除证据。
控制度量标签与基数
根据测量到的行为使用计数器、计量器和直方图。指标可以总结故障率、队列深度、命令年龄、推断延迟、控制截止时间未达、电池状态和干预持续时间。
当前 的OpenTelemetry指标指南 警告，唯一属性组合会增加内存成本，并描述了SDK的基数限制。不要在每个度量系列上放置原始任务、用户或对象标识符；将范例或有界标签与详细的跟踪和日志连接起来。
追踪异步机器人工作与重试
任务可能扩展为感知、规划、地图、策略和设备调用，然后通过队列或离线边缘链路继续。嵌套工作使用父子跨，当因果工作不是单一同步呼叫树时使用跨链路。
记录入队和脱排队时间、重试次数、超时所有者和结果。 OpenTelemetry的 跟踪文档 解释了跨度、上下文传播、事件和链路；应用保留失败和代表成功操作的采样规则。
在遥测数据旁保留物理证据
针对特定事件，获取传感器帧、关节状态、命令、变换、安全事件和操作员操作，并获得同意和存储控制。保留单元、协调帧、序列化以及信息 QoS 或丢弃信息。
ROS 2 rosbag2 文档已针对 Rolling 发行版进行了版本管理；固定部署所用的发行版和存储插件版本。没有时钟、配置和事件 ID 的 bag 文件仍然难以解释。
快照软件、模型、地图和校准谱系
将构建ID、容器或包摘要、模型和数据集谱系、地图、工具、校准、控制器参数和特征标志附加到机器人资源或事件包上。不要依赖可变标签的最新版本。
使用 机器人数据集谱系工作流程，将学习到的工件与其输入连接起来。保留更新和回滚事件，避免将混合车队分析为一个配置。
构建一个支持反证的事件包
事故记录应包含时间线、受影响配置、日志、度量窗口、痕迹、选定的物理记录、操作员陈述、候选原因以及与每个假设相矛盾的证据。根本原因不应从第一个令人警戒的图表中选择。
将确认的反复案例与 故障挖掘指南 连接起来，同时将培训选择与运营裁定和安全报告分开。
预算遥测、安全、隐私及运行退化
按信号类别设置收集速率、本地缓冲、上传优先级、保留和编辑。摄像头、音频、精确位置和工作人员标识符可以带来隐私和安全暴露；保护访问并证明删除行为。
可观测性不应扼杀控制或安全任务。测试断开操作、存储耗尽、集电器故障和日志风暴。机器人应保持有界临界环缓冲，并根据其运行安全设计继续或停止。
发布可观测性验收规范
保留事件问题、信号模式、标识符寿命、上下文传播、时钟同步质量、采样、基数预算、缓冲区和保留规则、访问控制、配置沿袭和重放测试。
仔细审查，请进行以下检查。
评估“机器人可观测性：日志、指标与分布式追踪”时，还应保存模型版本、机器人配置、标定文件、测试日期和全部试验记录。把成功、失败、恢复与人工介入放在同一份数据中，才能区分模型能力、系统接口和现场流程造成的差异。
成本评估除了设备与算力，还要记录数据采集、工程调试、安全措施、维护、停机和人员培训。只有把这些持续投入与单位成功任务的价值比较，才能判断方案是否适合扩大。
上线后仍要持续检查分布变化、传感器漂移、机械磨损和人工接管原因。监测结果应能触发降级、停止与重新验证流程，并为下一轮数据采集和模型更新留下可追溯记录。
最终结论应明确写出已知限制、尚未验证的场景和下一项可证伪的实验，使后续团队能够沿着证据继续推进。
实际项目还应指定数据、模型、控制器和安全流程的负责人，并预先定义回滚条件。责任边界、审批记录与变更日志越清楚，故障发生后越容易停止扩散、定位原因并安全恢复。
| 验收测试 | 注射状态 | 所需证据 | 失败 |
|---|---|---|---|
| 相关性 | 跨军种重试 | 一任务与尝试链 | 重复或损坏的ID。 |
| 时间安排 | 时钟偏移与漂移 | 合格期限或不确定性 | 假延迟 |
| 采样 | 罕见的临界故障 | 保留迹束和物理丛 | 头部取样滴剂盒 |
| 资源 | 网络与磁盘压力 | 有界控制影响 | 遥测干扰机器人 |
| 重赛 | 已知事件 | 时间线和配置可复制 | 仅仪表盘诊断 |
- 追踪一个任务从派遣到实际结果。
- 记录时钟源、偏移和不确定性。
- 避免指标有界限且详细的ID出现在标签中。
- 将遥测数据与精确软件和校准版本连接。
- 证明在网络丢失和存储压力下的事件捕获。
常见问题
原木足够让机器人可观测吗？
不。日志需要指标、痕迹、物证、时钟同步质量和配置上下文来重建许多事件。
机器人ID应该作为一个公制标签吗？
有界车队标签可能是合理的，但高基数标识符需要明确的成本分析，通常应放在跟踪或日志中。
跟踪时间戳能证明端到端延迟吗？
只有当时钟和传播边界被限定时；否则报告局部时长和同步不确定性。
每一次成功的任务都应该被完整记录吗？
通常不会。使用基于风险的抽样、总结和有界缓冲区，同时保留关键失败和代表性成功。
可观测性能取代安全监控吗？
不。它支持诊断和证据；经过验证的安全功能必须独立于普通遥测数据的可用性。
事件-重建证据边界
机器人可观测性在团队能够重建物理事故、识别准确配置并测试相互竞争的解释而不影响控制、安全、隐私或车队运营的情况下取得成功。