AnalyticsCAUTION

Developer-first error tracking and performance monitoring

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: analytics
description: Instrument and discover analytics events in Sentry's frontend UI. Use when adding tracking to buttons, pages, modals, or custom interactions, when defining new analytics events, when searching for existing events, when auditing analytics coverage for a feature, or when answering questions about how users interact with a feature. Trigger on "add analytics", "track event", "instrument analytics", "analytics event", "track click", "track page view", "add tracking", "what events exist for", "audit analytics", "how many people", "how many users", "are people using", "is anyone clicking", "usage of", "who is using".
---

# Analytics Instrumentation

Add analytics events to Sentry's frontend UI using established patterns.

## Answering "How Many People Do X?"

When the user asks about usage, adoption, or interaction counts for a feature:

1. Find the event: search Amplitude first (fastest), fall back to grepping the codebase.
2. If the Amplitude MCP is connected, query the data directly and report results.
3. If no matching event exists, tell the user the event is not tracked — then use `AskUserQuestion` to ask whether they want to instrument it. Do not proceed to instrumentation without explicit confirmation.

Read `references/amplitude-mcp.md` for the full discovery and querying workflow.

## Before Any Change: Search First

**NEVER create a new event without checking if one already exists.**

1. Search `static/app/utils/analytics/` for events matching the feature domain.
2. Grep for keywords related to the interaction (e.g., `clicked`, `viewed`, `created`).
3. If a matching event exists, reuse it — add parameters if needed rather than creating a duplicate.

```bash
grep -rn "keyword" static/app/utils/analytics/ --include="*.tsx"
```

## Event Naming Rules

| Rule                                         | Example                                                                |
| -------------------------------------------- | ---------------------------------------------------------------------- |
| Use `snake_case` with dots as separators     | `feedback.list-item-selected`                                          |
| First segment = feature domain               | `dashboards2.`, `issue_details.`, `feedback.`                          |
| Middle segments = section/context (optional) | `dashboards2.edit.`                                                    |
| Last segment = action                        | `.clicked`, `.viewed`, `.created`, `.changed`                          |
| Match the existing domain file's prefix      | If events are in `feedbackAnalyticsEvents.tsx`, use `feedback.` prefix |

**Standard action suffixes:**

| User action           | Suffix                     |
| --------------------- | -------------------------- |
| Clicks a button/link  | `.clicked` or `_clicked`   |
| Views a page          | `.viewed`                  |
| Submits a form        | `.submitted` or `.created` |
| Changes a setting     | `.changed`                 |
| Renders/loads content | `.rendered` or `.loaded`   |
| Dismisses UI          | `.dismissed`               |
| Opens a modal/panel   | `.opened`                  |

## Choose the Right Tracking Pattern

| What to track                             | Pattern                         | Open reference                                   |
| ----------------------------------------- | ------------------------------- | ------------------------------------------------ |
| Page view on route navigation             | Route analytics hooks           | `references/tracking-patterns.md` § Route-Level  |
| Button or link click                      | Button `analyticsEventKey` prop | `references/tracking-patterns.md` § Button       |
| Custom interaction (toggle, drag, select) | `trackAnalytics()` call         | `references/tracking-patterns.md` § Manual       |
| Modal or panel open/close                 | `trackAnalytics()` in handler   | `references/tracking-patterns.md` § Manual       |
| UI area context for events                | `AnalyticsArea` wrapper         | `references/tracking-patterns.md` § Area Context |

## When You Need to Define a New Event

Read `references/event-definitions.md` for step-by-step instructions.

## Common Mistakes and Debugging

Read `references/troubleshooting.md` when:

- An event isn't firing or appearing in Amplitude
- You see TypeScript errors when calling `trackAnalytics`
- You need to debug analytics locally
- You're unsure whether an event needs an Amplitude name

## Key Files

| File                                                              | Purpose                                                                               |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `static/app/utils/analytics.tsx`                                  | Master registry — all event maps merged, `trackAnalytics` export                      |
| `static/app/utils/analytics/{domain}AnalyticsEvents.tsx`          | Domain-specific event type definitions and name maps                                  |
| `static/app/utils/analytics/makeAnalyticsFunction.tsx`            | Factory that creates typed `trackAnalytics` — do not call directly                    |
| `static/app/utils/routeAnalytics/useRouteAnalyticsEventNames.tsx` | Hook for route-level page view event names                                            |
| `static/app/utils/routeAnalytics/useRouteAnalyticsParams.tsx`     | Hook for route-level page view parameters                                             |
| `static/app/components/analyticsArea.tsx`                         | `AnalyticsArea` component and `useAnalyticsArea` hook                                 |
| `static/app/components/core/button/types.tsx`                     | Button analytics props (`analyticsEventKey`, `analyticsEventName`, `analyticsParams`) |

## Interaction R

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (2)

.claude/skills

api-docs/.node-version

Gates applied: no_behavioural_pass.