telemetry-standards

Supabase Studio のテレメトリ標準

apps/studio/ における PostHog イベント追跡の標準です。追跡に関わる PR をレビューするときや、新しい追跡を実装するときに適用してください。

イベントの命名

形式： [object]_[verb] のスネークケース

承認済みの動詞のみ（正規リスト — 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 → 追跡しないでください — ユーザー操作がありません

プロパティの標準

大文字・小文字の形式： 新しいイベントではキャメルケースを推奨します。コードベースには既存のスネークケースのプロパティ（例：schema_name、table_name）もあります。既存のイベントにプロパティを追加するときは、そのイベントで確立されている形式に合わせてください。

名前は内容が明確にわかるものにしてください：

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

以下に注意してください：

• 汎用的な名前：label、value、name、data
• パスカルケースのプロパティ
• 類似イベント間で名前に一貫性がない（例：あるイベントではassistantType、関連イベントではaiType）
• 同じイベント内でキャメルケースとスネークケースを混在させる

追跡してはいけないもの

• ページ読み込み時の受動的なビューや描画（dashboard_viewed、sidebar_appeared、page_loaded）
• ユーザー操作を伴わないコンポーネントの表示
• 汎用的な「viewed」や「seen」イベント — ページビューイベントですでに記録されています

追跡するもの： ユーザーのクリック、フォーム送信、明示的な開閉、ユーザーが開始したアクション。

例外： A/B 実験の露出を追跡する_exposedイベントは、描画時に発火する場合でも有効です。

イベントのプロパティに個人を特定できる情報（メールアドレス、名前、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、またはuseDataApiRevokeOnCreateDefaultEnabledなどの PostHog を利用するフック）：関連するtrack()呼び出しでフラグの値を記録します。
• ConfigCat フラグ（commonからのuseFlag）は別のシステムです。このパターンは適用されません。

PostHog ストアの読み込み中、usePHFlagはundefinedを返します。ラッパーフックを通してundefinedをfalseに変換するのではなく、usePHFlag('flagName')でフラグの生の値を読み取り、条件付きスプレッドを使用して、フラグの値が確定するまではプロパティを省略してください（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も追加してください。3つすべてが正確である必要があります。

レビュールール

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 で、内容が分かりやすい
• イベントが正確な @group Events、@source、および（ページ固有の場合は）@page とともに telemetry-constants.ts で定義されている
• useTrack フックを使用している
• 受動的なビュー／表示をトラッキングしていない
• イベントプロパティに PII（メールアドレス、名前、IP アドレスなど）が含まれていない
• プロパティ名が類似イベントと一貫している