# UTM Cleanup Alerts Configuration

**Last Updated:** 2026-01-29

## Alert Configuration

### Alert 1: Cleanup Error Rate High

**Purpose:** Alert when cleanup failure rate exceeds threshold

**Configuration:**

- **Metric:** Error rate
- **Formula:** `utm_cleanup_error / (utm_cleanup_complete + utm_cleanup_error) * 100`
- **Threshold:** > 10%
- **Time Window:** 1 hour
- **Recipients:** hady@ordio.com
- **Frequency:** Once per hour if threshold exceeded

**GA4 Setup:**

1. Navigate to **Admin** → **Custom Alerts**
2. Click **New Alert**
3. Configure:
   - Alert Name: "UTM Cleanup Error Rate High"
   - Event: `utm_cleanup_error`
   - Condition: Error rate > 10% (over 1 hour)
   - Notification: Email to hady@ordio.com

### Alert 2: Cleanup Success Rate Low

**Purpose:** Alert when cleanup success rate drops below threshold

**Configuration:**

- **Metric:** Success rate
- **Formula:** `utm_cleanup_complete / (utm_cleanup_complete + utm_cleanup_error) * 100`
- **Threshold:** < 90%
- **Time Window:** 1 hour
- **Recipients:** hady@ordio.com
- **Frequency:** Once per hour if threshold exceeded

**GA4 Setup:**

1. Navigate to **Admin** → **Custom Alerts**
2. Click **New Alert**
3. Configure:
   - Alert Name: "UTM Cleanup Success Rate Low"
   - Event: `utm_cleanup_complete`
   - Condition: Success rate < 90% (over 1 hour)
   - Notification: Email to hady@ordio.com

### Alert 3: Cleanup Duration High

**Purpose:** Alert when cleanup takes too long

**Configuration:**

- **Metric:** Average cleanup duration
- **Threshold:** > 100ms
- **Time Window:** 1 hour
- **Recipients:** hady@ordio.com
- **Frequency:** Once per hour if threshold exceeded

**GA4 Setup:**

1. Navigate to **Admin** → **Custom Alerts**
2. Click **New Alert**
3. Configure:
   - Alert Name: "UTM Cleanup Duration High"
   - Event: `utm_cleanup_complete`
   - Condition: Average `cleanup_duration` > 100ms (over 1 hour)
   - Notification: Email to hady@ordio.com

### Alert 4: No Cleanup Events

**Purpose:** Alert if cleanup events stop firing (possible code issue)

**Configuration:**

- **Metric:** Event count
- **Threshold:** 0 events in 2 hours
- **Time Window:** 2 hours
- **Recipients:** hady@ordio.com
- **Frequency:** Once per 2 hours if threshold exceeded

**GA4 Setup:**

1. Navigate to **Admin** → **Custom Alerts**
2. Click **New Alert**
3. Configure:
   - Alert Name: "UTM Cleanup Events Missing"
   - Event: `utm_cleanup_complete` OR `utm_cleanup_error`
   - Condition: Event count = 0 (over 2 hours)
   - Notification: Email to hady@ordio.com

## Monitoring Dashboard

### Create Dashboard in GA4

1. Navigate to **Explore** → **Blank**
2. Add dimensions:
   - Event name
   - Date
3. Add metrics:
   - Event count
   - Total users
   - Average cleanup duration (if custom dimension created)
4. Add filters:
   - Event name contains `utm_cleanup`
5. Save as "UTM Cleanup Dashboard"

### Key Metrics to Display

1. **Success Rate** (calculated metric)
   - Formula: `utm_cleanup_complete / (utm_cleanup_complete + utm_cleanup_error) * 100`
   - Display as: Percentage
   - Target: >95%

2. **Error Rate** (calculated metric)
   - Formula: `utm_cleanup_error / (utm_cleanup_complete + utm_cleanup_error) * 100`
   - Display as: Percentage
   - Target: <5%

3. **Average Duration**
   - Metric: Average of `cleanup_duration`
   - Display as: Milliseconds
   - Target: <50ms

4. **Total Events**
   - Metric: Count of cleanup events
   - Display as: Number
   - Expected: Should match page views with UTMs

## Testing Alerts

### Test Alert Configuration

1. **Simulate Error:**
   - Disable cleanup via feature flag
   - Visit page with UTMs
   - Verify no cleanup events fire
   - Check if "No Cleanup Events" alert triggers

2. **Simulate High Error Rate:**
   - Temporarily break cleanup code
   - Visit multiple pages with UTMs
   - Verify error events fire
   - Check if "Error Rate High" alert triggers

3. **Verify Alert Delivery:**
   - Check email inbox
   - Verify alert format
   - Verify recipients correct

## Alert Response Procedures

### When Alert Fires

1. **Check GTM Preview Mode:**
   - Verify events in dataLayer
   - Check tag firing status
   - Verify no JavaScript errors

2. **Check Browser Console:**
   - Look for cleanup errors
   - Check for JavaScript errors
   - Verify feature flag status

3. **Check Test Scripts:**
   - Run `test-cleanup-monitoring.php`
   - Verify cleanup events fire
   - Check success/error rates

4. **Investigate Root Cause:**
   - Check recent code changes
   - Verify analytics scripts loading
   - Check browser compatibility

5. **Take Action:**
   - Fix issue if identified
   - Rollback if needed (use feature flag)
   - Document issue and resolution

## Related Documentation

- `docs/monitoring/UTM_CLEANUP_MONITORING_SETUP.md` - Monitoring setup guide
- [`UTM_CLEANUP_ROLLBACK_PLAN.md`](../archive/2026-04-01-docs-cleanup/utm-cleanup-analysis/UTM_CLEANUP_ROLLBACK_PLAN.md) — Rollback procedures (archived analysis)
- `docs/development/UTM_CLEANUP_BEST_PRACTICES.md` - Best practices