跳转到内容
Telemetry
浏览文档
概念与 SQL 模式更新于 2026年7月29日由 Telemetry 编辑团队和产品团队审核阅读约需 3 分钟

让编程智能体使用这篇文档

打开 Claude Code、Codex、Cursor 或其他编码代理的集中提示包,然后将其适应此处介绍的工作流程。

本页内容
  1. 不同的身份级别
  2. 定义租户边界
  3. 仔细链接匿名活动和经过身份验证的活动
  4. 选择正确的分析颗粒
  5. 处理生命周期变更
  6. 使用边缘情况进行验证

用于事件分析的多租户身份建模

产品和运营问题通常同时使用多个身份:人员、帐户、工作空间、会话、请求、设备或匿名访问者。将这些值视为可互换的会导致漏斗膨胀、保留队列被破坏以及数据暴露不安全。

在 SQL 中使用每个标识符之前定义其粒度和所有权。

不同的身份级别

对不同的实体使用不同的字段:

领域 含义 使用示例
account_id 稳定的客户或计费帐户 收入、计划和帐户保留
workspace_id 帐户内的产品工作区 协作和工作空间活动
user_id 稳定的内部人员标识符 用户激活和功能采用
anonymous_id 预认证浏览器或设备标识符 登陆到注册归因
session_id 有界互动期 旅程和会话分析
request_id 一次请求或处理尝试 操作相关性

请勿将电子邮件地址输入 user_id。首选内部假名标识符,并将身份查找保留在已拥有个人数据的系统中。

定义租户边界

每个多租户事件都应包含授权和分析所需的租户标识符。选择一个规范的帐户级字段并在各个服务中一致地使用它。如果事件属于工作区,请同时包含 account_idworkspace_id,而不是重载一个字段。

决定如何表示内部流量、测试租户、删除的租户和帐户合并。默默地将生产客户与员工和自动化测试混合在一起的仪表板将产生误导性的比率。

匿名访问者稍后可能成为经过身份验证的用户。仅在应用程序建立关系后才记录显式链接事件:

{
  "event_name": "identity_linked",
  "anonymous_id": "anon_7b2",
  "user_id": "usr_42",
  "account_id": "acct_18",
  "link_reason": "registration_completed",
  "identity_policy_version": "v2"
}

不要默默改写历史事件。保留链接时间和策略版本,以便查询可以区分事件时已知的内容和后来的身份解析。在跨上下文连接标识符之前,请检查同意和隐私要求。

选择正确的分析颗粒

计算帐户数量以进行帐户激活和扩展。计算个人采用的用户数量。计算会话参与度的不同会话。计算作业或 Webhook 结果的终端工作流 ID。

说明度量定义中的粒度:

  • “每周活跃账户”是指具有合格核心活动的独特 account_id 值;
  • “激活用户”是指达到激活里程碑的不同user_id值;
  • “请求失败率”使用符合条件的请求事件,而不是不同的用户。

漏斗队列保留 指南解释了身份选择如何改变分母。

处理生命周期变更

帐户合并、用户删除、工作区转移和成员资格更改需要明确的策略。当可审核性很重要时,保留不可变的事件时间标识符,并且仅当问题要求当前所有权时才加入当前维度。

对于删除请求,记录哪些假名标识符仍然是必要的,哪些可以不可逆地转换,以及哪些事件必须删除。关注 数据保留和删除敏感数据脱敏

使用边缘情况进行验证

测试多个工作区中的一名用户、一个帐户中的多个用户、匿名到身份验证的转换、帐户合并、员工租户和已删除的用户。确认激活、保留和收入查询将目标实体精确计数一次。

相关产品功能

记录稳定的事件名称、类型明确的字段,以及经过隐私审核的上下文。

内容责任与技术参考

Telemetry 编辑团队负责维护本文;产品团队审核功能行为、示例和适用范围。

查看编辑规范