The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
chore: add telemetry standards skill for CodeRabbit (#43436)
Pamela Chia5880966b1553
diff --git a/.claude/skills/telemetry-standards/SKILL.md b/.claude/skills/telemetry-standards/SKILL.mdnew file mode 100644index 00000000000..0ed2f7f85bc--- /dev/null+++ b/.claude/skills/telemetry-standards/SKILL.md@@ -0,0 +1,170 @@+---+name: telemetry-standards+description: PostHog event tracking standards for Supabase Studio. Use when reviewing+ PRs for telemetry compliance or implementing new event tracking. Covers event naming,+ property conventions, approved patterns, and implementation guide.+---++# 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:**+opened, clicked, submitted, created, removed, updated, retrieved, intended, evaluated, added,+enabled, disabled, copied, exposed, failed, converted++**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).++```typescript+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`:++```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+}+```++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:++```typescript+// 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