Monitors

Automated HTTP health checks to detect issues before your users do.

Overview

Monitors are built into ENDPOINT type components. They:

• Run HTTP health checks at configured intervals
• Evaluate response conditions (status code, response time, JSON path)
• Update component status automatically
• Create incidents when checks fail
• Send alerts to on-call teams

Creating a Monitor

Monitors are part of ENDPOINT components:

1. Navigate to Dashboard > Components
2. Click "Add Component"
3. Select Type: ENDPOINT
4. Configure monitoring settings:

Basic Settings

Request Configuration

Headers:

{
  "Authorization": "Bearer token123",
  "X-Custom-Header": "value"
}

Body (for POST/PUT):

{
  "test": true
}

Authentication:

• Basic Auth (username/password)
• Bearer Token
• API Key (header or query param)

Check Conditions

Define what constitutes a successful check:

Status Code

Check HTTP response status:

Response Time

Check response latency:

JSON Path

Assert values in JSON responses:

Example JSON Path expressions:

$.status              → Root field "status"
$.data.items[0].id    → First item's ID
$.users[*].email      → All user emails
$.config.enabled      → Nested field

Headers

Check response headers:

Body Contains

Check if response body contains text:

Response body contains "healthy"
Response body contains "version"

Condition Logic

Multiple conditions are combined with AND logic:

✓ Status code = 200
AND
✓ Response time < 1000ms
AND
✓ JSON $.status = "ok"

All conditions must pass for the check to succeed.

Check Intervals

Failure Handling

Failure Threshold

Set how many consecutive failures before taking action:

• 1 failure: Immediate action (may cause false positives)
• 2-3 failures: Recommended (filters transient issues)
• 5+ failures: Conservative (delays detection)

On Failure

When threshold is reached:

1. Component status changes (e.g., to Major Outage)
2. If auto-incident enabled, incident is created
3. Notifications sent to configured channels
4. On-call alerts triggered (if configured)

Auto-Incidents

Enable automatic incident creation:

1. Edit the ENDPOINT component
2. Enable "Auto Create Incident"
3. Configure:
   • Title template: e.g., "{{component}} is down"
   • Impact level: Minor, Major, Critical
   • Initial status: Usually "Investigating"

Auto-Resolution

When checks recover:

1. Enable "Auto Resolve"
2. Set "Recovery Threshold": consecutive successes needed
3. When recovered:
   • Incident is resolved automatically
   • Component returns to Operational
   • Recovery notification sent

Muting Monitors

Temporarily suppress alerts:

1. Edit the component
2. Enable "Muted"
3. Save

When muted:

• Checks continue running ✓
• Status updates ✓
• Incidents still created (if enabled) ✓
• No notifications sent ✗
• No on-call alerts ✗

Request Preview

Test your monitor configuration:

1. In the component editor, click "Test Request"
2. View the response:
   • Status code
   • Response time
   • Headers
   • Body
3. Check condition results
4. Copy cURL command for debugging

Monitor Dashboard

View all monitors in one place:

• Dashboard > Monitors shows all ENDPOINT components
• Quick filters by status, type
• Bulk actions (enable, disable, mute)

Monitor Cards

Each card shows:

• Current status
• Uptime percentage
• Last check result
• Response time trend

Actions

• Edit: Modify configuration
• Clone: Create a copy
• Mute/Unmute: Toggle alerts
• Delete: Remove the monitor

Response Time Metrics

Monitors track response times:

View on the component detail page or status page widgets.

API Access

List Monitors

curl http://localhost:3000/api/v1/components?type=ENDPOINT \
  -H "Authorization: Bearer sk_live_xxx"

Create Monitor

curl -X POST http://localhost:3000/api/v1/components \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Health",
    "type": "ENDPOINT",
    "url": "https://api.example.com/health",
    "method": "GET",
    "checkInterval": 60,
    "conditions": [
      {
        "type": "STATUS_CODE",
        "comparator": "EQUALS",
        "target": "200"
      },
      {
        "type": "RESPONSE_TIME",
        "comparator": "LESS_THAN",
        "target": "1000"
      }
    ],
    "autoCreateIncident": true,
    "failureThreshold": 3
  }'

Manual Check

curl -X POST http://localhost:3000/api/v1/components/{id}/check \
  -H "Authorization: Bearer sk_live_xxx"

Best Practices

Endpoint Selection

• Use dedicated health endpoints
• Include dependency checks in health response
• Avoid load balancer health checks (may not reflect actual status)

Condition Design

• Start with basic checks (status code)
• Add response time as secondary check
• Use JSON path for deep health validation

Thresholds

• Use 2-3 failure threshold for most cases
• Lower for critical services
• Higher for flaky endpoints

Intervals

• 1 minute is a good default
• Shorter for user-facing critical services
• Longer for background services

Troubleshooting

False Positives

If monitors trigger incorrectly:

1. Increase failure threshold
2. Increase check interval
3. Add timeout buffer
4. Check network connectivity

Missed Outages

If monitors don't detect issues:

1. Decrease failure threshold
2. Add more specific conditions
3. Check that endpoint reflects actual service health

Slow Checks

If checks take too long:

1. Reduce timeout
2. Check monitored endpoint performance
3. Ensure network path is optimal

Related Documentation

• Components - Configure ENDPOINT type
• Incidents - Auto-incident behavior
• On-Call - Alert escalation