Watchdog allows you to monitor URLs with customizable HTTP methods, monitoring frequencies, and contact emails for notifications. This guide covers everything you need to know about managing your monitored URLs.
Adding a monitored URL
Use the add command to register a new URL for monitoring. The command accepts four positional arguments:
Prepare your URL details
Gather the following information:
- The URL to monitor (required)
- HTTP method to use (optional, defaults to
get)
- Monitoring frequency (optional, defaults to
five_minutes)
- Contact email for notifications (required)
Run the add command
go run ./cmd/... add <url> <http_method> <frequency> <contact_email>
Verify the URL was added
After successful addition, you’ll see:URL successfully added, ID: 42
HTTP methods
Watchdog supports the following HTTP methods for monitoring your URLs:
get - HTTP GET requests (default)post - HTTP POST requestsput - HTTP PUT requestspatch - HTTP PATCH requestsdelete - HTTP DELETE requests
Examples with different methods
# Monitor an API endpoint with POST
go run ./cmd/... add https://api.example.com/health post five_minutes [email protected]
# Monitor with PUT method
go run ./cmd/... add https://api.example.com/status put one_minute [email protected]
# Monitor with PATCH
go run ./cmd/... add https://api.example.com/check patch thirty_seconds [email protected]
The HTTP method parameter is case-insensitive. Both GET and get are accepted.
Monitoring frequencies
Choose from eight different monitoring intervals based on your needs:
| Frequency | Value | Interval |
|---|
| Ten seconds | ten_seconds | 10 seconds |
| Thirty seconds | thirty_seconds | 30 seconds |
| One minute | one_minute | 60 seconds |
| Five minutes | five_minutes | 5 minutes (default) |
| Thirty minutes | thirty_minutes | 30 minutes |
| One hour | one_hour | 1 hour |
| Twelve hours | twelve_hours | 12 hours |
| Twenty-four hours | twenty_four_hours | 24 hours |
Choosing the right frequency
Best practices for frequency selection:
- Use
ten_seconds or thirty_seconds for critical production APIs
- Use
five_minutes for standard website monitoring (default)
- Use
thirty_minutes or one_hour for non-critical services
- Use
twelve_hours or twenty_four_hours for batch job endpoints
Examples with different frequencies
# Critical API - check every 10 seconds
go run ./cmd/... add https://critical-api.example.com get ten_seconds [email protected]
# Standard monitoring - every 5 minutes
go run ./cmd/... add https://example.com get five_minutes [email protected]
# Daily batch job check - every 24 hours
go run ./cmd/... add https://batch.example.com/status get twenty_four_hours [email protected]
Email notification triggers
Watchdog sends email notifications when:
- A URL becomes unreachable (healthy → unhealthy)
- A URL recovers (unhealthy → healthy)
- State transitions occur based on the supervisor’s evaluation logic
Ensure the contact email is valid and monitored. Invalid emails will cause notification failures without affecting the monitoring itself.
Multiple URLs with the same email
# Monitor multiple URLs with the same contact
go run ./cmd/... add https://app.example.com get five_minutes [email protected]
go run ./cmd/... add https://api.example.com get five_minutes [email protected]
go run ./cmd/... add https://admin.example.com get five_minutes [email protected]
# Frontend team
go run ./cmd/... add https://www.example.com get five_minutes [email protected]
# Backend team
go run ./cmd/... add https://api.example.com get thirty_seconds [email protected]
# DevOps team
go run ./cmd/... add https://monitoring.example.com get one_minute [email protected]
Listing monitored URLs
View all monitored URLs with the list command:
# View first page (default: 20 results per page)
go run ./cmd/... list --page=1 --per_page=20
# View second page
go run ./cmd/... list --page=2 --per_page=20
# Show 50 results per page
go run ./cmd/... list --page=1 --per_page=50
Filtering results
Filter by frequency:
go run ./cmd/... list --frequency=five_minutes
go run ./cmd/... list --http_method=get
# Show only healthy URLs
go run ./cmd/... list --status=healthy
# Show only unhealthy URLs
go run ./cmd/... list --status=unhealthy
# Show pending URLs (newly added)
go run ./cmd/... list --status=pending
go run ./cmd/... list --frequency=five_minutes --http_method=get --status=healthy
Example output
Page 1 (showing 3 results)
→ Next: --page=2
------------------------------------------------------------
1. https://example.com
ID: 42 | Method: get | Status: healthy | Frequency: five_minutes
Contact: [email protected]
2. https://api.example.com
ID: 43 | Method: post | Status: healthy | Frequency: thirty_seconds
Contact: [email protected]
3. https://batch.example.com
ID: 44 | Method: get | Status: pending | Frequency: twenty_four_hours
Contact: [email protected]
------------------------------------------------------------
More results available. Use --page=2 to continue.
Removing monitored URLs
Remove a URL from monitoring using its ID:
go run ./cmd/... remove <id>
# Remove URL with ID 42
go run ./cmd/... remove 42
Find the URL ID
Use the list command to find the ID of the URL you want to remove: Remove the URL
go run ./cmd/... remove 42
Verify removal
After successful removal, you’ll see:URL successfully removing, ID: 42
Removing a URL is permanent and will delete all associated monitoring data. There is no confirmation prompt, so ensure you have the correct ID.
Using command aliases
Watchdog provides short aliases for common commands:
# Add command - use 'a' alias
go run ./cmd/... a https://example.com get five_minutes [email protected]
# List command - use 'ls' alias
go run ./cmd/... ls --status=healthy
# Remove command - use 'rm' alias
go run ./cmd/... rm 42
The add and analysis commands both use the a alias, which may cause ambiguity. It’s recommended to use the full command name add to avoid conflicts.
URL status lifecycle
Every monitored URL goes through the following status states:
- Pending - URL is newly added and awaiting first check
- Healthy - URL is responding successfully
- Unhealthy - URL is not responding or returning errors
Status transitions
The Supervisor component evaluates each check result and determines status transitions. Email notifications are sent to the contact email when transitions occur between healthy and unhealthy states.
Common patterns
Monitor all services in a microservices architecture
# API Gateway
go run ./cmd/... add https://gateway.example.com/health get thirty_seconds [email protected]
# User Service
go run ./cmd/... add https://users.example.com/health get one_minute [email protected]
# Order Service
go run ./cmd/... add https://orders.example.com/health get one_minute [email protected]
# Payment Service (critical)
go run ./cmd/... add https://payments.example.com/health get ten_seconds [email protected]
Monitor different environments
# Production
go run ./cmd/... add https://prod.example.com get one_minute [email protected]
# Staging
go run ./cmd/... add https://staging.example.com get five_minutes [email protected]
# Development
go run ./cmd/... add https://dev.example.com get thirty_minutes [email protected]
Monitor scheduled tasks
# Daily backup job (runs at midnight)
go run ./cmd/... add https://backup.example.com/status get one_hour [email protected]
# Weekly report generation
go run ./cmd/... add https://reports.example.com/status get twelve_hours [email protected]