Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

add analytics skill (#68419)

Jakub Chodorowicze6bc40c22361
diff --git a/.claude/skills/analytics-events/SKILL.md b/.claude/skills/analytics-events/SKILL.md
new file mode 100644
index 00000000000..56c002f8976
--- /dev/null
+++ b/.claude/skills/analytics-events/SKILL.md
@@ -0,0 +1,504 @@
+---
+name: analytics-events
+description: Add product analytics events to track user interactions in the Metabase frontend
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Frontend Analytics Events Skill
+
+This skill helps you add product analytics (Snowplow) events to track user interactions in the Metabase frontend codebase.
+
+## Quick Reference
+
+Analytics events in Metabase use Snowplow with typed event schemas. All events must be defined in TypeScript types before use.
+
+**Key Files:**
+- `frontend/src/metabase-types/analytics/event.ts` - Event type definitions
+- `frontend/src/metabase-types/analytics/schema.ts` - Schema registry
+- `frontend/src/metabase/lib/analytics.ts` - Core tracking functions
+- Feature-specific `analytics.ts` files - Tracking function wrappers
+
+## Quick Checklist
+
+When adding a new analytics event:
+
+- [ ] Define event type in `frontend/src/metabase-types/analytics/event.ts`
+- [ ] Add event to appropriate union type (e.g., `DataStudioEvent`, `SimpleEvent`)
+- [ ] Create tracking function in feature's `analytics.ts` file
+- [ ] Import and call tracking function at the interaction point
+- [ ] Use `trackSimpleEvent()` for basic events (most common)
+
+## Event Schema Types
+
+### 1. Simple Events (Most Common)
+
+Use `SimpleEventSchema` for straightforward tracking. It supports these standard fields:
+
+```typescript
+type SimpleEventSchema = {
+ event: string; // Required: Event name (snake_case)
+ target_id?: number | null; // Optional: ID of affected entity
+ triggered_from?: string | null; // Optional: UI location/context
+ duration_ms?: number | null; // Optional: Duration in milliseconds
+ result?: string | null; // Optional: Outcome (e.g., "success", "failure")
+ event_detail?: string | null; // Optional: Additional detail/variant
+};
+```
+
+**When to use:** 90% of events fit this schema. Use for clicks, opens, closes, creates, deletes, etc.
+
+### 2. Custom Schemas (legacy, no events are being added)
+
+Consider adding new event schema only in very special cases.
+
+**Examples:** `DashboardEventSchema`, `CleanupEventSchema`, `QuestionEventSchema`
+
+## Step-by-Step: Adding a Simple Event
+
+### Example: Track when a user applies filters in a table picker
+
+#### Step 1: Define Event Types
+
+Add event type definitions to `frontend/src/metabase-types/analytics/event.ts`:
+
+```typescript
+export type DataStudioTablePickerFiltersAppliedEvent = ValidateEvent<{
+ event: "data_studio_table_picker_filters_applied";
+}>;
+
+export type DataStudioTablePickerFiltersClearedEvent = ValidateEvent<{
+ event: "data_studio_table_picker_filters_cleared";
+}>;
+```
+
+#### Step 2: Add to Union Type
+
+Find or create the appropriate union type and add your events:
+
+```typescript
+export type DataStudioEvent =
+ | DataStudioLibraryCreatedEvent
+ | DataStudioTablePublishedEvent
+ | DataStudioGlossaryCreatedEvent
+ | DataStudioGlossaryEditedEvent
+ | DataStudioGlossaryDeletedEvent
+ | DataStudioTablePickerFiltersAppliedEvent // <- Add here
+ | DataStudioTablePickerFiltersClearedEvent; // <- Add here
+```
+
+#### Step 3: Create Tracking Functions
+
+In your feature's `analytics.ts` file (e.g., `enterprise/frontend/src/metabase-enterprise/data-studio/analytics.ts`):
+
+```typescript
+import { trackSimpleEvent } from "metabase/lib/analytics";
+
+export const trackDataStudioTablePickerFiltersApplied = () => {
+ trackSimpleEvent({
+ event: "data_studio_table_picker_filters_applied",
+ });
+};
+
+export const trackDataStudioTablePickerFiltersCleared = () => {
+ trackSimpleEvent({
+ event: "data_studio_table_picker_filters_cleared",
+ });
+};
+```
+
+#### Step 4: Use in Components
+
+Import and call the tracking function at the interaction point:
+
+```typescript
+import {
+ trackDataStudioTablePickerFiltersApplied,
+ trackDataStudioTablePickerFiltersCleared,
+} from "metabase-enterprise/data-studio/analytics";
+
+function FilterPopover({ filters, onSubmit }) {
+ const handleReset = () => {
+ trackDataStudioTablePickerFiltersCleared(); // <- Track here
+ onSubmit(emptyFilters);
+ };
+
+ return (
+ <form
+ onSubmit={(event) => {
+ event.preventDefault();
+ trackDataStudioTablePickerFiltersApplied(); // <- Track here
+ onSubmit(form);
+ }}
+ >
+ {/* form content */}
+ </form>
+ );
+}
+```
+
+## Using SimpleEventSchema Fields
+
+### Example: Event with target_id
+
+```typescript
+// Type definition
+export type DataStudioLibraryCreatedEvent = ValidateEvent<{
+ event: "data_studio_library_created";
+ target_id: number | null;
+}>;
+
+// Tracking function
+export const trackDataStudioLibraryCreated = (id: CollectionId) => {
+ trackSimpleEvent({
+ event: "data_studio_library_created",
+ target_id: Number(id),
+ });
+};
+
+// Usage
+trackDataStudioLibraryCreated(newLibrary.id);
+```
+
+### Example: Event with triggered_from
+
+```typescript
+// Type definition
+export type NewButtonClickedEvent = ValidateEvent<{
+ event: "new_button_clicked";
+ triggered_from: "app-bar" | "empty-collection";
+}>;
+
+// Tracking function
+export const trackNewButtonClicked = (location: "app-bar" | "empty-collection") => {
+ trackSimpleEvent({
+ event: "new_button_clicked",
+ triggered_from: location,
+ });
+};
+
+// Usage
+<Button onClick={() => {
+ trackNewButtonClicked("app-bar");
+ handleCreate();
+}}>
+ New
+</Button>
+```
+
+### Example: Event with event_detail
+
+```typescript
+// Type definition
+export type MetadataEditEvent = ValidateEvent<{
+ event: "metadata_edited";
+ event_detail: "type_casting" | "semantic_type_change" | "visibility_change";
+ triggered_from: "admin" | "data_studio";
+}>;
+
+// Tracking function
+export const trackMetadataChange = (
+ detail: "type_casting" | "semantic_type_change" | "visibility_change",
+ location: "admin" | "data_studio"
+) => {
+ trackSimpleEvent({
+ event: "metadata_edited",
+ event_detail: detail,
+ triggered_from: location,
+ });
+};
+
+// Usage
+trackMetadataChange("semantic_type_change", "data_studio");
+```
+
+### Example: Event with result and duration
+
+```typescript
+// Type definition
+export type MoveToTrashEvent = ValidateEvent<{
+ event: "moved-to-trash";
+ target_id: number | null;
+ triggered_from: "collection" | "detail_page" | "cleanup_modal";
+ duration_ms: number | null;
+ result: "success" | "failure";
+ event_detail: "question" | "model" | "metric" | "dashboard";
+}>;
+
+// Tracking function
+export const trackMoveToTrash = (params: {
+ targetId: number | null;
+ triggeredFrom: "collection" | "detail_page" | "cleanup_modal";
+ durationMs: number | null;
+ result: "success" | "failure";
+ itemType: "question" | "model" | "metric" | "dashboard";
+}) => {
+ trackSimpleEvent({
+ event: "moved-to-trash",
+ target_id: params.targetId,
+ triggered_from: params.triggeredFrom,
+ duration_ms: params.durationMs,
+ result: params.result,
+ event_detail: params.itemType,
+ });
+};
+
+// Usage with timing
+const startTime = Date.now();
+try {
+ await moveToTrash(item);
+ trackMoveToTrash({
+ targetId: item.id,
+ triggeredFrom: "collection",
+ durationMs: Date.now() - startTime,
+ result: "success",
+ itemType: "question",
+ });
+} catch (error) {
+ trackMoveToTrash({
+ targetId: item.id,
+ triggeredFrom: "collection",
+ durationMs: Date.now() - startTime,
+ result: "failure",
+ itemType: "question",
+ });
+}
+```
+
+## Naming Conventions
+
+### Event Names (snake_case)
+
+```typescript
+// Good
+"data_studio_library_created"
+"table_picker_filters_applied"
+"metabot_chat_opened"
+
+// Bad
+"DataStudioLibraryCreated" // Wrong case
+"tablePickerFiltersApplied" // Wrong case
+"filters-applied" // Use underscore, not hyphen
+```
+
+### Event Type Names (PascalCase with "Event" suffix)
+
+```typescript
+// Good
+DataStudioLibraryCreatedEvent
+TablePickerFiltersAppliedEvent
+MetabotChatOpenedEvent
+
+// Bad
+dataStudioLibraryCreated // Wrong case
+DataStudioLibraryCreated // Missing "Event" suffix
+```
+
+### Tracking Function Names (camelCase with "track" prefix)
+
+```typescript
+// Good
+trackDataStudioLibraryCreated
+trackTablePickerFiltersApplied
+trackMetabotChatOpened
+
+// Bad
+DataStudioLibraryCreated // Missing "track" prefix
+track_library_created // Wrong case
+logLibraryCreated // Use "track" prefix
+```
+
+## Common Patterns
+
+### Pattern 1: Feature-Specific Union Types
+
+Group related events together:
+
+```typescript
+export type DataStudioEvent =
+ | DataStudioLibraryCreatedEvent
+ | DataStudioTablePublishedEvent
+ | DataStudioGlossaryCreatedEvent;
+
+export type MetabotEvent =
+ | MetabotChatOpenedEvent
+ | MetabotRequestSentEvent
+ | MetabotFixQueryClickedEvent;
+
+// Then add to SimpleEvent union
+export type SimpleEvent =
+ | /* other events */
+ | DataStudioEvent
+ | MetabotEvent
+ | /* more events */;
+```
+
+### Pattern 2: Conditional Tracking
+
+Track different events based on user action:
+
+```typescript
+const handleSave = async () => {
+ if (isNewItem) {
+ await createItem(data);
+ trackItemCreated(newItem.id);
+ } else {
+ await updateItem(id, data);
+ trackItemUpdated(id);
+ }
+};
+```
+
+## Common Pitfalls
+
+### Don't: Add custom fields to SimpleEvent
+
+```typescript
+// WRONG - SimpleEvent doesn't support custom fields
+export const trackFiltersApplied = (filters: FilterState) => {
+ trackSimpleEvent({
+ event: "filters_applied",
+ data_layer: filters.dataLayer, // ❌ Not in SimpleEventSchema
+ data_source: filters.dataSource, // ❌ Not in SimpleEventSchema
+ with_owner: filters.hasOwner, // ❌ Not in SimpleEventSchema
+ });
+};
+
+// RIGHT - Use only standard SimpleEventSchema fields
+export const trackFiltersApplied = () => {
+ trackSimpleEvent({
+ event: "filters_applied",
+ });
+};
+
+// Or use event_detail for a single variant
+export const trackFilterApplied = (filterType: string) => {
+ trackSimpleEvent({
+ event: "filter_applied",
+ event_detail: filterType, // ✓ "data_layer", "data_source", etc.
+ });
+};
+```
+
+### Don't: Forget to add event to union type
+
+```typescript
+// Define the event
+export type NewFeatureClickedEvent = ValidateEvent<{
+ event: "new_feature_clicked";
+}>;
+
+// ❌ WRONG - Forgot to add to SimpleEvent union
+// Event won't be recognized by TypeScript
+
+// ✓ RIGHT - Add to appropriate union
+export type SimpleEvent =
+ | /* other events */
+ | NewFeatureClickedEvent;
+```
+
+### Don't: Mix up event name formats
+
+```typescript
+// WRONG
+event: "dataStudioLibraryCreated" // camelCase
+event: "data-studio-library-created" // kebab-case
+event: "Data_Studio_Library_Created" // Mixed case
+
+// RIGHT
+event: "data_studio_library_created" // snake_case
+```
+
+### Don't: Track PII or sensitive data
+
+```typescript
+// WRONG - Don't track user emails, names, or sensitive data
+trackSimpleEvent({
+ event: "user_logged_in",
+ event_detail: user.email, // ❌ PII
+});
+
+// RIGHT - Track non-sensitive identifiers only
+trackSimpleEvent({
+ event: "user_logged_in",
+ target_id: user.id, // ✓ Just the ID
+});
+```
+
+### Don't: Forget to track both success and failure
+
+```typescript
+// WRONG - Only tracking success
+try {
+ await saveData();
+ trackDataSaved();
+} catch (error) {
+ // ❌ No tracking for failure case
+}
+
+// RIGHT - Track both outcomes
+try {
+ await saveData();
+ trackDataSaved({ result: "success" });
+} catch (error) {
+ trackDataSaved({ result: "failure" });
+}
+```
+
+## Testing Analytics Events
+
+While developing, you can verify events are firing:
+
+1. **Check browser console** - When `SNOWPLOW_ENABLED=true` in dev, events are logged
+2. **Use shouldLogAnalytics** - Set in `metabase/env` to see all analytics in console
+3. **Check Snowplow debugger** - Browser extension for Snowplow events
+
+Example console output:
+
+```
+[SNOWPLOW EVENT | event sent:true], data_studio_table_picker_filters_applied
+```
+
+## File Organization
+
+### Where to put tracking functions:
+
+```
+Feature-specific analytics functions:
+frontend/src/metabase/{feature}/analytics.ts
+enterprise/frontend/src/metabase-enterprise/{feature}/analytics.ts
+
+Event type definitions (all in one place):
+frontend/src/metabase-types/analytics/event.ts
+
+Core tracking utilities:
+frontend/src/metabase/lib/analytics.ts
+```
+
+## Real-World Examples
+
+See these files for reference:
+
+- **Simple events**: `enterprise/frontend/src/metabase-enterprise/data-studio/analytics.ts`
+- **Events with variants**: `frontend/src/metabase/dashboard/analytics.ts`
+- **Complex events**: `frontend/src/metabase/query_builder/analytics.js`
+- **Event type examples**: `frontend/src/metabase-types/analytics/event.ts`
+
+## Workflow Summary
+
+1. **Identify the user interaction** to track
+2. **Decide on event name** (snake_case, descriptive)
+3. **Define event type** in `event.ts` using `ValidateEvent`
+4. **Add to union type** (create feature union if needed)
+5. **Create tracking function** in feature's `analytics.ts`
+6. **Import and call** at the interaction point
+7. **Test** that events fire correctly
+
+## Tips
+
+- **Be specific** - `filters_applied` is better than `action_performed`
+- **Use past tense** - `library_created` not `create_library`
+- **Group related events** - Create feature-specific event union types
+- **Track meaningful actions** - Not every click needs tracking
+- **Consider the data** - What would you want to analyze later?
+- **Stay consistent** - Follow existing naming patterns in the codebase
+- **Document context** - Use `triggered_from` to track where the action happened
diff --git a/CLAUDE.md b/CLAUDE.md
index 3c33dd34859..479ab0046ee 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -19,6 +19,10 @@ For detailed guidance on writing and reviewing code and documentation, see the s
- **[docs-write](.claude/skills/docs-write/SKILL.md)** - Documentation writing with Metabase style guide
- **[docs-review](.claude/skills/docs-review/SKILL.md)** - Documentation review checklist
+## Frontend
+
+- **[analytics-events](.claude/skills/analytics-events/SKILL.md)** - Add product analytics events to track user interactions
+
## Tool Preferences
If `clojure-mcp` tools are available, prefer them over shell-based alternatives for Clojure development.