Metrics Ownership

这份文档定义 AIRI 团队的指标分层规则：什么指标该走 Grafana / Prometheus（OTel server-side），什么该走 PostHog（frontend/external product analytics），同名指标怎么处理。落地这份是为了避免后期"同一个 KPI 三处不同数"的漂移。

总原则

工具职责正交，互补不互替：

业界没有权威的判定 framework（参见下方"参考来源"），这份文档落实成项目内的可执行规则。

7 题判定 Checklist

每条新增指标依次问这 7 个问题：

裁决规则：

• ≥4 个偏一侧 → 那一侧
• 平局 → 两边都放，但指定唯一 truth side（见下文）
• 如果一个指标 7 题答下来很纠结，多半是指标定义本身没拆干净——应该拆成两个不同的指标，分别归到两边，而不是混合归属

Truth Side（重复指标处理）

业界没有银弹（PostHog 官方在 issue #43633 也承认 dual-emit 没有统一 pattern）。我们的做法：接受两边数字差异，dashboard 上标注语义不同。

Truth side 指定原则

Better Auth session table 与活跃用户

user_active_sessions（COUNT(*)）和 user_distinct_active（COUNT(DISTINCT user_id)）共享同一张 session 表：

• Better Auth 每次 sign-in / 每次 OIDC access-token 颁发都新建一条 session row，从不主动 GC 过期 row——因为 oauth_access_token.session_id FK 指向 session（apps/server/src/libs/auth.ts:513 注释）
• 实战观察：~80K user_active_sessions 对应实际只有几百 distinct user。比例 5+ 就该考虑加 session GC cron 或缩短 Better Auth expiresIn
• 永远展示 user_distinct_active 给非工程师看（PM、运营）；user_active_sessions 留给工程师 debug

Dashboard 标注规则

两边都展示的指标，必须在 Grafana panel description 和 PostHog insight description 里：

1. 注明 truth side（"Truth: Postgres flux_transaction 表" / "Truth: PostHog 事件去重"）
2. 注明本侧统计的语义差异（如 "Grafana 这里是 session 计数，不去重；PostHog 那边是 user 去重 DAU"）
3. 如果两边数字差异预期 > 10%，写明合理范围

PostHog 事件命名约定

格式：<noun>_<verb_past_tense>，全部 snake_case。

distinctId 在登录后必须调 posthog.identify(userId)，userId 用 Better Auth 的 user id（跟 server 里的 c.get('user').id 一致）。AIRI server 不直接接入 posthog-node，后端事实事件写入 Postgres product_events 并通过 airi_product_events_total 暴露到 Grafana。前端 wiring 由 useSharedAnalyticsStore.initialize() 自动处理，不需要每个 caller 手动 identify。

参考来源：PostHog: 5 events all teams should track。

Grafana 指标命名约定

沿用现有 observability-conventions.md 不再重复，关键约束：

• OTel semconv 优先（http_* / db_* / gen_ai_*），匹配不上才放 airi.* 命名空间
• counter 一律 _total 后缀，histogram 一律 _seconds_bucket / _bytes_bucket
• label 基数受控（route pattern 而非 URL，model name 而非 prompt）

当前指标归属总表

Grafana / Prometheus（系统侧）

来源：apps/server/src/otel/index.ts 全量列表见 observability-metrics.md。Dashboard 配置在 apps/server/otel/grafana/dashboards/build.ts。

PostHog（前端 / 外部数据源，产品侧）

已接入：

• 前端 posthog-js 通过 packages/stage-ui/src/stores/analytics/posthog.ts 初始化，三个 app（web / desktop / pocket）按 isStageTamagotchi() 等选 project key
• Server 不接入 posthog-node。后端产品事件写 product_events，Grafana 展示低基数聚合；需要 PostHog revenue/person analytics 时优先用 PostHog Stripe source connector 或离线导入，不允许在 API 请求路径同步发 PostHog。
• 前端 identity：useSharedAnalyticsStore.initialize() watch authStore.isAuthenticated 自动调 posthog.identify(user.id) / reset()
• Conversation controls 事件的 surface 由 packages/stage-ui/src/composables/use-analytics.ts 统一按 runtime 推断，UI 调用点只传业务字段。

已埋点：

待埋点（API 已在 use-analytics.ts 暴露但调用点未接入）：

双展示指标（同名两边都有）

PostHog 接入路线图

落地分两步，不要一次性埋全部事件，否则 schema 漂移会很快出现。PostHog 采集只发生在前端或外部 source connector；server 请求路径只写 Postgres/Grafana。

阶段 1（P0 — 付费漏斗 + activation）

apps/stage-web：

import posthog from 'posthog-js'

posthog.init(import.meta.env.VITE_POSTHOG_KEY, {
  api_host: 'https://us.i.posthog.com',
  capture_pageview: false, // 手动 capture 控制语义
})
// 登录后
posthog.identify(user.id)
// 在 pricing.vue
posthog.capture('pricing_page_viewed', { plan_period, source })

apps/stage-tamagotchi（Electron renderer）：

// NOTICE: Electron CSP 下普通 import 会静默失效，必须用 full bundle。
// 参考：https://posthog.com/tutorials/electron-analytics
import posthog from 'posthog-js/dist/module.full.no-external.js'

posthog.init(import.meta.env.VITE_POSTHOG_KEY, {
  api_host: 'https://us.i.posthog.com',
  autocapture: false, // 桌面应用没有传统 URL 路由，手动控制
})

埋点事件清单（P0）：

• 前端：pricing_page_viewed、plan_selected、checkout_started、user_signed_up、first_message_sent、first_model_selected
• 后端：不直接发 PostHog；payment_completed 写入 product_events，PostHog 侧通过 Stripe source connector 或离线导入展示

PostHog UI 配两个 funnel：

• 付费漏斗 (7d 窗口)：pricing_page_viewed → plan_selected → checkout_started → payment_completed（最后一步来自 Stripe source connector / 离线导入）
• 激活漏斗 (14d 窗口)：user_signed_up → first_message_sent → first_model_selected → payment_completed（最后一步同上）

阶段 2（P1 — retention / feature adoption / churn）

埋点事件清单：character_created、voice_mode_activated、chat_session_started、model_switched、flux_image_generated、subscription_cancelled。

PostHog UI 配 cohort：

• D7 Retention by voice mode：第一次 session 用了 voice_mode_activated 的用户 vs 没用的，看 D7/D30 retention 差异
• Churn 14d：过去 14d 没有 chat_session_started 的付费用户，作为召回 cohort

Stripe → PostHog 集成路径

不在 server webhook 里手动 capture：

不要在 API 请求路径同步发 PostHog：PostHog 网络尾延迟会污染 auth / billing / chat route latency。需要 person-level funnel endpoint 时，用后台导入或 connector，不阻塞用户请求。

5xx Triage 路径

Dashboard 上 follow 这条 panel 链可以从"出事了"一路 drill 到"哪个 trace 是真凶"：

1. panel-4 5xx Rate %（Row 1）— 数字 / gauge 颜色变红，说明出事
2. panel-9 Top Routes by 5xx（Row 2 donut）— "现在哪些 route 在失败"
3. panel-44 5xx Rate by Route（Row 5.5 timeseries）— "什么时候开始的、是单点还是普遍"
4. panel-91 5xx Error Logs（Row 8 上半）— 实际错误消息，里面有 trace_id field 可点 → Tempo 看完整 trace 回放

Tempo / Loki derived fields 配置（一次性）

panel-91 的 trace_id 字段必须配 Grafana Cloud Loki datasource 的 Derived fields 才能跳 Tempo。这不在 dashboard JSON 范围内，是 datasource 级配置：

• Grafana Cloud → Connections → Data sources → 选 grafanacloud-projairi-logs（Loki）→ Derived fields
• 添加：
  • Name: trace_id
  • Type: Regex in label or value
  • Regex: "trace_id":"([a-f0-9]+)"（匹配我们 logger 的 JSON 输出）
  • URL: 留空
  • Internal link: ✓，datasource 选 grafanacloud-projairi-traces（Tempo）
• 同样手法可加 req (request id) → 配 internal link 回 Loki 自身，按 requestId filter

配置完之后日志面板里 trace_id 会变成蓝色可点，直接跳 Tempo waterfall。这一步配置只做一次，新加 panel 自动享有。

Grafana Alert SOP

Alert rules 不放在 apps/server/otel/grafana/dashboards/build.ts 里——Grafana Cloud 用 Unified Alerting，rule 在 Grafana UI 或 alerting API 管理，跟 dashboard JSON 解耦。这一节维护我们应该配的 alert rule，新加 rule 时同步更新这里。

P0 — page on-call（PagerDuty / Slack on-call channel）

P1 — notify only（Slack ops channel，不分页）

配置入口

Grafana Cloud → Alerts & IRM → Alert rules → New alert rule。把上面 query 粘进 PromQL editor，threshold 按表设置，labels 加 severity=p0|p1，notification policy 按 severity 路由到 PagerDuty 或 Slack。

每加一条 alert，更新这张表——alert 没在文档里登记 = 不知道为什么 page、不知道 owner、不知道历史阈值改动。

何时打破规则

这份文档定的是默认值，不是法律。下列情况可以打破：

• 系统指标也需要给 PM 看（如 LLM provider 可用性影响产品决策）→ Grafana truth + 周期性 export 给 PostHog dashboard 展示
• 产品指标需要分钟级告警（如付费转化突然归零）→ Grafana alert 监 Stripe webhook 计数，PostHog truth 不变
• A/B test 影响系统指标（如新 LLM router 影响延迟）→ feature flag 同时打到两边，Grafana panel 按 flag value 分线展示

打破规则的指标必须在 dashboard description 里说明，不要静默打破。

参考来源

业界没有权威 framework，下列来源是这份文档的依据：

• PostHog Product Metrics Handbook — PostHog 自己的内部分层
• PostHog issue #43633 — dual-emit 问题的工程承认
• Honeycomb Observability 2.0 — "消除工具边界"的少数派立场
• Reforge: North Star Metrics — leading vs lagging 区分
• DEV: Metrics for 500 Engineers with Linear + Grafana + PostHog — 与我们结构最接近的公开案例
• PostHog: Stripe payment platform — Stripe 集成路径官方文档
• PostHog: Electron analytics — Electron renderer 接入要点
• Google SRE Book: Monitoring Distributed Systems — Four Golden Signals
• Stripe: Essential SaaS Metrics — 收入侧指标定义