|
| 1 | +# 跨 Peer 可观测性契约 |
| 2 | + |
| 3 | +本契约定义 InKCre 各 Peer 共同消费的观测身份、传播、持久 Job 因果关联及数据边界。它描述实现应满足的行为，不单独证明当前运行版本已具备这些能力。各 Unit 拥有采集实现，部署 owner 拥有采集出口、存储、查询与保留；SDK 版本、配置、后端限制和验收证据留在相应实现或部署文档。 |
| 4 | + |
| 5 | +新增遥测必须由每个 Peer 的本地配置显式启用，缺省关闭；共享部署配置只描述身份和目的地，endpoint 或凭据存在不能自动开启。关闭时不初始化新增采集/导出，不新增 Trace Context 注入、提取或 Job carrier 捕获，仍保持现有日志与业务行为。开启也不自动替换、停用或桥接既有日志 writer；默认 PostgreSQL 日志及按 Job 查询继续可用。 |
| 6 | + |
| 7 | +本地开关在进程启动或客户端连接重新初始化时生效；首版不承诺热切换。开启所需配置不足时报告遥测初始化问题，但不使业务 readiness 失败；关闭不能删除已有日志或持久 carrier。 |
| 8 | + |
| 9 | +## 权威与身份 |
| 10 | + |
| 11 | +一个 deployment 保持一个 owner 上下文，已准入 Peer 平等参与。Peer 可以直接操作共享数据库，也可以同步委派能力；观测路径不能强制所有业务绕经某个中心 Peer。[系统状态与权威](system-state-and-authority.md)继续拥有业务 authority。 |
| 12 | + |
| 13 | +遥测用于解释已观察的运行，不决定 Job、Agent、图谱或结果的状态。采样、丢失、过期和接收顺序都不能变成业务成功、重试、执行恢复或证据完整性的依据。采集出口与观测后端不可用不应阻止应用就绪或改变业务结果；采集需有界，丢弃需可观察，关闭需有时限。 |
| 14 | + |
| 15 | +部署标识、Peer 标识、运行实例与业务 ID 各有意义。部署配置 owner 提供稳定、非秘密的观测部署标识，同一部署的 Peer 与可选采集转发组件使用一致归属；不从凭据、数据库地址或观测产品的项目 ID 派生。重启与原部署恢复保持标识，独立 preview、克隆或新 owner 的部署分配新标识。配置尚不可用的记录可缺少该关联，不能伪造身份或以此阻止启动。 |
| 16 | + |
| 17 | +共享部署配置使用 key `inkcre.observability`、schema `inkcre.observability.v1`；value 含 `deployment_id` UUID，以及可选、无凭据的 `otlp_http_endpoints` 对象与 `diagnostics_url`。出口对象按需声明 traces、logs、metrics 的完整 OTLP/HTTP URL；本地启用后缺省信号仍不导出，不要求所有信号共享一个 base URL；共享 value 不携带启用开关。部署启用步骤仅在缺失时创建身份，Peer 不各自生成；服务端私密采集凭据仅从运行配置提供，不进入客户端；客户端直连需使用适合其公开环境的受限写入能力，否则经过受控转发。凭据不进入该非秘密配置。各 Unit 注册和读取同一 schema；关闭的 Peer 不为新增遥测读取配置或初始化身份，开启时配置尚不可用只暂停新增遥测。 |
| 18 | + |
| 19 | +Peer 复用现有身份，运行实例区分进程或客户端运行期，Job、Thread、ToolCall 与实体保留业务 ID。Trace/Span ID 由标准 SDK 管理，不能用业务 ID 替代。可变业务 ID 适合日志与 Trace 关联，不进入无界指标标签。资源属性用于筛选和诊断，不提供认证或权限证明。 |
| 20 | + |
| 21 | +## 同步传播 |
| 22 | + |
| 23 | +开启的 Peer 在同步调用中使用标准 W3C `traceparent`/`tracestate`，由所选 OpenTelemetry propagator 负责解析、版本兼容与注入。应用拥有传播目标与 carrier 容量边界，不自行维护 W3C 解析器。自动与手动采集的注入责任应唯一，实际调用使用当时的上下文。 |
| 24 | + |
| 25 | +缺失、语义无效或未采样的上下文不改变认证、业务响应、能力选择或执行结果。Trace 解析失败不成为普通 HTTP 业务请求的拒绝理由；不打印原始非法 carrier 作为诊断。同步委派继续遵守[Peer 能力契约](semantic-retrieval-and-peer-capabilities.md)，尤其不能因遥测失败重放结果未知的调用。 |
| 26 | + |
| 27 | +传播目标限定在配置的部署边界。对外部模型、Source 或其它服务，默认观察本地客户端调用，不自动携带内部业务身份、上下文或任意 baggage。浏览器、原生 Peer 与进程内 Extension 都遵守此规则；客户端 span 不冒充尚未采集的 PostgREST 或数据库服务端执行证据。 |
| 28 | + |
| 29 | +## 持久 Job 的因果关联 |
| 30 | + |
| 31 | +Job 的提交和执行可以属于不同 Peer、进程与时间段。公共持久协议提供可选、受限的提交 Trace Context，由开启的创建方在创建 Job 的同一事务中保存；关闭的创建方不捕获该信息并保持缺省 NULL。它属于提交事实，领取和关闭不能将其改写成执行上下文。公共字段为 `submission_traceparent`、`submission_tracestate`，均为可选字符串、缺省 NULL、各最多 512 UTF-8 bytes；数据库协议 owner 交付约束、迁移与各语言投影，不混入 handler 的业务参数或可变执行状态。 |
| 32 | + |
| 33 | +512 bytes 是应用持久化容量，不是 W3C tracestate 的全局最大值。创建方保存 SDK 注入的 carrier，超限 optional tracestate 在写入前整体省略并记录有界原因，保留有效 traceparent；不截断成员、不打印原值、不因观测状态重试业务写入。直接输入仍遵守普通类型和容量约束。 |
| 34 | + |
| 35 | +Python、浏览器直写及其它直接数据库生产者采用同一提交语义。HTTP 创建入口从当前标准上下文捕获，不要求旧创建 body 接受新遥测字段。Cron 在实际创建一次 Job 时捕获该次发生的上下文，不永久继承最初创建 Cron 的请求。 |
| 36 | + |
| 37 | +开启且成功领取的执行器建立独立执行 trace，用 Span Link 连接有效的提交上下文，并在诊断记录中保留同一 Job ID。领取失败不记成实际执行。没有 carrier 的旧 Job 仍可执行；通过普通结构约束但 W3C 语义无效的 carrier 只失去因果 link，不使持久 Job 挂起。关闭的执行器不产出新增 span，但领取和关闭必须保留行中已有 carrier。不同 Peer 的开关可以不同，因而允许提交或执行 Trace 缺失，不影响业务执行。查询可始终按 Job ID 关联，不以提交 trace 仍在保留期内为前提。 |
| 38 | + |
| 39 | +普通字段的类型、允许表面和大小边界仍有效；观测容错不意味着接受任意输入。可选字段不自动授予跨版本运行能力。生产者与执行器必须满足[Peer 数据库运行契约](peer-database-runtime-contract.md)的准入要求，交付明确支持的 runtime/schema 组合与顺序；禁止通过写失败后重放 Job 来探测兼容。Job 的领取、取消、终态、timeout 和 Cron 发生语义仍由[知识能力契约](knowledge-capability-contract.md)拥有。 |
| 40 | + |
| 41 | +现有 PostgreSQL 日志及其按 Job 查询能力持续保留；新增后端是按需启用的诊断增强，开启/关闭均不自动停旧 writer、搬迁历史、删除表或改变原日志关联 ID。新查询通过不构成退役旧日志的授权。 |
| 42 | + |
| 43 | +## AI 诊断与结果证据 |
| 44 | + |
| 45 | +模型、embedding、Agent turn、工具调用、检索、Peer 调用和最终结果通过已有业务身份关联。检索候选、实际读取与最终引用或图谱写入是不同事实；某输入与输出存在关联，不足以证明模型依据了该内容或答案正确。 |
| 46 | + |
| 47 | +Usage 以 provider 实际返回为依据，覆盖流式结束阶段。未提供、明确为零和非零必须保持可区分；后端估算或补值不能冒充观测事实；允许用最少的字段来源元数据保持区别，缺失标记不作为真实用量参与聚合。成本估算附有价格版本与币种，并与 provider 账单区分；采样 Trace 的费用总和不是完整账本。GenAI 语义约定在实现中固定采用的修订，升级时验证消费兼容。 |
| 48 | + |
| 49 | +短期 Trace 可采样、丢失或过期。需要长期复核的证据由对应业务结果 owner 按明确的保存与删除契约持久化，遥测只关联它；不由 tracing 自行引入 Agent 执行库、永久内容副本或确定性回放承诺。 |
| 50 | + |
| 51 | +## 内容与访问边界 |
| 52 | + |
| 53 | +[共享安全模型](security-boundary-model.md)定义 actor 与权限。这里需要限定的路径是：外部输入或异常携带内容、凭据，经采集写入观测存储，再被超出预期范围的读者或外部运营者取得。Trace Context、Peer/resource 属性及 CORS 均不构成授权。 |
| 54 | + |
| 55 | +新增 OTLP 基础模式只采集声明的元数据和关联 ID。Prompt、query、工具参数/结果、引用内容、任意请求响应 body、SQL 参数和异常原文不因打开 tracing 自动获得保存许可；Authorization、Cookie、provider 配置和签名 URL 也不自动采集。基础出口只接入声明来源、字段和值来源的结构化记录，策略覆盖 span 名称、status、events、Resource 与 log body，不能仅过滤 headers 或在远端补做清洗。应用、SDK 和第三方的任意原文日志不得自动桥接；既有 PG/其它已配置 writer 按原配置保持内容行为，不要求为了保留它们再次启用新内容模式。“原文默认关闭”只约束新增 OTLP 出口，不代表整个部署无内容副本。 |
| 56 | + |
| 57 | +内容启用独立于基础性能元数据，并明确用途、可访问者、大小与截断、保留和删除。已有 debug 开关不能自动授权向新增观测出口发送内容。删除业务源数据不会天然删除遥测副本，启用内容时必须处理这个差别。 |
| 58 | + |
| 59 | +部署 owner 控制摄取与查询入口；采集权限不授予读取或管理权限，浏览器不持有后端管理凭据。对外托管或跨 owner 集中诊断需要明确新增数据边界，不能从非秘密部署标识推导租户隔离。 |
| 60 | + |
| 61 | +## 后端可替换性与验证 |
| 62 | + |
| 63 | +应用采集依赖 OpenTelemetry、OTLP 和公共业务语义，不依赖供应商 SDK、项目或 datasource ID，持久业务 schema/carrier 不保存供应商身份；后端替换应发生在出口配置、存储与消费侧，不要求改写业务采集逻辑。OTLP 兼容不保证历史数据、查询和仪表盘可以无成本迁移。部署交付记录属性映射、必要因果字段、保留或损失的协议信息、导出能力及查询迁移方法；不可恢复的字段损失不能通过默认值伪装成原始观测。 |
| 64 | + |
| 65 | +准入应从独立后端查询核对关键字段的可消费语义、缺失与真零、必要因果关联及指标聚合，声明类型投影和损失，并覆盖持久化后的消费。发送成功不算持久化证明。故障验收还需比较真实业务结果，检查应用及可选 Collector 的队列、关闭、丢弃与恢复；只停后端、只测 SDK 或只读取数据库模型不能替代端到端验收。 |
0 commit comments