🇺🇸

Original

English

🇨🇳

Translation

Chinese

Instrumentation Spec

埋点规范

An instrumentation spec defines what analytics events to track, when to fire them, and what properties to include. It serves as a contract between product and engineering, ensuring consistent data collection that enables accurate measurement. Good instrumentation specs prevent the "we can't answer that question because we didn't track it" problem.

埋点规范定义了需要追踪哪些分析事件、何时触发这些事件，以及需要包含哪些属性。它是产品团队与技术团队之间的约定，确保数据收集的一致性，从而实现准确的度量。完善的埋点规范可以避免“因为没有追踪相关数据，所以无法回答这个问题”的情况。

When to Use

使用场景

Before engineering implements a new feature
When defining analytics requirements for experiments
When auditing existing tracking for gaps or inconsistencies
When onboarding a new analytics tool
Before launch to ensure measurement is in place

在技术团队开发新功能之前
为实验定义分析需求时
审核现有追踪方案的漏洞或不一致性时
接入新的分析工具时
产品上线前，确保度量方案已就绪

Instructions

操作步骤

When asked to create an instrumentation spec, follow these steps:

Define Analytics Goals Start with the questions you need to answer. What will you measure? What decisions will this data inform? This prevents over-instrumentation while ensuring nothing important is missed.
Identify Events to Track List each user action or system event that should be tracked. Follow consistent naming conventions (typically
```
noun_verb
```
or
```
verb_noun
```
in snake_case). Each event should represent a distinct, meaningful action.
Specify Event Triggers For each event, describe exactly when it fires. Be precise: "When user clicks Submit button" vs. "When form is submitted successfully." These are different events with different meanings.
Define Event Properties List the properties (attributes) attached to each event. Include property name, data type, description, and example values. Properties provide context that makes events useful.
Document User Properties Identify persistent user-level attributes that should be associated with all events (e.g., subscription tier, account creation date). These enable segmentation in analysis.
Address PII and Privacy Flag any properties that contain personally identifiable information. Document how PII should be handled . hashing, encryption, or exclusion.
Create Testing Checklist Define how QA should verify that tracking is implemented correctly. Include steps to validate events fire at the right times with correct properties.

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

定义分析目标 从你需要解答的问题入手。你要度量什么？这些数据将支持哪些决策？这可以避免过度埋点，同时确保不会遗漏重要数据。
确定需追踪的事件 列出每个需要追踪的用户操作或系统事件。遵循统一的命名规范（通常为蛇形命名法的
```
noun_verb
```
或
```
verb_noun
```
格式）。每个事件应代表一个明确且有意义的行为。
指定事件触发条件 针对每个事件，准确描述其触发时机。表述要精准：比如“当用户点击提交按钮时”与“当表单提交成功时”是两个不同含义的事件。
定义事件属性 列出每个事件附带的属性（特征），包括属性名称、数据类型、描述和示例值。属性为事件提供了上下文，使其更具分析价值。
记录用户属性 确定需要与所有事件关联的持久化用户级属性（例如订阅等级、账户创建日期）。这些属性支持分析时的用户细分。
处理PII与隐私问题 标记任何包含个人身份信息（PII）的属性，并记录PII的处理方式（如哈希加密、加密或排除）。
创建测试清单 定义QA团队应如何验证追踪实现的正确性。包括验证事件在正确时机触发且属性准确的步骤。

Output Format

输出格式

Use the template in

references/TEMPLATE.md

to structure the output.

使用

references/TEMPLATE.md

中的模板来构建输出内容。

Quality Checklist

质量检查清单

Before finalizing, verify:

Event names follow consistent naming convention
Each event has a clear, unambiguous trigger
Properties include data types and example values
PII is identified and handling is documented
Events map to the analytics questions you need to answer
Testing checklist enables QA verification

最终定稿前，请验证以下内容：

事件名称遵循统一命名规范
每个事件都有清晰明确的触发条件
属性包含数据类型和示例值
PII已被识别且处理方式已记录
事件与你需要解答的分析问题对应
测试清单可支持QA团队进行验证

See

references/EXAMPLE.md

for a completed example.

请查看

references/EXAMPLE.md

中的完整示例。

measure-instrumentation-spec