Skip to content

feat(core): 统一可观测性记录与后端查询 - #178

Draft
xiaoland wants to merge 2 commits into
feat/core-app-separationfrom
feat/observability-unification
Draft

xiaoland wants to merge 2 commits into
feat/core-app-separationfrom
feat/observability-unification

Conversation

@xiaoland

@xiaoland xiaoland commented Nov 4, 2026 •

Copy link
Copy Markdown
Member

成功执行的 Job 过去只产生可选 OTLP 事件,Web 的 PostgreSQL 日志查询因此可能为空;不同采集和读取入口也各自绑定具体存储。本 PR 让基础记录和查询使用同一选定后端,并通过 Core 的单一采集入口协调额外 OTLP 出口。

范围

  • Core 实例拥有有界观测队列、数据库或 Loki 双向后端及额外 OTLP runtime;目标、认证、资源关闭不会混入其它 Core。
  • 独立公共选择 inkcre.observability.backend / inkcre.observability.backend.v1 缺省 PostgreSQL;Loki 需要服务端私密 URL/headers 和稳定部署身份。配置失败或外部不可用不回退另一存储。
  • 精确 Peer 能力 core.observability.v1 提供认证的 /observability,支持 status/query/ingest;expected_backend 不匹配返回 409。查询过滤先于截断,时间窗最长 31 天、最多 500 条;截断明确返回,不提供会遗漏同刻记录的 cursor。
  • Job 开始/终态、操作耗时/结果及真实 AI usage 在 OTLP 关闭时也有基础记录;缺失用量不补零。ERROR 使用既有 OTEL severity 17,取消保持 INFO 9。
  • 旧 PG 原文与 job.<id> 关联可读取,不补写虚构历史、不自动搬迁。选择外部不自动允许原文复制,默认保留声明元数据与固定说明;显式内容开关有单独说明。
  • HTTP 请求有 256 KiB、四并发、15 秒总限额;查询另有十秒预算;采集队列最多 1024 条,关闭最多五秒排空。格式错误、超大日志或后端失败不会覆盖业务结果。

受影响发布项目:inkcre-core(含服务镜像);已包含 Towncrier fragment。无数据库 migration、历史表删除或第三方服务配置变更。

验证

  • 同步 main ee84d48 前的本地非 integration/acceptance 集合:114 passed、9 skipped、1 deselected;唯一 warning 为既有 Starlette TestClient deprecation。同步后执行发布意图与必要静态核对,未重跑该集合;当前 head 的云端结果见文末。
  • 10 项新受控用例覆盖 Loki 编解码/字面多行查询、外部失败不回退、历史 PG 映射、选择缺失和失败、目标不匹配、慢请求/并发准入、元数据/日志边界及实例资源隔离。无真实数据库或外部网络。
  • Pyrefly 0 diagnostics;Ruff lint、578 文件格式、数据库边界和提交 hooks 通过。
  • 独立 wheel 构建及仓库外导入/生命周期检查通过,未连接数据库。
  • 共享文档引用检查和 git diff --check 通过。

按用户要求,本地未执行端到端验收;云端 CI 正常运行,结果以当前 head 的 Checks 为准。模拟传输不证明 Loki/Grafana Cloud 真实持久化、部署路由或完整 Web 旅程。

风险、迁移与回滚

公共选择在实例启动时读取,修改后重启提供方并重建客户端;没有隐式热切换。旧 OBSRV__LOGGING_BACKEND/Logtail writer 配置不再选择存储,需按部署文档迁移到有完整读写语义的后端。旧 Peer 不认识新选择,混合部署升级时需协调各生产者,不能假定旧 writer 自动停止。

状态中的 configured/queryable 只说明具备配置和能力,不是连通性或持久化证明;dropped 是本实例已知损失。窗口摘要不代表完整 APM、全局指标或账单。

可整体撤销本 PR 的源码与共享引用提交,恢复父 PR 产物。Loki 中已写数据和 PG 历史均保留,回滚不执行数据迁移。若曾选择 Loki,恢复旧产物前需明确恢复部署配置,避免新旧消费者读取不同后端。

本 PR 只创建草稿,不合并、发布软件包、部署生产或修改真实第三方配置。既有 CI/预览按正常规则运行。

关联与下一步

直接父 PR:#175(feat/core-app-separation);直接子 PR:https://github.com/InKCre/impl-py/pull/181。父 PR 合并后需重排到最新 main,再合并本 PR。

共享合同:InKCre/docs#53;跨仓跟踪:InKCre/docs#52。Hub 已先推送 33f5a13,本 PR 用独立提交更新子模块引用。

下一响应方:维护者。请审阅后端选择、读取错误、内容边界及生命周期语义;真实部署端到端验证和最终交付仍由跟踪项保留。

当前 head 0867de6 基于父 PR a749300(main ee84d48),云端 Repository and artifact checks 已通过,包括数据库场景、CLI 和 E2E;preview 部署尚在运行。上述云端结果不代表真实 Loki 服务和完整 Web 旅程已验收。

后续 App / Peer 命名迁移

直接子 PR:https://github.com/InKCre/impl-py/pull/181(draft)。先交付本 PR,再重排命名迁移;跨仓跟踪 InKCre/docs#55。

This branch was successfully deployed

1 active deployment
preview — 0867de66 Deployed Nov 4, 2026 by xiaoland via impl-py preview #548
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Review / acceptance

Development

Successfully merging this pull request may close these issues.

1 participant