# UTM Cleanup Monitoring Setup Guide

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

## Overview

This guide provides step-by-step instructions for setting up monitoring and alerting for UTM cleanup in Google Tag Manager and Google Analytics 4.

## Events Available

### 1. utm_cleanup_complete

**Fired when:** Cleanup succeeds

**Properties:**

- `event`: 'utm_cleanup_complete'
- `cleanup_success`: true
- `cleanup_duration`: number (milliseconds)
- `had_utms`: boolean
- `had_tracking`: boolean

### 2. utm_cleanup_error

**Fired when:** Cleanup fails

**Properties:**

- `event`: 'utm_cleanup_error'
- `cleanup_success`: false
- `error`: string (error message)

## GTM Setup

### Step 1: Create DataLayer Variables

1. Navigate to **Variables** → **User-Defined Variables**
2. Click **New**
3. Create the following variables:

**Variable 1: Cleanup Success**

- Variable Name: `DLV - Cleanup Success`
- Variable Type: Data Layer Variable
- Data Layer Variable Name: `cleanup_success`
- Data Layer Version: Version 2

**Variable 2: Cleanup Duration**

- Variable Name: `DLV - Cleanup Duration`
- Variable Type: Data Layer Variable
- Data Layer Variable Name: `cleanup_duration`
- Data Layer Version: Version 2

**Variable 3: Cleanup Error**

- Variable Name: `DLV - Cleanup Error`
- Variable Type: Data Layer Variable
- Data Layer Variable Name: `error`
- Data Layer Version: Version 2

**Variable 4: Had UTMs**

- Variable Name: `DLV - Had UTMs`
- Variable Type: Data Layer Variable
- Data Layer Variable Name: `had_utms`
- Data Layer Version: Version 2

**Variable 5: Had Tracking**

- Variable Name: `DLV - Had Tracking`
- Variable Type: Data Layer Variable
- Data Layer Variable Name: `had_tracking`
- Data Layer Version: Version 2

### Step 2: Create Triggers

1. Navigate to **Triggers** → **New**
2. Create the following triggers:

**Trigger 1: UTM Cleanup Complete**

- Trigger Name: `UTM Cleanup Complete`
- Trigger Type: Custom Event
- Event Name: `utm_cleanup_complete`
- This trigger fires on: All Custom Events

**Trigger 2: UTM Cleanup Error**

- Trigger Name: `UTM Cleanup Error`
- Trigger Type: Custom Event
- Event Name: `utm_cleanup_error`
- This trigger fires on: All Custom Events

### Step 3: Create GA4 Tags

1. Navigate to **Tags** → **New**
2. Create the following tags:

**Tag 1: UTM Cleanup Complete**

- Tag Name: `GA4 - UTM Cleanup Complete`
- Tag Type: Google Analytics: GA4 Event
- Configuration Tag: [Your GA4 Configuration Tag]
- Event Name: `utm_cleanup_complete`
- Event Parameters:
  - `cleanup_duration`: `{{DLV - Cleanup Duration}}`
  - `had_utms`: `{{DLV - Had UTMs}}`
  - `had_tracking`: `{{DLV - Had Tracking}}`
- Triggering: `UTM Cleanup Complete`

**Tag 2: UTM Cleanup Error**

- Tag Name: `GA4 - UTM Cleanup Error`
- Tag Type: Google Analytics: GA4 Event
- Configuration Tag: [Your GA4 Configuration Tag]
- Event Name: `utm_cleanup_error`
- Event Parameters:
  - `error`: `{{DLV - Cleanup Error}}`
- Triggering: `UTM Cleanup Error`

### Step 4: Publish Changes

1. Click **Submit**
2. Add version name: "UTM Cleanup Monitoring"
3. Add version description: "Added monitoring for UTM cleanup events"
4. Click **Publish**

## GA4 Setup

### Create Custom Dimensions (Optional)

1. Navigate to **Admin** → **Custom Definitions** → **Custom Dimensions**
2. Click **Create Custom Dimension**
3. Create the following dimensions:

**Dimension 1: Cleanup Duration**

- Dimension Name: `Cleanup Duration`
- Scope: Event
- Event Parameter: `cleanup_duration`
- Description: "Duration of UTM cleanup in milliseconds"

**Dimension 2: Cleanup Success**

- Dimension Name: `Cleanup Success`
- Scope: Event
- Event Parameter: `cleanup_success`
- Description: "Whether UTM cleanup succeeded"

**Dimension 3: Had UTMs**

- Dimension Name: `Had UTMs`
- Scope: Event
- Event Parameter: `had_utms`
- Description: "Whether URL had UTM parameters before cleanup"

### Create Exploration Report

1. Navigate to **Explore** → **Blank**
2. Add dimensions:
   - Event name
   - Cleanup Success (if created)
   - Cleanup Duration (if created)
3. Add metrics:
   - Event count
   - Total users
4. Add filters:
   - Event name = `utm_cleanup_complete` OR `utm_cleanup_error`
5. Save as "UTM Cleanup Monitoring"

### Create Alert

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%
   - Notification: Email to hady@ordio.com
4. Save alert

## Monitoring Dashboard

### Key Metrics to Track

1. **Cleanup Success Rate**
   - Formula: `utm_cleanup_complete / (utm_cleanup_complete + utm_cleanup_error)`
   - Target: >95%
   - Alert if: < 90%

2. **Average Cleanup Duration**
   - Metric: Average of `cleanup_duration`
   - Target: < 50ms
   - Alert if: > 100ms

3. **Error Rate**
   - Formula: `utm_cleanup_error / (utm_cleanup_complete + utm_cleanup_error)`
   - Target: < 5%
   - Alert if: > 10%

4. **Events per Day**
   - Metric: Count of cleanup events
   - Expected: Should match page views with UTMs
   - Alert if: Significant drop

## Testing

### Test Monitoring Setup

1. Visit test page with UTMs:

   ```
   http://localhost:8003/schichtbetriebe?utm_source=test&utm_campaign=test&utm_debug=true
   ```

2. Open GTM Preview Mode
3. Verify events appear in dataLayer
4. Verify tags fire
5. Check GA4 Real-Time reports
6. Verify events appear in GA4

### Test Script

Use `v2/scripts/dev-helpers/test-cleanup-monitoring.php` to test monitoring:

```
http://localhost:8003/v2/scripts/dev-helpers/test-cleanup-monitoring.php?utm_source=test&utm_campaign=test
```

## Troubleshooting

### Events Not Appearing

**Check:**

1. GTM Preview Mode - verify events in dataLayer
2. Browser console - check for JavaScript errors
3. Network tab - verify GTM container loads
4. GA4 DebugView - verify events received

### Tags Not Firing

**Check:**

1. Trigger configuration - verify event name matches
2. Variable configuration - verify dataLayer variable names
3. Tag configuration - verify trigger assigned
4. GTM Preview Mode - check tag firing status

### GA4 Events Not Receiving

**Check:**

1. GA4 Configuration Tag - verify correct measurement ID
2. Consent mode - verify analytics consent granted
3. GA4 DebugView - check for events
4. Network tab - verify requests to GA4

## Related Documentation

- `docs/development/UTM_CLEANUP_IMPROVEMENTS.md` - Improvements implemented
- `docs/development/UTM_CLEANUP_BEST_PRACTICES.md` - Best practices
- `v2/scripts/dev-helpers/test-cleanup-monitoring.php` - Test script