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/).

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

Feature Flag Measurement

A feature flag that gates behavior needs telemetry on both the flag state and how users respond to the new behavior (toggle clicks, opt-in actions), so the rollout can be measured.

• PostHog flags (usePHFlag, or PostHog-backed hooks such as useDataApiRevokeOnCreateDefaultEnabled): capture the flag value in a relevant track() call.
• ConfigCat flags (useFlag from common) are a different system — this pattern does not apply to them.

usePHFlag returns undefined while the PostHog store is still loading. Read the raw flag via usePHFlag('flagName'), not through wrapper hooks that coerce undefined to false, and use a conditional spread so the property is omitted (not false) until the flag has resolved:

As always, track() runs inside the user-action handler — never in the component body or an effect:

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

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

For string-valued flags (e.g. experiment variants), use usePHFlag<string>('flagName'); a flag that may be migrated from boolean to multivariate is typed usePHFlag<boolean | string>. ProjectCreationForm.tsx (dataApiRevokeOnCreateDefault) is the canonical example.

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 are required on every event; add @page when the event fires from a specific page. All three must be accurate.