measure-instrumentation-spec

埋点规范

埋点规范定义要跟踪哪些分析事件、何时触发事件，以及要包含哪些属性。它是产品与工程团队之间的约定，确保数据收集保持一致，从而实现准确衡量。完善的埋点规范可以避免出现“我们没跟踪这个数据，所以无法回答这个问题”的情况。

适用场景

• 工程团队开始实现新功能之前
• 为实验定义分析需求时
• 审核现有跟踪方案，找出遗漏或不一致之处时
• 接入新的分析工具时
• 发布之前，确保已做好衡量准备

不适用场景

• 你要定义基于这些事件构建的仪表盘 → 使用 measure-dashboard-requirements
• 你需要的是实验专属指标和变体，而不是产品级跟踪 → 使用 measure-experiment-design
• 功能本身尚未明确（没有可供埋点的流程）→ 先使用 deliver-prd
• 你要分析已收集的数据 → 使用 measure-experiment-results 或 measure-survey-analysis

说明

当被要求创建埋点规范时，请遵循以下步骤：

1. 定义分析目标 从需要回答的问题入手。你要衡量什么？这些数据将为哪些决策提供依据？这可以避免过度埋点，同时确保不遗漏任何重要内容。

2. 确定要跟踪的事件 列出应跟踪的每项用户操作或系统事件。遵循一致的命名约定（通常采用 noun_verb 或 verb_noun 这种 snake_case 格式）。每个事件都应代表一个独立且有意义的操作。

3. 指定事件触发条件 对每个事件，准确描述其触发时机。务必明确：“用户点击提交按钮”与“表单成功提交”是不同的事件，含义也不同。

4. 定义事件属性 列出附加到每个事件的属性（特征）。包括属性名称、数据类型、描述和示例值。属性提供的上下文能让事件更有用。

5. 记录用户属性 确定应与所有事件关联的持久用户级属性（例如订阅等级、账户创建日期）。这些属性有助于在分析中进行细分。

6. 处理 PII 和隐私 标记包含个人身份信息的任何属性。记录应如何处理 PII——散列、加密或排除。

   如果捕获任何模型输入、输出、检索上下文或工具调用，则本节还应涵盖跟踪记录。触发条件是捕获，而非创作：无论敏感文本是由用户输入、从租户文档中检索、置于系统提示词中、传递给工具或由工具返回、从上传文件或批处理作业中读取，还是由模型自行生成，都会触发捕获。即使某项功能没有直接的用户输入，也可能将客户合同文本写入跟踪记录存储中。

   跟踪记录不是事件：事件携带的是你预先选定的属性，而跟踪记录携带的是可能包含任何内容的自由文本，包括属性架构未预料到的数据。请决定并记录：

   • 捕获的数据类别。 明确列出类别（用户文本、检索到的文档、系统提示词、工具参数和结果、文件内容、模型输出）。“跟踪记录”不是答案。
   • 最小化处理，覆盖两个边界。 哪些内容会在跟踪记录离开进程之前被丢弃或编辑，哪些内容会在存储之前被丢弃。若编辑器只在存储层运行，原始文本就已经通过网络发送了。
   • 访问权限。 谁可以读取跟踪记录，读取操作是否会被记录。跟踪记录存储通常是功能所处理的最敏感数据中管控最宽松的副本。
   • 保留与删除。 保留多久、什么操作会触发删除，以及当删除请求涉及已复制到评估集中的跟踪记录时如何处理。
   • 同意与选择退出。 数据主体是否已同意，以及他们拒绝时该功能会如何处理。
   • 采样。 捕获的比例以及样本的选取方式。均匀采样不适合发现罕见故障；如果捕获跟踪记录是为了诊断不良输出，就应对已标记的案例进行过度采样，并明确说明。

7. 创建测试清单 定义 QA 应如何验证埋点是否正确实现。包括验证事件是否在正确时机触发且携带正确属性的步骤。

输出格式

使用 references/TEMPLATE.md 中的模板组织输出。完整的规范应填写模板中的所有部分：概述、事件清单、用户属性、PII 与隐私注意事项、实现说明和测试清单。

质量检查清单

定稿前，请核实：

• 事件名称遵循一致的命名规范
• 每个事件都有清晰、明确的触发条件
• 属性包含数据类型和示例值
• 已识别个人身份信息（PII），并记录处理方式
• 事件与需要解答的分析问题相对应
• 测试清单可用于 QA 验证
• 如果记录了任何模型输入、输出、检索上下文或工具调用：已命名数据类别；已分别确定数据在出口边界和存储边界的最小化措施；已确定访问控制与读取日志、保留与删除、同意和抽样，不会将这些事项留待以后处理

示例

请参阅 references/EXAMPLE.md 中的完整示例。