telemetry-standards

Supabase Studio 的遥测规范

apps/studio/ 中 PostHog 事件追踪的规范。在审核涉及追踪的 PR 或实现新的追踪功能时，请遵循这些规范。

事件命名

格式： [object]_[verb]，使用 snake_case

仅限已批准的动词（规范列表，源自 packages/common/telemetry-constants.ts）： opened、clicked、submitted、created、removed、updated、intended、evaluated、added、 enabled、disabled、copied、exposed、failed、converted、closed、completed、applied、sent、moved

标记以下问题：

• 未批准的动词（saved、viewed、seen、pressed 等）
• 顺序错误：click_product_card → 应为 product_card_clicked
• 大小写错误：productCardClicked → 应为 product_card_clicked

正确示例：

• product_card_clicked
• backup_button_clicked
• sql_query_submitted

常见错误及修正：

• database_saved → save_button_clicked 或 database_updated（动词未获批准）
• click_backup_button → backup_button_clicked（顺序错误）
• dashboardViewed → 不要追踪页面加载时的被动浏览
• component_rendered → 不要追踪，没有用户交互

属性规范

大小写： 新事件优先使用 camelCase。代码库中已有 snake_case 属性（例如 schema_name、table_name）；向现有事件添加属性时，请遵循该事件已有的命名惯例。

名称必须清晰易懂：

• { productType: 'database', planTier: 'pro' }
• { assistantType: 'sql', suggestionType: 'optimization' }

标记以下问题：

• 通用名称：label、value、name、data
• PascalCase 属性
• 类似事件的名称不一致（例如，一个事件使用 assistantType，相关事件却使用 aiType）
• 同一事件中混用 camelCase 和 snake_case

不要追踪的内容

• 页面加载时的被动浏览或渲染（dashboard_viewed、sidebar_appeared、page_loaded）
• 没有用户交互的组件显示
• 通用的“已浏览”或“已查看”事件——页面浏览事件已记录这些信息

应追踪： 用户点击、表单提交、明确的打开或关闭操作、由用户发起的操作。

例外： 用于跟踪 A/B 实验曝光情况的 _exposed 事件是有效的，即使它们在渲染时触发。

绝不在事件属性中追踪 PII（电子邮件、姓名、IP 等）。

必需模式

在 apps/studio/ 中从 @/lib/telemetry/track 导入 useTrack。

import { useTrack } from '@/lib/telemetry/track'

const MyComponent = () => {
  const track = useTrack()

  const handleClick = () => {
    track('product_card_clicked', {
      productType: 'database',
      planTier: 'pro',
      source: 'dashboard',
    })
  }

  return <button onClick={handleClick}>Click me</button>
}

功能标志度量

用于控制行为的功能标志需要针对标志状态以及用户对新行为的响应（切换点击、选择加入操作）进行遥测，以便衡量发布效果。

• PostHog 标志（usePHFlag 或由 PostHog 支持的 Hook，例如 useDataApiRevokeOnCreateDefaultEnabled）：在相关的 track() 调用中记录标志值。
• ConfigCat 标志（来自 common 的 useFlag）属于不同的系统，不适用此模式。

PostHog 存储仍在加载时，usePHFlag 会返回 undefined。通过 usePHFlag('flagName') 读取原始标志，不要通过会将 undefined 强制转换为 false 的包装 Hook 读取；并使用条件展开，以便在标志值确定之前省略该属性（而不是设为 false）：

一如既往，track() 应在用户操作处理函数中运行，绝不要放在组件主体或副作用中：

const track = useTrack()
const flagValue = usePHFlag<boolean>('myBooleanFlag') // for boolean flags

const handleSubmit = () => {
  track('event_name', {
    ...(flagValue !== undefined && { myFlagEnabled: flagValue }),
  })
}

对于字符串类型的标志（例如实验变体），使用 usePHFlag<string>('flagName')；可能从布尔类型迁移为多变量类型的标志，应声明为 usePHFlag<boolean | string>。ProjectCreationForm.tsx（dataApiRevokeOnCreateDefault）是规范示例。

事件定义

所有事件都必须在 packages/common/telemetry-constants.ts 中定义为 TypeScript 接口：

/**
 * [Event description]
 *
 * @group Events
 * @source [what triggers this event]
 */
export interface MyFeatureClickedEvent {
  action: 'my_feature_clicked'
  properties: {
    /** Description of property */
    featureType: string
  }
  groups: TelemetryGroups
}

将新接口添加到 TelemetryEvent 联合类型中，以便 useTrack 能识别该事件。 每个事件都必须包含 @group Events 和 @source；如果事件在特定页面触发，还要添加 @page。这三项都必须准确无误。

审查规则

审查 PR 时，将以下问题标记为必须修改：

1. 命名违规——事件名称不符合 [object]_[verb] snake_case 格式，或使用了未经批准的动词
2. 属性违规——属性名称不是 camelCase、过于笼统，或与类似事件不一致
3. 不必要的页面浏览跟踪——事件在页面加载时触发，且没有用户交互
4. 文档不准确——@source/@page 描述与实际实现不符
5. 未衡量的功能标志——PostHog 标志控制了新行为，但其值未被记录在任何 track() 调用中，或没有跟踪受该标志控制的行为结果

当 PR 新增了未进行跟踪的面向用户交互（按钮、表单、切换开关、模态框）时，请建议：

• “这新增了一项可能值得跟踪的用户交互。”
• 按照 [object]_[verb] 约定提出事件名称
• 提出包含建议属性的 useTrack() 调用

检查属性一致性时，请在 packages/common/telemetry-constants.ts 中查找类似事件，并确认属性名称一致。

格式规范的事件示例

来自实际代码库：

// User copies a connection string
track('connection_string_copied', {
  connectionType: 'psql',
  connectionMethod: 'transaction_pooler',
  connectionTab: 'Connection String',
})

// User enables a feature preview
track('feature_preview_enabled', {
  feature: 'realtime_inspector',
})

// User clicks a banner CTA
track('index_advisor_banner_dismiss_button_clicked')

// Experiment exposure (fires on render — valid exception)
track('home_new_experiment_exposed', {
  variant: 'treatment',
})

实现新的跟踪

为用户操作添加跟踪：

1. 命名事件——使用 [object]_[verb] 格式，且仅使用经过批准的动词
2. 选择属性——新事件优先使用 camelCase；在 packages/common/telemetry-constants.ts 中查找类似事件，并保持属性名称及大小写一致
3. 在 telemetry-constants.ts 中添加接口——添加 @group Events 和 @source JSDoc（页面专属时还需添加 @page），并将其加入 TelemetryEvent 联合类型
4. 添加到组件中——import { useTrack } from '@/lib/telemetry/track'，调用 track('event_name', { properties })

验证清单

• 事件名称遵循 [object]_[verb] 格式，且动词经过批准
• 事件名称为 snake_case
• 属性为 camelCase，且含义明确
• 事件已在 telemetry-constants.ts 中定义，且 @group Events、@source 以及（页面专属时的）@page 均准确无误
• 使用 useTrack hook
• 不跟踪被动浏览或出现事件
• 事件属性中不含 PII（电子邮件、姓名、IP 等）
• 属性名称与类似事件一致