From 325ef51790ea37ad4f355aeccb45311f231077db Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Thu, 5 Nov 2026 16:46:59 +0800 Subject: [PATCH 1/2] =?UTF-8?q?docs(observability):=20=E6=98=8E=E7=A1=AE?= =?UTF-8?q?=E6=8C=81=E4=B9=85=20Job=20=E4=BA=8B=E5=AE=9E=E4=B8=8E=E8=AF=8A?= =?UTF-8?q?=E6=96=AD=E6=9F=A5=E8=AF=A2=E7=AA=97=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 明确提交已保存的事实由持久 Job 提供，诊断摘要使用实际返回记录 - 说明生产者时钟偏差、可调整历史窗口及单次查询宽度语义 - 规定长任务窗口和诊断缺项的展示要求 --- 10-prd/behavior/observability.md | 4 ++++ 20-product-tdd/observability-contract.md | 6 ++++++ 2 files changed, 10 insertions(+) diff --git a/10-prd/behavior/observability.md b/10-prd/behavior/observability.md index a5a9598..e095ed9 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..706b8a5 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”的要求由本节替代；数据保留及既有业务协议权限不变。 From e3e3e9d5c00bca01202ec8c0dafe60d796dd6321 Mon Sep 17 00:00:00 2001 From: Lan_zhijiang Date: Thu, 5 Nov 2026 16:50:37 +0800 Subject: [PATCH 2/2] =?UTF-8?q?docs(observability):=20=E5=87=86=E7=A1=AE?= =?UTF-8?q?=E6=8F=8F=E8=BF=B0=E5=8E=86=E5=8F=B2=E7=AA=97=E5=8F=A3=E7=9A=84?= =?UTF-8?q?=E7=94=9F=E5=91=BD=E5=91=A8=E6=9C=9F=E8=A6=86=E7=9B=96=E8=8C=83?= =?UTF-8?q?=E5=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 10-prd/behavior/observability.md | 2 +- 20-product-tdd/observability-contract.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/10-prd/behavior/observability.md b/10-prd/behavior/observability.md index e095ed9..3390dd6 100644 --- a/10-prd/behavior/observability.md +++ b/10-prd/behavior/observability.md @@ -18,7 +18,7 @@ Job 详情分别呈现已保存的任务信息和查询到的诊断记录。在 Job 记录仍保存期间，提交方退出后，其他已准入 Peer 仍能通过该记录确认提交已保存，并查看当前状态及已保存的创建、开始和结束时间。提交诊断的采集与存储可能失败，详情中的提交事实直接取自 Job，诊断数量和时长概况只统计实际返回的记录。 -Job 身份决定诊断的关联对象，查询时间窗决定本次读取的范围。详情可用任务时间定位初始窗口，并为生产者时钟差留出搜索余量。用户能够查看和调整实际起止时间，包括过去的绝对时间窗。长任务采用部分窗口时，页面说明更早阶段位于窗口之外。单次查询宽度、返回数量上限和后端保留期分别表达，诊断缺项的原因需要相应证据支持。 +Job 身份决定诊断的关联对象，查询时间窗决定本次读取的范围。详情可用任务时间定位初始窗口，并为生产者时钟差留出搜索余量。用户能够查看和调整实际起止时间，包括过去的绝对时间窗。长任务采用部分窗口时，页面说明当前只覆盖部分生命周期。单次查询宽度、返回数量上限和后端保留期分别表达，诊断缺项的原因需要相应证据支持。 ## 范围与演进 diff --git a/20-product-tdd/observability-contract.md b/20-product-tdd/observability-contract.md index 706b8a5..ec9ff5d 100644 --- a/20-product-tdd/observability-contract.md +++ b/20-product-tdd/observability-contract.md @@ -108,7 +108,7 @@ Job 提交的持久化结果由数据库 Job 记录拥有，详情从其 `create 全局工作区和 Job 详情复用同一观测查询接口。过滤、关联详情、操作时间线和当前窗口摘要不包含供应商分支。状态面板展示当前存储、配置/能力、历史说明及读取故障；加载、空、错误和截断分别呈现。外部完整 Trace/指标系统可通过已配置诊断入口访问，不用当前窗口的操作摘要假装实现完整 APM。 -详情显示已保存的提交事实，以及诊断所用的后端、起止时间和筛选条件。生命周期跨越单次窗口时，页面提示未包含的更早阶段，并提供调整时间范围的入口。返回记录过多的 `truncated` 提示继续由查询结果驱动。窗口内缺少某个事件时，界面描述本次查询范围内的结果，业务状态继续由 Job 记录提供。 +详情显示已保存的提交事实，以及诊断所用的后端、起止时间和筛选条件。当前窗口只覆盖部分生命周期时，页面说明覆盖范围，并提供调整时间范围的入口。返回记录过多的 `truncated` 提示继续由查询结果驱动。窗口内缺少某个事件时，界面描述本次查询范围内的结果，业务状态继续由 Job 记录提供。 ### 变更验证