Analytics

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.

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

Event Naming Rules

Standard action suffixes:

Choose the Right Tracking Pattern

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

Interaction Rules

Users of this skill may be less technical. Use AskUserQuestion at every decision point instead of dumping plans or code.

Never dump code blocks as a "plan" and then ask "Want me to make these changes?" — either present a short plain-English summary via AskUserQuestion for confirmation, or proceed directly if the user already asked for instrumentation.

Event Pipeline

Every trackAnalytics call flows through the GetSentry override in static/gsApp/utils/rawTrackAnalyticsEvent.tsx:

• Set eventName to a string (e.g., 'Logs Trace Link Clicked') to send to both Reload and Amplitude. This is the default for almost all events.
• Set eventName to null only for high-volume events that would be too expensive for Amplitude. These are Reload-only and queryable via Redash.
• Reload accepts events with allow_no_schema: true — no separate registration step is needed.
• When searching for events, note that Reload-only events (null name) will not appear in Amplitude search. Fall back to grepping the codebase if Amplitude returns no results.

Non-Negotiable Constraints

1. All events must be type-safe. Every event key must exist in a *EventParameters type and be registered in the domain's event map. 2. All events flow through `trackAnalytics()`. Never call window.analytics, Amplitude.track(), or any other analytics SDK directly. 3. Organization context is automatic. Pass organization to trackAnalytics — the override system handles the rest. 4. Reuse over create. Always search for existing events before defining new ones. 5. One event per interaction. Do not fire multiple events for the same user action. 6. No PII in event parameters. Never include user emails, IP addresses, full names, or other personally identifiable information. Use opaque IDs (org ID, user ID) when identity context is needed.

Amplitude MCP — Discovery and Querying

Setup (One-Time)

If the Amplitude MCP is not connected:

1. Tell the user to run /mcp in Claude Code 2. Select "claude.ai Amplitude" from the list 3. Authenticate via Sentry SSO

Once connected, the mcp__claude_ai_Amplitude__* tools become available.

Discover the Amplitude Project

Call get_context to find the Sentry organization and its projects. Use the appId for the sentry.io project as the projectId in all subsequent Amplitude tool calls.

Discovery Workflow

When a user asks "how many people do X?" or "are people using Y?":

Step 1: Find the Event

Use search to find matching events by keyword:

mcp__claude_ai_Amplitude__search({
  queries: ["seer", "autofix"],
  entityTypes: ["EVENT"],
  limitPerQuery: 20,
  search_goal: "Find events related to the seer feature on issue details"
})

This returns Amplitude event names (the eventName from our event maps, e.g., "Issue Details: Seer Opened").

If search returns nothing, fall back to grepping the codebase:

grep -rn "seer\|autofix" static/app/utils/analytics/ --include="*.tsx"

Step 2: Get Event Properties (Optional)

If the user needs to filter or break down by a property:

mcp__claude_ai_Amplitude__get_properties({
  propertyType: "event",
  projectId: "<projectId>",
  eventType: "Issue Details: Seer Opened"
})

Step 3: Query the Data

Use query_dataset for ad-hoc queries:

mcp__claude_ai_Amplitude__query_dataset({
  projectId: "<projectId>",
  definition: {
    type: "eventsSegmentation",
    app: "<projectId>",
    name: "Seer Opens Last 30 Days",
    params: {
      range: "Last 30 Days",
      events: [{
        event_type: "Issue Details: Seer Opened",
        filters: [],
        group_by: []
      }],
      metric: "uniques",
      countGroup: "User",
      groupBy: [],
      interval: 1,
      segments: [{ conditions: [] }]
    }
  }
})

Use query_chart if the user provides an existing chart ID or URL.

Step 4: Report Results

• State the event name used and the date range queried.
• Report unique users (not total event count) unless the user asks for totals.
• Offer to break down by property (platform, org, etc.) if the numbers need context.

Common Query Patterns

Searching for Dashboards and Charts

If the user wants an existing dashboard rather than raw data:

mcp__claude_ai_Amplitude__search({
  queries: ["seer dashboard", "autofix metrics"],
  entityTypes: ["DASHBOARD", "CHART"],
  limitPerQuery: 10
})

When the MCP Is Not Connected

Fall back to the codebase:

1. Grep event files for the Amplitude name (eventName in the event map). 2. Report the event key and Amplitude name so the user can search Amplitude manually. 3. Suggest they connect the Amplitude MCP for direct querying: run /mcp → select "claude.ai Amplitude".

Defining New Analytics Events

Step 1: Find or Create the Domain Event File

Event files live in static/app/utils/analytics/ and follow the naming pattern {domain}AnalyticsEvents.tsx.

Discover existing domain files:

ls static/app/utils/analytics/*AnalyticsEvents.tsx

Prefer adding events to an existing domain file. Create a new file only when the feature has no natural home in an existing domain.

Step 2: Add the Event Type

Add the event key and its parameter types to the domain's *EventParameters type:

export type FeedbackEventParameters = {
  // Existing events...
  'feedback.filter-applied': {
    filter_type: string;
    source: 'list' | 'detail';
  };
};

Parameter typing rules:

Step 3: Add the Event Map Entry

Add the event key → Amplitude display name mapping:

export const feedbackEventMap: Record<keyof FeedbackEventParameters, string | null> = {
  // Existing entries...
  'feedback.filter-applied': 'Feedback: Filter Applied',
};

Amplitude name rules:

The Amplitude name follows 'Domain: Action Description' format in Title Case.

Step 4: Register in the Master Registry

If you created a new domain file, register it in static/app/utils/analytics.tsx:

1. Import the type and event map:

import type {MyDomainEventParameters} from './analytics/myDomainAnalyticsEvents';
import {myDomainEventMap} from './analytics/myDomainAnalyticsEvents';

2. Add the type to the EventParameters interface:

interface EventParameters
  // ...existing types
  extends MyDomainEventParameters, Record<string, Record<string, any>> {}

3. Spread the map into allEventMap:

const allEventMap: Record<string, string | null> = {
  // ...existing maps
  ...myDomainEventMap,
};

If you added events to an existing domain file, skip this step — the domain is already registered.

Complete Example: New Event in Existing Domain

Adding a "filter applied" event to the feedback domain:

// In static/app/utils/analytics/feedbackAnalyticsEvents.tsx

export type FeedbackEventParameters = {
  // ... existing events
  'feedback.filter-applied': {
    filter_type: string;
    source: 'list' | 'detail';
  };
};

export const feedbackEventMap: Record<keyof FeedbackEventParameters, string | null> = {
  // ... existing entries
  'feedback.filter-applied': 'Feedback: Filter Applied',
};

Anti-Pattern: Untyped Event

// BAD — will cause TypeScript error, event key not registered
trackAnalytics('feedback.my-new-thing', {
  organization,
  some_param: 'value',
});

// GOOD — define the event type and map entry first, then call
trackAnalytics('feedback.filter-applied', {
  organization,
  filter_type: 'status',
  source: 'list',
});

Tracking Patterns

Route-Level Page Views

Use route analytics hooks for tracking when a user visits a page. These fire automatically on route navigation.

Where: Inside the top-level component for a route (the component rendered by React Router).

import {useRouteAnalyticsEventNames} from 'sentry/utils/routeAnalytics/useRouteAnalyticsEventNames';
import {useRouteAnalyticsParams} from 'sentry/utils/routeAnalytics/useRouteAnalyticsParams';

function MyFeaturePage() {
  const organization = useOrganization();

  // Register the page view event
  useRouteAnalyticsEventNames('my_feature.viewed', 'My Feature: Viewed');

  // Attach contextual parameters
  useRouteAnalyticsParams({
    has_data: true,
    tab: 'overview',
  });

  return <div>...</div>;
}

Rules:

• Call useRouteAnalyticsEventNames exactly once per route component.
• Call useRouteAnalyticsParams to add context. It can be called multiple times — params merge.
• useRouteAnalyticsParams must be called within 2 seconds of organization context loading.
• Subcomponents can call useRouteAnalyticsParams to add their own params (e.g., trace status, replay availability).
• The event fires automatically — do not also call trackAnalytics for the same page view.

Real-world example (from static/app/views/issueDetails/groupDetails.tsx):

useRouteAnalyticsEventNames('issue_details.viewed', 'Issue Details: Viewed');
useRouteAnalyticsParams({
  ...getAnalyticsDataForGroup(group),
  ...getAnalyticsDataForEvent(event),
  ...getAnalyicsDataForProject(project),
  tab,
  group_event_type: groupEventType,
});

Button Click Tracking

Use built-in button analytics props for simple click tracking. No event definition required for Reload-only tracking.

<Button
  analyticsEventKey="feedback.filter-applied"
  analyticsEventName="Feedback: Filter Applied"
  analyticsParams={{filter_type: 'status', source: 'sidebar'}}
>
  Apply Filter
</Button>

Props:

Rules:

• Prefer button props over a manual trackAnalytics call in an onClick handler.
• If you need the event to be type-safe and appear in the typed event registry, also define it in the domain event file. Button props work without registration but lose type safety.
• The tracking fires via TrackingContext — the GetSentry override wires it to Reload/Amplitude.

Manual trackAnalytics() Calls

Use for interactions that aren't button clicks or page views: toggles, drag actions, form submissions, modal opens, etc.

import {trackAnalytics} from 'sentry/utils/analytics';

function handleFilterChange(filterType: string) {
  trackAnalytics('feedback.filter-applied', {
    organization,
    filter_type: filterType,
    source: 'list',
  });
  // ... actual handler logic
}

Rules:

• Always pass organization (string slug or Organization object).
• The event key must be defined in a *EventParameters type and registered in the domain event map.
• Call trackAnalytics at the point of user action, not in render or effects (unless tracking a "viewed" event).
• For "viewed" events in components that aren't route-level, use a useEffect:

useEffect(() => {
  trackAnalytics('feedback.banner-viewed', {
    organization,
  });
}, [organization]);

Area Context

Use AnalyticsArea to tag events with their UI location. This is useful when the same component appears in multiple contexts.

import {AnalyticsArea, useAnalyticsArea} from 'sentry/components/analyticsArea';

// Wrap a section of UI
<AnalyticsArea name="feedback">
  <AnalyticsArea name="details">
    <MyComponent /> {/* useAnalyticsArea() returns "feedback.details" */}
  </AnalyticsArea>
</AnalyticsArea>;

// Use in a component
function MyComponent() {
  const area = useAnalyticsArea();

  function handleClick() {
    trackAnalytics('feedback.action-clicked', {
      organization,
      area, // "feedback.details"
    });
  }
}

Rules:

• Areas nest with dot notation: outer.inner.
• Use overrideParent to strip the outer area (e.g., for modals that should have their own top-level area).
• Do not branch app logic on the area value — it is for analytics metadata only.

Choosing Between Patterns

Troubleshooting

Common Mistakes

Debugging Locally

Enable analytics debug logging in your browser console:

localStorage.setItem('DEBUG_ANALYTICS', '1');

This logs all trackAnalytics calls and button tracking events to the console. Remove with:

localStorage.removeItem('DEBUG_ANALYTICS');

Anti-Patterns

Direct SDK calls

// NEVER do this
window.analytics.track('my_event', {...});
Amplitude.track('My Event', {...});

// ALWAYS use trackAnalytics
trackAnalytics('my_feature.event', {organization, ...});

Untyped events

// NEVER call trackAnalytics with an unregistered key
// TypeScript will catch this, but if you bypass it with `as any`:
trackAnalytics('nonexistent.event' as any, {organization});

// ALWAYS define the event type first, then call trackAnalytics

Tracking in render

// NEVER track in the render body — fires on every re-render
function MyComponent() {
  trackAnalytics('my_feature.viewed', {organization}); // BAD
  return <div />;
}

// ALWAYS use useEffect for "viewed" events
function MyComponent() {
  useEffect(() => {
    trackAnalytics('my_feature.viewed', {organization});
  }, [organization]);
  return <div />;
}

Creating duplicate events

// NEVER create a new event when one already exists
// Search first: grep -rn "feedback" static/app/utils/analytics/

// If 'feedback.list-item-selected' exists, don't create 'feedback.list_item_clicked'
// Reuse the existing event and add params if needed

Overly broad parameter types

// AVOID — loses type safety
'my_feature.action': {
  type: string;       // What values can this be?
  data: any;          // Completely untyped
};

// PREFER — explicit and self-documenting
'my_feature.action': {
  type: 'create' | 'update' | 'delete';
  item_count: number;
};

Analytics Instrumentation Specification

Intent

Guide users and agents through adding analytics events to Sentry's frontend UI using established patterns. Prioritizes reusing existing events, enforcing type safety, and following naming conventions. Designed to be safe for less-technical users (design, PM, sales) who may not know the analytics architecture.

Scope

In scope:

• Frontend analytics event definition (TypeScript types, event maps)
• Frontend tracking instrumentation (trackAnalytics, route hooks, button props, AnalyticsArea)
• Event naming conventions and parameter typing
• Searching for and reusing existing events
• Local debugging with DEBUG_ANALYTICS

Out of scope:

• Backend analytics event creation (src/sentry/analytics/)
• Amplitude dashboard configuration
• Google Analytics configuration
• Performance metrics (metric.mark, metric.measure)

Users And Trigger Context

• Common user requests: "add analytics to this button", "track when users view this page", "what events exist for dashboards", "I need to track clicks on the new filter"
• Should not trigger for: backend-only analytics, Sentry SDK instrumentation, performance monitoring, error tracking setup

Runtime Contract

• Required first actions: search existing events before defining new ones
• Required outputs: code changes to event definition files and instrumentation call sites
• Non-negotiable constraints: all events must be type-safe; all events flow through trackAnalytics; reuse existing events when possible
• Expected bundled files loaded at runtime: references/event-definitions.md, references/tracking-patterns.md, references/troubleshooting.md, references/amplitude-mcp.md

Source And Evidence Model

Authoritative sources:

• static/app/utils/analytics.tsx — master event registry
• static/app/utils/analytics/*.tsx — domain event definitions
• static/app/utils/analytics/makeAnalyticsFunction.tsx — factory function
• static/app/utils/routeAnalytics/ — route-level tracking hooks
• static/app/components/analyticsArea.tsx — area context
• static/app/components/core/button/types.tsx — button analytics props

Data that must not be stored:

• Customer organization slugs, names, or IDs
• Internal Amplitude project keys
• Reload backend credentials

Reference Architecture

• SKILL.md contains: routing table, naming rules, non-negotiable constraints, key files
• references/event-definitions.md contains: step-by-step event creation, registration, examples
• references/tracking-patterns.md contains: route-level, button, manual, and area tracking patterns
• references/troubleshooting.md contains: common mistakes, debugging, anti-patterns
• references/amplitude-mcp.md contains: Amplitude MCP setup, event discovery, ad-hoc querying, fallback workflow

Validation

• Lightweight validation: TypeScript compilation catches unregistered event keys
• Deeper validation: DEBUG_ANALYTICS=1 in browser console confirms events fire
• Acceptance gates: event key exists in domain type, event map entry exists, trackAnalytics call compiles

Known Limitations

• Reload backend registration is in a separate repo (getsentry/reload) — this skill cannot automate that step
• Button analytics props are not type-checked against the event registry
• Route analytics timing constraint (2s) is not enforced at compile time

Maintenance Notes

• When to update SKILL.md: new tracking patterns added to the codebase, analytics architecture changes
• When to update references: existing patterns deprecated or new tracking patterns introduced