Sentry 前端分析事件定义指南：从域事件文件到主注册表的完整实现流程

在 Sentry 的前端 UI 中，产品团队依赖结构化、强类型的分析事件（analytics events）来度量用户行为。本文基于仓库中的官方技能参考文档，完整讲解"如何定义一个新分析事件"的四步标准流程：定位或创建域事件文件、添加事件参数类型、写入 Amplitude 名称映射、注册到主注册表，并深入源码解释 trackAnalytics 的类型安全机制与事件下发管道（Reload / Amplitude / Pendo），帮助你掌握在 Sentry 前端代码库中正确、可验证地新增埋点的完整技术能力。

一、背景：Sentry 前端的事件埋点架构

Sentry 的前端埋点不是"随手调一下 SDK"，而是一套类型驱动的分域注册机制。理解这套机制是正确定义事件的前提：

• 域事件文件：所有事件按功能域（domain）拆分到 static/app/utils/analytics/ 目录下的 {domain}AnalyticsEvents.tsx 文件中，例如 feedbackAnalyticsEvents.tsx、dashboardsAnalyticsEvents.tsx。目录中目前已有 30 多个域文件，覆盖 feedback、explore、monitors、seer、replay 等全部主要功能模块；
• 主注册表：static/app/utils/analytics.tsx 汇总所有域的参数类型与事件名映射，导出全应用唯一的 trackAnalytics 函数；
• 类型工厂：makeAnalyticsFunction.tsx 通过泛型工厂生成类型安全的埋点函数，事件键（event key）和参数（params）都由泛型约束；
• 下发管道：GetSentry 部署通过 override 机制把事件路由到 Reload（始终）、Amplitude / Pendo（当事件名非空且组织上下文存在时）。

从 analytics.tsx 的注释 可以看到该设计意图：所有分析事件——无论最终目的地是 Reload 还是 Amplitude——都必须经由同一个 trackAnalytics 入口，且事件名（eventName）非空时才会同步到 Amplitude。

二、第一步：定位或创建域事件文件

事件文件位于 static/app/utils/analytics/，命名模式为 {domain}AnalyticsEvents.tsx。可以用下面的命令发现现有域文件：

ls static/app/utils/analytics/*AnalyticsEvents.tsx

核心原则：优先把新事件加进已有域文件。 只有当该功能在现有任何域中没有自然归属时，才创建新文件。这与仓库技能文档 SKILL.md 中"复用优先于创建"（Reuse over create）的硬性约束一致——在定义新事件前，应先按功能域关键词搜索 static/app/utils/analytics/，确认没有可复用的同名或近似事件。

三、第二步：添加事件类型

在对应域的 *EventParameters 类型中添加事件键及其参数类型。例如向 feedback 域添加一个"应用过滤器"事件：

export type FeedbackEventParameters = {
  // Existing events...
  'feedback.filter-applied': {
    filter_type: string;
    source: 'list' | 'detail';
  };
};

仓库中的 feedbackAnalyticsEvents.tsx 就是这类类型的真实实例：其中 'feedback.mark-spam-clicked' 的参数被限定为 {type: 'bulk' | 'details'}（字符串字面量），而 'feedback.feedback-item-rendered' 这类无自定义参数的渲染事件则声明为 Record<string, unknown>，与官方规范完全吻合。

参数类型化规则

规则	示例
取值范围已知时，用具体字符串字面量而非 string	source: 'list' | 'detail'
无自定义参数的事件用 Record<string, unknown>	'feedback.item-rendered': Record<string, unknown>
参数类型永远不要使用 any	使用 unknown 或具体类型
organization 仅在需要覆盖自动组织上下文时才包含	极少需要

这些规则的价值在于：makeAnalyticsFunction 的签名是 analyticsParams: EventParameters[EventKey] & OrgRequirement（见 makeAnalyticsFunction.tsx），即参数对象的结构完全由你声明的类型决定。用字面量联合类型，调用方写错 source: 'sidebar' 时 TypeScript 会直接报错；反之若声明为 string，这类错误只能到线上才能发现。

四、第三步：添加事件名映射（Event Map）

在域事件文件中，把事件键映射到 Amplitude 显示名：

export const feedbackEventMap: Record<keyof FeedbackEventParameters, string | null> = {
  // Existing entries...
  'feedback.filter-applied': 'Feedback: Filter Applied',
};

注意 map 的类型是 Record<keyof FeedbackEventParameters, string | null>——每个参数类型中声明的事件键都必须有对应映射项，漏掉任何一项都会直接触发 TypeScript 编译错误。这是该设计的关键安全网：类型与映射在编译期被强制保持一致。

Amplitude 命名规则

场景	取值
事件需要进入 Amplitude	'Human Readable: Title Case Name'
仅 Reload 的内部指标事件（如高频事件）	null

Amplitude 名称遵循 'Domain: Action Description' 的 Title Case 格式。例如真实仓库中 feedbackEventMap 里的 'feedback.summary.category-selected': 'Selected Feedback Category'。

null 与字符串的取舍对应下发管道的行为差异：

目的地	触发条件	使用字段
Reload	始终发送	eventKey
Amplitude	eventName 非空且组织上下文存在	eventName
Pendo	同 Amplitude	eventName

也就是说，null 名称的事件只在 Reload 中可查（Reload-only 事件不会出现在 Amplitude 搜索里），适合那些对 Amplitude 成本过高的高频内部指标事件。

五、第四步：注册到主注册表

只有当你创建了新的域文件时才需要这一步；向已有域文件添加事件则跳过——该域已经注册完毕。注册动作分三步，全部在 static/app/utils/analytics.tsx 中完成：

1. 导入类型与事件名映射：

import type {MyDomainEventParameters} from './analytics/myDomainAnalyticsEvents';
import {myDomainEventMap} from './analytics/myDomainAnalyticsEvents';

2. 把类型加入 EventParameters 接口（该接口通过 extends 聚合所有域类型，见 analytics.tsx）：

interface EventParameters
  // ...existing types
  extends MyDomainEventParameters, Record<string, Record<string, any>> {}

3. 把 map 展开进 allEventMap（见 analytics.tsx）：

const allEventMap: Record<string, string | null> = {
  // ...existing maps
  ...myDomainEventMap,
};

trackAnalytics 最终由 makeAnalyticsFunction<EventParameters>(allEventMap) 生成，因此只有完成这三步注册的事件键，才能通过 trackAnalytics 的类型检查。

六、完整示例与反模式

向已有域添加新事件的完整示例

向 feedback 域添加 "filter applied" 事件（对应 feedbackAnalyticsEvents.tsx 中的真实代码结构）：

// In static/app/utils/analytics/feedbackAnalyticsEvents.tsx

export type FeedbackEventParameters = {
  // ... existing events
  'feedback.filter-applied': {
    filter_type: string;
    source: 'list' | 'detail';
  };
};

export const feedbackEventMap: Record<keyof FeedbackEventParameters, string | null> = {
  // ... existing entries
  'feedback.filter-applied': 'Feedback: Filter Applied',
};

随后在业务代码中即可类型安全地调用：

import {trackAnalytics} from 'sentry/utils/analytics';

trackAnalytics('feedback.filter-applied', {
  organization,
  filter_type: 'status',
  source: 'list',
});

反模式：未注册的事件键

// BAD — will cause TypeScript error, event key not registered
trackAnalytics('feedback.my-new-thing', {
  organization,
  some_param: 'value',
});

// GOOD — define the event type and map entry first, then call
trackAnalytics('feedback.filter-applied', {
  organization,
  filter_type: 'status',
  source: 'list',
});

BAD 示例之所以必然编译失败，是因为 trackAnalytics 的事件键参数类型是 keyof EventParameters & string，未注册的键根本不在联合类型内；即便通过 @ts-ignore 强推，运行时 eventKeyToNameMap[eventKey] 也会得到 undefined，事件虽会发往 Reload 但永远到不了 Amplitude。

七、源码纵深：事件从声明到下发的完整链路

结合源码可以更清楚地理解每一步注册为什么是必需的：

1. 调用阶段：trackAnalytics('feedback.filter-applied', {...}) 执行 makeAnalyticsFunction 生成的闭包。函数体从 eventKeyToNameMap[eventKey] 取出显示名，组装 {eventKey, eventName, ...analyticsParams}，然后调用 rawTrackAnalyticsEvent。若 localStorage 中 DEBUG_ANALYTICS === '1'，事件会以 analyticsEvent 前缀打印到控制台——这是本地调试埋点最直接的验证手段；
2. override 阶段：rawTrackAnalyticsEvent 只是 getOverride('analytics:raw-track-event') 的转发（见 makeAnalyticsFunction.tsx）。这种间接层让开源版（override 未注册时事件被静默丢弃）与 GetSentry 部署共用同一套类型系统；
3. 路由阶段：GetSentry 侧的真实实现在 static/gsApp/utils/rawTrackAnalyticsEvent.tsx，它引入 trackReloadEvent、trackAmplitudeEvent、trackPendoEvent 等模块，把事件分发给各目的地，并处理分析会话（ANALYTICS_SESSION）、referrer 参数、以及 project_id/organization_id/user_id/org_id 等字段的整数强制转换（COERCE_FIELDS）。

这条链路也解释了文档中"参数类型化规则"的工程意义：由于事件参数最终被序列化发给多个下游，类型是唯一的契约——域类型定义、事件名映射、主注册表三者共同构成了一个编译期可验证的埋点注册表。

八、实操检查清单

在提交前，可以按以下清单自检（依据 event-definitions.md 与 SKILL.md）：

1. 事件键符合 {domain}.{section}.{action} 的 snake_case 点分命名，且前缀与该域文件中既有事件一致；
2. 参数类型使用了字面量联合 / Record<string, unknown>，没有任何 any；
3. *EventParameters 类型与 *EventMap 中的键一一对应（类型系统会自动强制）;
4. 新域文件已完成主注册表三步注册；
5. 事件名遵循 'Domain: Action Description' Title Case 格式，或高频事件显式置 null；
6. 调用点位于用户动作触发处（点击处理函数、提交处理函数），而非 render 或 effect（"viewed" 类事件除外，且应在 useEffect 中触发）;
7. 参数中不含任何 PII（邮箱、IP、全名等），身份上下文只用不透明 ID；
8. 本地用 localStorage.setItem('DEBUG_ANALYTICS', '1') 打开控制台日志，确认事件 payload 符合预期。

此外，埋点模式的选择（路由级页面浏览用 route analytics hooks、按钮点击用 analyticsEventKey prop、其余交互用 trackAnalytics）参见同目录下的 tracking-patterns.md，事件键类型注册完成只是整条埋点工作流中的一环。