Maintenance Windows

Schedule planned downtime to prevent false alerts during deployments, upgrades, or maintenance activities.

Overview

Maintenance windows allow you to temporarily modify test behavior during scheduled maintenance periods. Instead of manually pausing tests or dealing with false alerts, you can:

• Schedule maintenance in advance
• Choose how tests behave during the window
• Automatically resume normal operations when maintenance completes
• Set up recurring maintenance schedules (daily, weekly)

Key Concepts

Behaviors

Maintenance windows support two different behaviors:

Suppress Issues

Tests continue running, but issues are not created or alerted

What happens:

• ✅ Tests execute on schedule
• ✅ Test results are recorded
• ❌ No new issues are created during the window
• ✅ Existing issues can auto-resolve if tests pass
• ❌ No alert notifications are sent

When to use:

• Planned deployments that may cause brief instability
• Database migrations that affect API responses
• Third-party service maintenance (when you know it's happening)
• Blue-green deployment switches

Example scenario:

You're deploying a new version of your API. Tests may fail briefly during the rolling restart, but you don't want to wake up the on-call engineer. Use Suppress Issues to:

• Keep monitoring to verify deployment success
• Prevent false alerts during known instability
• Allow auto-resolution if tests stabilize

Pause Execution

Tests are completely paused - no execution, no results recorded

What happens:

• ❌ Tests do not execute during the window
• ❌ No test results are recorded
• ❌ No issues are created
• ❌ No alert notifications
• ✅ Tests automatically resume after the window

When to use:

• Extended maintenance windows (hours or days)
• Service intentionally shut down for upgrades
• Cost optimization (pause non-critical tests overnight)
• Environments that are down during maintenance

Example scenario:

You're performing a major database upgrade that will take 4 hours. The API will be completely offline. Use Pause Execution to:

• Avoid wasting test execution quota
• Prevent result history gaps that show as downtime
• Resume automatically when maintenance completes

Recurrence Types

One-Time

Single maintenance window with specific start and end times.

Example:

Title: Database Migration
Start: 2024-01-15 02:00 AM UTC
End: 2024-01-15 06:00 AM UTC
Recurrence: One-Time

Daily

Repeats every day at the same time.

Example:

Title: Nightly Backup Window
Start: 2024-01-15 03:00 AM UTC
End: 2024-01-15 03:30 AM UTC
Recurrence: Daily

This window will occur every day from 3:00-3:30 AM UTC.

Weekly

Repeats every week on the same day and time.

Example:

Title: Weekly Maintenance
Start: 2024-01-15 01:00 AM UTC (Monday)
End: 2024-01-15 02:00 AM UTC
Recurrence: Weekly

This window will occur every Monday from 1:00-2:00 AM UTC.

Scope Options

Control which tests are affected by the maintenance window:

All Tests

Applies to every test in your workspace.

When to use:

• Full platform maintenance
• Infrastructure-wide upgrades
• All services depend on a common resource

Specific Tests

Choose individual tests by name.

When to use:

• Service-specific maintenance
• Single API endpoint changes
• Targeted deployments

Example:

Scope: Specific Tests
Selected Tests:
  - Payment API Health
  - Checkout Service
  - Billing API

Tagged Tests

Apply to all tests with specific tags.

When to use:

• Environment-based maintenance (all "production" tests)
• Team-based organization (all "payments-team" tests)
• Service groupings (all "authentication" tests)

Example:

Scope: Tagged Tests
Tags: production, payments

Affects any test with either the "production" OR "payments" tag.

Creating a Maintenance Window

Step 1: Navigate to Maintenance Windows

1. Go to Maintenance from the main navigation
2. Click + New Maintenance Window

Step 2: Basic Information

Title: Q1 Database Migration
Description: Upgrading PostgreSQL from v14 to v15

Title: Short, descriptive name (appears in UI and logs) Description: Optional details about the maintenance

Step 3: Schedule

Start Time: 2024-01-20 02:00 AM UTC
End Time: 2024-01-20 06:00 AM UTC
Recurrence: One-Time

Important timezone notes:

• All times are in UTC
• Convert from your local time to UTC before scheduling
• Maintenance windows activate at the exact start time

Step 4: Choose Behavior

○ Suppress Issues
   Tests continue running, but no issues are created or alerted

● Pause Execution
   Tests are completely paused during this window

See Behaviors above to choose the right option.

Step 5: Set Scope

○ All Tests in Workspace
● Specific Tests
   [Select tests from dropdown]
○ Tests with Tags

Step 6: Create

Click Create Maintenance Window to save.

Managing Maintenance Windows

Active Maintenance Indicator

When a maintenance window is active, you'll see a banner on the dashboard:

⚠️ Active Maintenance Window
"Database Migration" is in progress
Behavior: Pause Execution | Ends: Jan 20, 2024 6:00 AM UTC
Affected: 12 tests

Maintenance Window States

State	Description
Scheduled	Future maintenance, not yet active
Active	Currently in progress
Completed	Past maintenance (historical record)

Editing a Scheduled Window

Before a maintenance window starts, you can:

1. Go to Maintenance → click the window
2. Click Edit
3. Modify any settings
4. Save changes

Note: You cannot edit an active or completed window.

Canceling a Scheduled Window

If maintenance is no longer needed:

1. Go to Maintenance → find the window
2. Click Delete
3. Confirm deletion

This removes the window entirely - affected tests return to normal operation.

Ending an Active Window Early

If maintenance completes ahead of schedule:

1. Go to Maintenance → find the active window
2. Click End Early
3. Confirm

Tests immediately resume normal behavior.

Recurring Windows

How Recurring Windows Work

When a recurring window completes, Pingward automatically:

1. Marks the current occurrence as Completed
2. Creates a new Scheduled window for the next occurrence
3. Uses the same configuration (behavior, scope, duration)

Example:

Daily Backup Window: 3:00-3:30 AM UTC
- Jan 15 occurrence: Completed
- Jan 16 occurrence: Active (right now)
- Jan 17 occurrence: Scheduled
- (future occurrences created automatically)

Stopping Recurring Windows

To stop a recurring maintenance:

1. Find the next Scheduled occurrence
2. Click Delete
3. Choose:
   • Delete this occurrence only
   • Delete all future occurrences (stops recurrence)

Maintenance Windows and Status Pages

Component Status During Maintenance

Status page components linked to tests in maintenance windows:

Suppress Issues behavior:

• Component status updates based on test results
• "Is In Maintenance" flag is set
• Optional maintenance message is displayed

Pause Execution behavior:

• Component status shows last known state
• "Is In Maintenance" flag is set
• No new status updates until maintenance ends

Setting Maintenance Messages

When creating a maintenance window, optionally set a public message:

Public Message (optional):
"We're performing scheduled maintenance to improve performance.
All services will return to normal operation by 6:00 AM UTC."

This message appears on your status page during the window.

Subscriber Notifications

If configured, status page subscribers receive:

• Maintenance start: Email/webhook notification when window begins
• Maintenance end: Notification when window completes

Use Cases and Examples

Example 1: Rolling Deployment

Scenario: Deploying a new API version across 10 servers. Each server takes 30 seconds to restart. Expect intermittent 503 errors during rollout.

Solution:

Title: API v2.3 Deployment
Behavior: Suppress Issues
Duration: 10 minutes
Scope: Specific Tests (API Health Check, User Login)
Recurrence: One-Time

Result: Tests keep running to verify deployment success, but temporary 503s don't create issues.

Example 2: Database Maintenance

Scenario: Weekly database optimization runs every Sunday at 3 AM, takes ~30 minutes. All queries are slower during this time.

Solution:

Title: Weekly DB Optimization
Behavior: Suppress Issues
Start: Sunday 3:00 AM UTC
End: Sunday 3:30 AM UTC
Scope: All Tests
Recurrence: Weekly

Result: Tests continue monitoring, but slow response times don't trigger alerts.

Example 3: Extended Downtime

Scenario: Major infrastructure upgrade requiring 4-hour service outage. All APIs will be completely offline.

Solution:

Title: Infrastructure Upgrade
Behavior: Pause Execution
Duration: 4 hours (2 AM - 6 AM UTC)
Scope: All Tests
Recurrence: One-Time
Public Message: "Scheduled maintenance in progress..."

Result: No tests run, no quota consumed, status page shows maintenance message.

Example 4: Third-Party Maintenance

Scenario: Payment processor (Stripe) has scheduled maintenance on Saturday, 1-2 PM UTC. Your checkout tests will fail during this time.

Solution:

Title: Stripe Scheduled Maintenance
Behavior: Suppress Issues
Start: Saturday 1:00 PM UTC
End: Saturday 2:00 PM UTC
Scope: Tagged Tests (tag: "payments")
Recurrence: One-Time

Result: Payment-related tests keep running but don't alert. Other tests unaffected.

Example 5: Cost Optimization

Scenario: Development environment tests don't need to run overnight (6 PM - 6 AM) when no one is working.

Solution:

Title: Dev Environment Off-Hours
Behavior: Pause Execution
Start: 6:00 PM UTC
End: 6:00 AM UTC (next day)
Scope: Tagged Tests (tag: "dev-environment")
Recurrence: Daily

Result: Save on test execution quota for non-critical dev tests.

Best Practices

Plan Ahead

• Schedule maintenance windows in advance
• Add buffer time (start 5 minutes early, end 10 minutes late)
• Coordinate with team using calendar invites

Choose the Right Behavior

Situation	Recommended Behavior
Brief, expected instability	Suppress Issues
Complete service shutdown	Pause Execution
Database migration (queries slow)	Suppress Issues
Server offline for hours	Pause Execution
Third-party service maintenance	Suppress Issues

Use Descriptive Titles

Good:

• ✅ "Q1 2024 Database Migration"
• ✅ "Weekly Backup Window"
• ✅ "Stripe Payment Processor Maintenance"

Bad:

• ❌ "Maintenance"
• ❌ "Temp Fix"
• ❌ "Test"

Set Public Messages

For status pages, always set a public message explaining:

• What's being maintained
• Expected duration
• When normal service resumes

Review Historical Windows

Periodically review completed windows:

• Did maintenance take longer than expected?
• Were scopes too broad or too narrow?
• Adjust future windows based on learnings

Coordinate with Status Page Updates

If you have a status page:

1. Schedule the maintenance window
2. Verify public message is set
3. Optionally post a manual incident for advance notice (48 hours before)
4. Let maintenance window handle during-maintenance status

Troubleshooting

Tests Still Creating Issues During Maintenance

Check:

1. Is the maintenance window Active? (Check dashboard banner)
2. Is the test included in the scope? (View window details)
3. Was the issue created just before the window started? (Check timestamps)

Maintenance Window Didn't Activate

Check:

1. Start time in UTC - did you convert from your timezone correctly?
2. Maintenance window state is Scheduled (not deleted)
3. System time is synchronized (unlikely but possible)

Tests Didn't Resume After Maintenance

Check:

1. Is the end time correct? (Maintenance may still be active)
2. Were tests paused manually? (Separate from maintenance windows)
3. View test details to see status

Recurring Window Not Creating Next Occurrence

Check:

1. Did you delete "all future occurrences"?
2. Check completed window details to verify recurrence type
3. Next occurrence should appear when current one completes

API Access

Maintenance windows can be managed programmatically:

GET /api/maintenance-windows
POST /api/maintenance-windows
PUT /api/maintenance-windows/{id}
DELETE /api/maintenance-windows/{id}

See API Reference for details.

Related Topics

• Scheduling Tests
• Pausing Tests
• Status Pages
• Issue Management