telemetry-standards（遥测标准）

Telemetry Standards for Supabase Studio

Standards for PostHog event tracking in apps/studio/. Apply these when reviewing PRs that touch tracking or when implementing new tracking.

Event Naming

Format: [object]_[verb] in snake_case

Approved verbs only (canonical list — derived from 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

Flag these:

• Unapproved verbs (saved, viewed, seen, pressed, etc.)
• Wrong order: click_product_card → should be product_card_clicked
• Wrong casing: productCardClicked → should be product_card_clicked

Good examples:

• product_card_clicked
• backup_button_clicked
• sql_query_submitted

Common mistakes with corrections:

• database_saved → save_button_clicked or database_updated (unapproved verb)
• click_backup_button → backup_button_clicked (wrong order)
• dashboardViewed → don't track passive views on page load
• component_rendered → don't track — no user interaction

Property Standards

Casing: camelCase preferred for new events. The codebase has existing snake_case properties (e.g., schema_name, table_name) — when adding properties to an existing event, match its established convention.

Names must be self-explanatory:

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

Flag these:

• Generic names: label, value, name, data
• PascalCase properties
• Inconsistent names across similar events (e.g., assistantType in one event, aiType in a related event)
• Mixing camelCase and snake_case within the same event

What NOT to Track

• Passive views/renders on page load (dashboard_viewed, sidebar_appeared, page_loaded)
• Component appearances without user interaction
• Generic "viewed" or "seen" events — already captured by pageview events

DO track: user clicks, form submissions, explicit opens/closes, user-initiated actions.

Exception: _exposed events for A/B experiment exposure tracking are valid even though they fire on render.

Never track PII (emails, names, IPs, etc.) in event properties.

Required Pattern

Import useTrack from lib/telemetry/track (within apps/studio/). Never use useSendEventMutation (deprecated).

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>
}

Event Definitions

All events must be defined as TypeScript interfaces in packages/common/telemetry-constants.ts:

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

Add the new interface to the TelemetryEvent union type so useTrack picks it up. @group Events and @source must be accurate.

Review Rules

When reviewing a PR, flag these as required changes:

1. Naming violations — event not following [object]_[verb] snake_case, or using an unapproved verb
2. Property violations — not camelCase, generic names, or inconsistent with similar events
3. Deprecated hook — any usage of useSendEventMutation instead of useTrack
4. Unnecessary view tracking — events that fire on page load without user interaction
5. Inaccurate docs — @page/@source descriptions that don't match the actual implementation

When a PR adds user-facing interactions (buttons, forms, toggles, modals) without tracking, suggest:

• "This adds a user interaction that may benefit from tracking."
• Propose the event name following [object]_[verb] convention
• Propose the useTrack() call with suggested properties

When checking property consistency, search packages/common/telemetry-constants.ts for similar events and verify property names match.

Well-Formed Event Examples

From the actual codebase:

// 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',
})

Implementing New Tracking

To add tracking for a user action:

1. Name the event — [object]_[verb] using approved verbs only
2. Choose properties — camelCase preferred for new events; check packages/common/telemetry-constants.ts for similar events and match their property names and casing
3. Add interface to telemetry-constants.ts — with @group Events and @source JSDoc, add to the TelemetryEvent union type
4. Add to component — import {useTrack} from 'lib/telemetry/track', call track('event_name', {properties})

Verification checklist

• Event name follows [object]_[verb] with approved verb
• Event name is snake_case
• Properties are camelCase and self-explanatory
• Event defined in telemetry-constants.ts with accurate @page/@source
• Using useTrack hook (not useSendEventMutation)
• Not tracking passive views/appearances
• No PII in event properties (emails, names, IPs, etc.)
• Property names consistent with similar events