Almanac Console Metrics
外部 Console 指标定义与供数方案

先定义看什么，再决定数据怎么产出

先统一分析维度，再固化指标口径和适用范围；看板结构、数据存储与接口方案都由这套定义反推。

STEP 01 · DIMENSIONS

先定义分析坐标

明确时间、数据范围、入口、知识资产和加工过程；指标不支持的维度，不出现在筛选器里。

STEP 02 · METRICS

再建立指标字典

每项指标固定名称、公式、粒度、可用维度、数据来源、成熟度、完整水位和版本。

STEP 03 · DELIVERY

最后反推供数架构

高基数业务分析进入 Reporting PG / OLAP；低基数运行监控进入 Prometheus-compatible TSDB。

CURRENT · 当前事实现有数据库可计算六项首期指标，其中四项为直接口径、两项为代理口径。
GAP · 仍需补齐组织历史、任务/质量/成本事件、正式聚合 API，以及 OTLP / TSDB 运行遥测。
01 · 分析维度

先约定指标可以怎么切

维度决定筛选、趋势和下钻。首期定义五类业务维度；运行维度单独用于系统健康，不与用户、任务或文档明细混在一起。

统一分析表达式

结果 = 指标 × 时间 × 服务端数据范围 × 该指标支持的维度。 同一指标在个人、知识运营和平台运营视图中公式不变，只改变服务端解析出的数据范围。

D1

时间

什么时候发生

首期字段

event_time、created_at、finished_at；hour / day / week；timezone。

适用指标

M01–M06

当前边界

已有 每次响应仍需返回 as_of、complete_through 和 partial。

D2

数据范围

谁能看、统计哪里

首期字段

user_id、owner / creator、folder / KB ACL；服务端解析 self / managed / platform scope。

适用指标

M01–M06

当前边界

部分具备 部门、BU、租户和组织历史快照尚未贯通。

D3

使用入口

从哪里发起

首期字段

entrypoint；Agent、Search、API、MCP 等枚举需由接入端统一登记。

适用指标

M01–M03

当前边界

DB 已有 当前外供召回明细没有完整提供 entrypoint。

D4

知识范围

什么内容、在哪里

首期字段

folder、KB、document、knowledge_type、publish_status、processing_status。

适用指标

M04–M06；M03 目标态

当前边界

部分具备 历史归因需要事件时快照或 SCD，不能只用文档当前位置。

D5

加工过程

在哪一步、什么结果

首期字段

operation、current_step、status、retry_count、batch / run / step。

适用指标

M05–M06

当前边界

已有 需要统一终态枚举以及排队、执行时间口径。

D6

运行标签

系统是否健康

目标字段

env、service、route、status、version、model、provider。

适用指标

QPS、错误率、P95/P99、lag、并发

当前边界

待建设 仅用于低基数运行指标，不放 user_id / task_id / doc_id。

02 · 指标字典

六项指标回答三个问题

首期只承诺现有事实能够支持的指标，并明确区分“数据库可算”“现有外部接口可取”和“代理口径”。

指标定义规则

每项指标必须同时给出：指标 ID、业务问题、公式与时间窗、适用维度、事实来源、聚合粒度、成熟度、限制和 metric_version。

首期指标字典。状态描述的是现有事实能力，不等于当前外部 raw API 已可直接供数。
指标 业务问题与口径 可用维度 事实来源 / 聚合 成熟度与限制
A · 使用规模｜有多少人在用、用了多少次
M01检索 WAU不是全产品 WAU 滚动 7 日 count(distinct user_id) D1 时间 · D2 范围 · D3 入口 kp_retrieval_events → 日聚合 DB 可算现有外部明细只能算“有命中 WAU”。
M02已记录检索请求数不是任务数 时间窗内 count(retrieval_event) D1 时间 · D2 范围 · D3 入口 kp_retrieval_events → 小时 / 日聚合 DB 可算request_id 唯一约束可能漏记同一外部请求内多次检索。
B · 知识可用性｜有没有检索结果、多少内容处于可用状态
M03已记录检索非空率不能叫回答成功率 success / (success + empty) D1 时间 · D2 范围 · D3 入口 retrieval status → 小时 / 日聚合 DB 可算现有外部明细使用 INNER JOIN，空召回不会出现。
M04PG 可检索候选文档数库存快照 有效源文档 + enabled + published / completed + 非删除 D1 快照 · D2 范围 · D4 知识范围 documents + kp_kb_docs → 日快照 代理口径表示 PG 就绪，不能证明向量索引完全一致。
C · 加工交付｜知识能否成功、及时进入可用状态
M05加工成功率按终态计算 成功终态 /（成功终态 + 失败终态） D1 时间 · D2 范围 · D4 知识 · D5 加工 kp_process_runs → 小时 / 日聚合 DB 可算排除 cancelled、superseded，固定终态枚举。
M06加工入库时延 P95排队 + 执行 p95(finished_at - created_at) D1 时间 · D2 范围 · D4 知识 · D5 加工 process run / step → 小时 / 日聚合 代理口径不等于 source.updated → content.searchable 的真实新鲜度 SLA。
重要边界：M03 是请求结果，M04 是库存状态；在没有统一 KB / 目录归因前，不能把两者按目录直接做因果对比。可信解决率、真实新鲜度和成本仍需新增事件，见目标态附录。

Console 只消费指标定义，不重新发明口径

筛选条件必须随指标能力变化，不能让所有指标共享一套虚假的万能筛选器。

全局筛选

时间、服务端数据范围、入口；知识与加工维度仅在支持的指标页出现。

使用规模

M01 检索 WAU、M02 请求数，以及按时间和入口的趋势。

知识可用性

M03 非空率、M04 候选文档库存；各自展示口径和限制。

加工交付

M05 成功率、M06 入库 P95，并提供失败步骤入口。

运行健康单独成页

QPS、HTTP 错误率、P95/P99、队列 lag、Worker 并发使用 D6 低基数标签，不混入业务指标字典。

03 · 数据架构

这些指标如何产出

前面已经定义了计算什么以及怎么切分，下面才决定数据从哪里来、如何处理、存在哪里，以及怎样安全提供给 Console。

Metric Catalog 是合同层

统一登记维度、公式、时间窗、成熟度、可用范围、完整水位和版本；同时约束 Metric Mart、Metrics API 与 Console，避免三端各算一套。

双通道数据架构
当前已有 规划建设

业务指标通道

高基数 · 可复算 · 可追溯 · 受 ACL 约束

CURRENT 业务 PostgreSQL

资产、KB、加工、检索和 ACL 权威事实。

PLANNED 增量采集与标准化

校验、幂等去重、维度补全、事件时快照、迟到回补。

PLANNED Reporting PG → OLAP

首期用独立 PG；规模增长后迁移或同步至 OLAP。

PLANNED Metric Mart

小时/日汇总、库存快照、分子分母和指标版本。

PLANNED Metrics API

Catalog + Batch Query；服务端解析范围并校验 ACL。

CONSUMER External Console

核心卡片、趋势、维度拆分和受控下钻。

运行指标通道

低基数 · 实时健康 · 告警与容量

CURRENT API / Worker / DB / Redis / Model

当前主要有应用日志和 Worker 周期快照。

PLANNED OTLP / Remote Write

统一采集请求、依赖、队列和模型运行遥测。

PLANNED Prometheus-compatible TSDB

QPS、错误率、P95/P99、lag、并发和依赖健康。

CONSUMER External Console

实时运行大盘、告警状态和服务下钻。

Prometheus 的边界

user_id、task_id、doc_id 等高基数明细保存在 Reporting PG / OLAP，不作为 Prometheus 指标标签。出发点是控制时间序列基数、查询成本、隐私风险，并保留业务指标重算能力。

业务分析维度用户、入口、KB、目录、文档、加工过程和 ACL 范围；任务属于目标态。
运行指标标签env、service、route、status、version、model、provider。
04 · 实施顺序

先签口径，再建供数

如果维度和指标字典尚未冻结，先做数据库、接口或大屏只会把口径分歧固化进更多系统。

冻结分析合同

先让业务、数据、后端和 Console 对同一套定义签字。

  • 冻结 D1–D6 维度的字段、枚举、层级和历史规则。
  • 固化 M01–M06 的分子、分母、窗口、成熟度和版本。
  • 逐项确认哪些筛选和下钻当前可用。
  • 用生产事实 SQL 复核基线值和数据缺口。

建设稳定供数

按已签字的合同建设数据层，而不是让 Console 自己聚合。

  • 建立 Reporting PG、小时/日 Metric Mart。
  • 完成历史回填、增量同步、迟到回补和三方对账。
  • 提供 Metric Catalog + Batch Query API。
  • 增加 service principal、metrics:read 和范围校验。

补齐目标态能力

首版可信后，再增加业务价值和实时运行监控。

  • 补 task、quality、feedback、freshness、usage 事件。
  • 接入 OTLP / Remote Write 与 Prometheus-compatible TSDB。
  • 上线可信解决率、真实新鲜度 SLA 和成本。
  • 达到规模阈值后将 Reporting PG 同步或迁移至 OLAP。
P0 · 禁止浏览器直连 inner feed

原始接口只允许服务间入仓；浏览器只调用聚合 API。

P0 · 每个响应携带完整水位

返回 as_of、complete_through、partial 和 metric_version。

P0 · ACL 在服务端再次判断

外部传入的 scope_id 不能替代当前调用者的权限校验。

附录

细节放在需要时再展开

以下内容保留设计依据和精确边界，但不再与主结论争夺注意力。

角色范围与扩展下钻 同一指标字典，不同服务端数据范围

三类视图

个人使用

服务端解析 self scope；首期查看自己的检索使用和趋势。已撤权来源不再展示标题或正文。

知识运营

服务端解析可管理目录子树；查看内容健康、加工失败、知识缺口和治理队列。

平台运营

按已授权平台范围聚合；查看采用、稳定性和安全状态，默认不暴露 query_text 与文档名。

统一原则

三类视图共用 M01–M06 的公式和版本，只改变服务端解析出的 scope，不复制三套指标。

建议下钻指标

  • 内容：有效资产存量、新增 / 更新资产、活跃贡献者、KB 关联覆盖率、类型 / 目录 / KB 分布。
  • 质量：无效资产召回率可由现有命中明细计算；证据充分率、引用有效率与正反馈率需要新增事件。
  • 检索：pipeline P50 / P95、人均检索次数、平均返回文档数和入口占比；现有 latency_ms 不是 HTTP 端到端耗时。
  • 加工：批次完成率、排队/执行 P95、重试率、步骤失败、积压与卡死。
  • 权限：目录 Owner 完整率、权限索引层级事实、重建/outbox 积压。

历史目录归因目前只能按文档当前 folder_id 映射，可能随文档移动而漂移；目标态应保存事件时 folder/path 快照或使用 SCD 历史维表。

目标态指标与事件模型 可信解决、新鲜度、成本

最终首页五项

以下不是当前承诺项。可信解决、严格新鲜度和成本目前缺少可持续事实，必须先增加事件并完成数据质量验证。

  1. 可信解决任务数：distinct task_id where trusted=true and resolved=true。
  2. 可信解决率：可信且已解决任务 / 有效任务。
  3. 周活跃用户 WAU：有效任务中的滚动 7 日去重用户。
  4. 数据新鲜度 SLA 达标率，同时报告 source.updated → content.searchable 的 P95。
  5. 单次可信解决成本：模型与检索成本 / 可信解决任务数。

最小事件

task.started、answer.completed、quality.checked、task.feedback、source.updated、content.searchable、model.usage、authz.decision。

与 Issue #18 保持一致：task_id 表示用户目标；turn_id 表示一次外部请求或用户回合；interaction_id 表示每次检索、模型或工具调用；event_id 用于幂等；trace_id 用于跨系统追踪。

当前数据来源与处理细节 表、接口、回填与水位
资产事实

asset_folder、documents、asset_file：目录、逻辑文档、版本、类型、大小和生命周期。

知识加工

kp_kb_docs、kp_batch_jobs、kp_process_runs、kp_process_steps：状态、步骤、重试、错误和耗时。

检索事实

kp_retrieval_events、kp_retrieval_event_documents：用户、入口、状态、耗时和最终命中文档。

权限治理

resource_node、access_grant、effective_resource_permission_index、audit、outbox、rebuild task。

已有增量接口

  • /asset/inner/assets：资产最新版本与变更，可用于首次回填和增量入仓。
  • /knowledge/inner/retrieval-records：只返回有命中的文档明细；一行代表一个命中文档，空结果不会出现。

增量采集应使用日期 + cursor、重叠窗口重拉和幂等 upsert。小时汇总处理迟到事件，每日保存库存快照；完整水位由 as_of、complete_through 和 partial 表达。

API、安全与 ACL 边界 供数契约、三层权限和 CREATE_SUB

业务指标接口

GET  /api/v1/insight/metrics/catalog
POST /api/v1/insight/metrics/query:batch

response.meta = {
  "as_of": "...",
  "complete_through": "...",
  "partial": false,
  "metric_version": "1.0.0"
}

安全边界

  • 使用专用 service principal、metrics:read scope 和网关白名单。
  • Console 不获得普通用户 API Key，不直连生产数据库或 inner feed。
  • 任何目录、KB、文档明细下钻都必须按当前 ACL 再授权。

三层 ACL

最终鉴权先汇总调用者全部主体，再按资源选择完整最高层级 owner > local > inherited；仅在选中的同一层级内处理 deny / allow，不能跨层合并 action。

  • Owner 是 resource_node.owner_principal_key 的资源事实，不是额外 owner grant；新建目录不追加 owner grant。
  • 显式 CREATE_SUB 是当前目录的独立本地 action，本身不向后代继承。
  • MANAGE 仍可能隐含 CREATE_SUB，因此“显式本地授权数”不等于“最终可创建主体数”。
设计依据与已知限制 仓库证据和不能误用的数据
设计基线GitLab Issue #18 · 核心指标口径与埋点链路
外部增量接口docs/api/inner-interfaces.md
检索事件libs/almanac_infra/.../models/retrieval_events.py
加工任务models/kb_docs.py · process_runs.py · process_steps.py
权限判定libs/almanac_infra/src/almanac_infra/acl_sql.py
现有前端原型apps/web/src/App.tsx · PersonalUsageAnalytics，目前为演示数据

不能直接作为正式指标的数据

  • call_count、accuracy_rate 没有真实维护链路。
  • kp_retrieval_test_results 无法还原完整历史趋势。
  • last_processed_at 没有可靠写入点，不能计算真实源端新鲜度。
  • 当前 OTEL 仅有配置占位，Worker 的 lag / pending / active 仍主要写入日志。