mirror of
https://github.com/supabase/supabase.git
synced 2026-05-06 08:56:46 -04:00
chore: add telemetry standards skill for CodeRabbit (#43436)
## Summary - Adds a combined telemetry standards skill (`.claude/skills/telemetry-standards/SKILL.md`) that covers PostHog event naming conventions, property standards, review rules, and implementation guide - Intended to be imported as CodeRabbit learnings after merge so CodeRabbit can flag missing/incorrect tracking in PRs - Consolidates standards from existing `review-telemetry` and `implement-tracking` Claude commands into a single source of truth ## Post-merge steps ### 1. Import as CodeRabbit learnings (one-time) Comment on any PR in the repo: ``` @coderabbitai add a learning using .claude/skills/telemetry-standards/SKILL.md ``` This teaches CodeRabbit the telemetry standards. It will then: - Flag naming/property violations when `telemetry-constants.ts` is changed - Suggest adding `useTrack()` tracking when PRs add user-facing interactions without it - Propose event names following `[object]_[verb]` convention ### 2. Add path instructions in CodeRabbit web UI (optional, recommended) Go to CodeRabbit settings > Review > Path Instructions and add: - **Path:** `packages/common/telemetry-constants.ts` - **Instructions:** "Strictly enforce event naming: [object]_[verb] in snake_case. Only approved verbs: opened, clicked, submitted, created, removed, updated, retrieved, intended, evaluated, added. Properties must be camelCase and self-explanatory. Flag any usage of useSendEventMutation." ### 3. Remove old Claude commands (after verifying skill works) Delete `.claude/commands/review-telemetry.md` and `.claude/commands/implement-tracking.md` — this skill replaces both. Closes GROWTH-661
This commit is contained in:
@@ -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
|
||||
Reference in New Issue
Block a user