Amplitude Troubleshooting & Debugging

Symptom Library

Common Amplitude Issues

Identity & User Tracking Issues

• User ID not persisting - Users re-identified on each session
• Device ID conflicts - Same user counted multiple times
• Merge conflicts - User profiles not unifying correctly
• Anonymous to identified transition - Lost event history after login
• Cross-platform identity - Web and mobile users not linked

Data Quality Problems

• Event properties missing or malformed
• Timestamp drift causing events out of order
• Duplicate events from retry logic
• Schema validation failures blocking events
• Rate limiting causing data loss

Investigation Workflow

Step 1: Verify Event Instrumentation

// Enable Amplitude debug mode in browser console
amplitude.getInstance().setOptOut(false);
amplitude.getInstance().setLogLevel('DEBUG');

// Verify SDK initialization
console.log('Amplitude Instance:', amplitude.getInstance());
console.log('API Key:', amplitude.getInstance().options.apiKey);
console.log('User ID:', amplitude.getInstance().options.userId);
console.log('Device ID:', amplitude.getInstance().options.deviceId);

// Test event tracking
amplitude.getInstance().logEvent('Test Event', {
  test_property: 'test_value',
  timestamp: new Date().toISOString()
});

// Check event queue
console.log('Event Queue:', amplitude.getInstance()._unsentEvents);

Step 2: Use Amplitude Instrumentation Explorer

1. Navigate to your project in Amplitude
2. Click "Data" > "Instrumentation Explorer"
3. Select the source to debug (Web, iOS, Android, etc.)
4. View live event stream for your test device
5. Verify events appear with correct properties

Step 3: Check User Lookup

# Query specific user via Amplitude dashboard
# Navigate to: Data > User Lookup
# Enter User ID or Device ID
# Review:
# - Event history
# - User properties
# - Cohort memberships
# - Last seen timestamp

Step 4: Inspect Network Requests

Chrome DevTools

1. Open DevTools > Network tab
2. Filter for "amplitude.com"
3. Look for POST requests to /2/httpapi or /batch
4. Check request payload for your events
5. Verify 200 OK response with {"code": 200} body

Common Response Codes

• 200: Success
• 400: Invalid request (check event structure)
• 429: Rate limited (reduce event volume)
• 500: Server error (retry with exponential backoff)

Decision Tree

Issue Reported
│
├─ Events missing entirely?
│  ├─ YES → Check SDK initialization
│  │        → Verify API key
│  │        → Check ad blockers/CSP policies
│  │
│  └─ NO → Events delayed?
│           ├─ YES → Check network connectivity
│           │        → Review batching configuration
│           │
│           └─ NO → Data incorrect?
│                    → Validate event properties
│                    → Check instrumentation code
│                    → Review data transformations

Tools & Logs

Amplitude Debugging Tools

1. Instrumentation Explorer

• Location: Amplitude Dashboard > Data > Instrumentation Explorer
• Real-time event stream monitoring
• Filter by device ID, user ID, or event type
• Retention: Last 30 days of live data

2. User Lookup Tool

• Location: Amplitude Dashboard > Data > User Lookup
• Individual user event history
• User property timeline
• Cohort membership tracking
• Retention: Full data retention period

3. Amplitude Chrome Extension

• Real-time event inspection
• Property validation
• User ID/Device ID verification
• Event queue monitoring

4. Server-Side Validation

# Python script to validate Amplitude tracking
import requests
import json
from datetime import datetime

def check_amplitude_events(api_key, secret_key, user_id, hours=24):
    """Query Amplitude API to verify events for specific user"""

    url = 'https://amplitude.com/api/2/export'
    params = {
        'start': (datetime.now() - timedelta(hours=hours)).strftime('%Y%m%dT%H'),
        'end': datetime.now().strftime('%Y%m%dT%H')
    }

    response = requests.get(url, params=params, auth=(api_key, secret_key))

    # Parse NDJSON response
    events = []
    for line in response.text.strip().split('\n'):
        event = json.loads(line)
        if event.get('user_id') == user_id:
            events.append(event)

    print(f"Found {len(events)} events for user {user_id}")
    for event in events[:10]:  # Show first 10
        print(f"  - {event['event_type']} at {event['event_time']}")

    return events

# Usage
events = check_amplitude_events(
    api_key='YOUR_API_KEY',
    secret_key='YOUR_SECRET_KEY',
    user_id='user_12345',
    hours=24
)

Log Access & Retention

Event Log Export

• Access: Dashboard > Project Settings > Export Data
• Retention: Based on plan (30 days to unlimited)
• Format: NDJSON (newline-delimited JSON)
• Export methods: API, Amazon S3, Google Cloud Storage

Audit Log

• Location: Settings > Audit Log
• Retention: 90 days
• Contains: User actions, configuration changes, data deletions

Integration Logs

• Location: Data > Sources > [Integration] > Status
• Shows sync status, error messages, last successful sync
• Retention: 30 days

Escalation & Communication

When to Escalate

Escalate to Amplitude Support When:

• Widespread data loss (>10% of expected volume)
• Processing delays exceeding 1 hour
• Schema enforcement blocking valid events
• Billing discrepancies for event volume
• Feature bugs or unexpected behavior

Escalate to Stakeholders When:

• Missing data affects published dashboards
• Revenue metrics show anomalies
• User segmentation is incorrect
• SLA violations occur

Incident Communication Template

**Incident:** Missing Purchase Events

**Discovered:** 2025-12-26 14:30 PST

**Impact:**
- Affected Events: Purchase, Revenue
- Time Range: 12:00 PM - 2:00 PM PST (2 hours)
- Estimated Loss: ~500 purchase events
- Affected Reports: Revenue dashboard, conversion funnel
- Business Impact: Unable to track campaign ROI for 2-hour period

**Root Cause:** SDK upgrade introduced breaking change in revenue property format

**Resolution:**
1. Rolled back SDK to previous version (completed 14:45 PST)
2. Verified tracking resumed (completed 15:00 PST)
3. Backfilled missing data via server-side API (ETA: 16:00 PST)

**Prevention:**
- Add automated tests for revenue tracking before SDK upgrades
- Implement canary deployment for tracking changes
- Set up real-time alerts for revenue event drops

**Status:** Resolved

**Next Steps:** Post-mortem scheduled for 2025-12-27

Amplitude Support Ticket Template

Subject: [URGENT] Revenue Events Not Recording

Project: Production (App ID: 123456)
Issue Type: Data Collection
Severity: P1 - Critical

Description:
Purchase events stopped recording at approximately 12:00 PM PST today (2025-12-26).
- Last successful event: 11:58 AM PST
- Expected volume: ~250 events/hour
- Actual volume: 0 events since 12:00 PM
- SDK version: amplitude-js@8.21.4
- Platform: Web (JavaScript)

Troubleshooting Completed:
✓ Verified tracking code fires (browser debugger shows events)
✓ Checked network requests (200 OK responses from Amplitude API)
✓ Tested in multiple browsers - same issue
✓ Instrumentation Explorer shows no events for test device
✓ User Lookup returns no purchase events in affected timeframe

Additional Information:
- No recent code deployments
- No SDK version changes
- Issue affects all users globally
- Other events (Page View, Button Click) tracking correctly

Requested Action:
- Investigate server-side processing for purchase events
- Confirm whether data can be recovered
- Provide ETA for resolution

Attachments:
- network_trace.har
- browser_console_log.txt
- instrumentation_screenshot.png

Preventive Maintenance

Recurring Monitoring Schedule

Daily

• Review event volume dashboard for anomalies
• Check Instrumentation Explorer for error patterns
• Monitor active user counts for unexpected drops
• Scan error logs for new issues

Weekly

• Audit event schema for undefined properties
• Review blocked events report
• Check integration sync status
• Validate critical conversion events

Monthly

• Full QA of instrumentation across platforms
• Review and update event taxonomy
• Audit user property usage
• Performance review of custom dashboards

Quarterly

• SDK version audit and upgrade planning
• Review data governance policies
• Assess need for new integrations
• Optimize event volume and costs

Automated Alerting

# Automated monitoring script for Amplitude
import requests
import schedule
import time
from datetime import datetime, timedelta

class AmplitudeMonitor:
    def __init__(self, api_key, secret_key):
        self.api_key = api_key
        self.secret_key = secret_key
        self.base_url = 'https://amplitude.com/api/2'

    def check_event_volume(self, event_name, threshold_percent=30):
        """Alert if event volume drops below threshold"""

        # Get event count for last hour
        recent_count = self.get_event_count(event_name, hours=1)

        # Get baseline (average of previous 7 days, same hour)
        baseline = self.get_baseline_count(event_name)

        if recent_count < baseline * (1 - threshold_percent/100):
            self.send_alert(
                f"Event volume drop detected for {event_name}: "
                f"{recent_count} (expected ~{baseline})"
            )

    def check_revenue_tracking(self):
        """Alert if no revenue events in last hour during business hours"""
        hour = datetime.now().hour
        if 9 <= hour <= 17:  # Business hours
            revenue_events = self.get_event_count('Purchase', hours=1)
            if revenue_events == 0:
                self.send_alert("No purchase events in last hour during business hours!")

    def send_alert(self, message):
        """Send alert via Slack/PagerDuty"""
        webhook_url = 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL'
        requests.post(webhook_url, json={'text': f"⚠️ Amplitude Alert: {message}"})

# Schedule checks
monitor = AmplitudeMonitor('YOUR_API_KEY', 'YOUR_SECRET_KEY')

schedule.every(15).minutes.do(monitor.check_event_volume, 'Page Viewed')
schedule.every(15).minutes.do(monitor.check_revenue_tracking)

while True:
    schedule.run_pending()
    time.sleep(60)

Risk Reduction Backlog

High Priority

• Implement automated regression tests for tracking
• Set up synthetic monitoring for critical user flows
• Create event schema validation in CI/CD pipeline
• Build real-time data quality dashboard

Medium Priority

• Migrate to server-side tracking for critical events
• Implement event deduplication logic
• Create comprehensive tracking documentation
• Set up A/B testing framework for tracking changes

Low Priority

• Archive unused events and properties
• Optimize SDK bundle size
• Consolidate redundant user properties
• Clean up test/development data