diff --git a/10-prd/behavior/observability.md b/10-prd/behavior/observability.md index a5a9598..3390dd6 100644 --- a/10-prd/behavior/observability.md +++ b/10-prd/behavior/observability.md @@ -16,6 +16,10 @@ 历史成功 Job 没有记录时,保留其真实业务状态和时间,并说明没有观测记录;不得根据状态生成看似当时采集的日志。切换后端不会自动迁移或删除历史,界面说明只查询当前选中的存储。 +Job 详情分别呈现已保存的任务信息和查询到的诊断记录。在 Job 记录仍保存期间,提交方退出后,其他已准入 Peer 仍能通过该记录确认提交已保存,并查看当前状态及已保存的创建、开始和结束时间。提交诊断的采集与存储可能失败,详情中的提交事实直接取自 Job,诊断数量和时长概况只统计实际返回的记录。 + +Job 身份决定诊断的关联对象,查询时间窗决定本次读取的范围。详情可用任务时间定位初始窗口,并为生产者时钟差留出搜索余量。用户能够查看和调整实际起止时间,包括过去的绝对时间窗。长任务采用部分窗口时,页面说明当前只覆盖部分生命周期。单次查询宽度、返回数量上限和后端保留期分别表达,诊断缺项的原因需要相应证据支持。 + ## 范围与演进 基建和视图围绕同一记录、过滤、关联和错误语义演进。首次交付覆盖结构化日志、运行事件和操作摘要;标准分布式 Trace、指标导出仍可作为独立能力使用。操作摘要不冒充完整 Span 树;抽样或有界查询不承诺全量指标、账单、告警或确定性回放。 diff --git a/20-product-tdd/observability-contract.md b/20-product-tdd/observability-contract.md index 3e91341..ec9ff5d 100644 --- a/20-product-tdd/observability-contract.md +++ b/20-product-tdd/observability-contract.md @@ -100,10 +100,16 @@ Usage 以 provider 实际返回为依据,覆盖流式结束阶段。未提供 成功领取 Job 后记录开始,完成、失败、超时、取消记录实际终态。观测失败不能推翻数据库已提交的状态,不能把没有记录视为没有执行。采集仅覆盖实际经过已接入实现的执行;旧 Peer 或未采集的信号允许缺失。 +Job 提交的持久化结果由数据库 Job 记录拥有,详情从其 `created_at`、当前状态及已保存的 `started_at`、`closed_at` 呈现业务事实。`job.submitted` 等诊断事件独立按有界采集机制写入。提交方退出或诊断写入失败后,其他 Peer 仍可读取已保存的 Job。诊断摘要只使用后端实际返回的 `records`,Job 信息由其持久记录单独呈现。 + +观测 `timestamp` 使用生产者记录的时间,Job 的数据库时间与各 Peer 的墙钟可能存在偏差。Job 详情的默认时间窗是搜索起点,应用为初始查询提供可解释的余量并支持用户调整。31 天约束每次 `[since, until)` 的宽度,过去的有效绝对窗口同样可以查询。存储保留期属于部署配置,具体记录是否仍可读取以所选后端的实际查询为准。 + ### Web 消费 全局工作区和 Job 详情复用同一观测查询接口。过滤、关联详情、操作时间线和当前窗口摘要不包含供应商分支。状态面板展示当前存储、配置/能力、历史说明及读取故障;加载、空、错误和截断分别呈现。外部完整 Trace/指标系统可通过已配置诊断入口访问,不用当前窗口的操作摘要假装实现完整 APM。 +详情显示已保存的提交事实,以及诊断所用的后端、起止时间和筛选条件。当前窗口只覆盖部分生命周期时,页面说明覆盖范围,并提供调整时间范围的入口。返回记录过多的 `truncated` 提示继续由查询结果驱动。窗口内缺少某个事件时,界面描述本次查询范围内的结果,业务状态继续由 Job 记录提供。 + ### 变更验证 内置与外部后端使用同一合同样例核对记录、过滤、时间、关联、截断和错误;覆盖配置缺失、未知选择、外部不可用、目标切换和资源关闭。局部模拟传输只证明编解码与控制流,真实持久化、部署路由和跨 Peer 数据读取需要单独的端到端证据。旧合同“始终并行保留 PG writer”的要求由本节替代;数据保留及既有业务协议权限不变。