> ## Documentation Index
> Fetch the complete documentation index at: https://docs.statusstack.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Monitors

> Custom website and API monitoring with StatusStack

## What are Monitors?

**Monitors** in StatusStack allow you to track the health and performance of your own websites, APIs, and custom endpoints. Unlike Sources (which monitor third-party services), Monitors check endpoints that you own and control.

***

## Key Features

<CardGroup cols={2}>
  <Card title="HTTP/HTTPS Health Checks" icon="heart-pulse">
    Ping your endpoints at regular intervals to verify availability
  </Card>

  <Card title="SSL Certificate Monitoring" icon="shield-check">
    Track certificate expiry dates and get alerted before they expire
  </Card>

  <Card title="Response Time Tracking" icon="gauge-high">
    Monitor performance trends and detect slowdowns
  </Card>

  <Card title="Uptime Percentage" icon="chart-line">
    Calculate and display historical uptime statistics
  </Card>
</CardGroup>

***

## Monitor Types

### Website Monitors

Monitor public or private websites:

```http theme={null}
GET https://www.yoursite.com/
Expected Status: 200 OK
Check Interval: 60 seconds
```

**Use Cases:**

* Monitor your company website
* Track landing page availability
* Check documentation sites
* Verify blog accessibility

### API Health Checks

Monitor API endpoints with custom validation:

```http theme={null}
GET https://api.yourservice.com/health
Headers:
  Authorization: Bearer your-token-here
Expected Status: 200
Expected Body: {"status": "healthy"}
Check Interval: 30 seconds
```

**Use Cases:**

* Monitor production APIs
* Track microservice health
* Verify webhook endpoints
* Check database connectivity

### Custom Endpoints

Monitor any HTTP/HTTPS endpoint:

* **Admin Panels** - Verify dashboard accessibility
* **CDN Endpoints** - Check asset delivery
* **Load Balancers** - Monitor routing health
* **Internal Services** - Track private network endpoints

***

## Creating a Monitor

<Steps>
  <Step title="Navigate to Monitors">
    In your dashboard, go to **Monitoring** → **Website Monitors**
  </Step>

  <Step title="Click Create Monitor">
    Click the **"Create Monitor"** button in the top-right
  </Step>

  <Step title="Configure Basic Settings">
    Fill in the monitor details:

    ```yaml theme={null}
    Name: Production API Health
    URL: https://api.yoursite.com/health
    Description: Monitors production API availability (optional)
    Team: Select your team
    ```
  </Step>

  <Step title="Set Check Interval">
    Choose how often to check the endpoint:

    * **30 seconds** - Critical endpoints
    * **60 seconds** - Production services
    * **5 minutes** - Standard monitoring
    * **15 minutes** - Less critical endpoints
  </Step>

  <Step title="Configure Validation">
    Define what "healthy" means:

    * **Expected Status Code** - 200, 201, 204, etc.
    * **Response Timeout** - Maximum wait time (default: 10s)
    * **Follow Redirects** - Enable/disable redirect following
    * **Verify SSL** - Check SSL certificate validity
  </Step>

  <Step title="Add to Stack">
    Select which Stack(s) to add this monitor to
  </Step>

  <Step title="Save Monitor">
    Click **Create** to start monitoring
  </Step>
</Steps>

***

## Monitor Configuration Options

### Basic Settings

| Field           | Description                  | Example                          |
| --------------- | ---------------------------- | -------------------------------- |
| **Name**        | Display name for the monitor | "Production API"                 |
| **URL**         | Endpoint to monitor          | `https://api.example.com/health` |
| **Description** | Optional notes               | "Main API health endpoint"       |
| **Team**        | Which team owns this monitor | "Engineering Team"               |

### Check Configuration

| Setting               | Options                    | Recommended        |
| --------------------- | -------------------------- | ------------------ |
| **Check Interval**    | 30s, 1m, 5m, 15m, 30m, 60m | 60s for production |
| **Timeout**           | 5s, 10s, 15s, 30s          | 10s                |
| **Retry Count**       | 1-5 retries                | 3 retries          |
| **Failure Threshold** | 1-10 failures              | 3 failures         |

### Advanced Options

<AccordionGroup>
  <Accordion title="Custom Headers">
    Add authentication or custom headers:

    ```yaml theme={null}
    Headers:
      Authorization: Bearer sk_live_abc123...
      X-API-Key: your-api-key-here
      User-Agent: StatusStack Monitor
    ```
  </Accordion>

  <Accordion title="SSL Certificate Monitoring">
    Track certificate expiry:

    * **Monitor Expiry** - Get alerted before certificates expire
    * **Warning Threshold** - Alert 30 days before expiry
    * **Critical Threshold** - Alert 7 days before expiry
  </Accordion>

  <Accordion title="Response Validation">
    Validate response content:

    * **Status Code** - Expected HTTP status (200, 201, etc.)
    * **Response Body** - Check for specific text or JSON
    * **Response Time** - Alert if slower than threshold
  </Accordion>

  <Accordion title="Maintenance Windows">
    Schedule maintenance to pause monitoring:

    * **One-Time** - Specific date/time range
    * **Recurring** - Weekly maintenance windows
    * **Manual** - Pause/resume manually
  </Accordion>
</AccordionGroup>

***

## Monitor Status Levels

Monitors report one of four status levels:

<CardGroup cols={2}>
  <Card title="Operational" icon="circle-check" color="#10b981">
    All checks passing, endpoint is healthy
  </Card>

  <Card title="Degraded" icon="triangle-exclamation" color="#f59e0b">
    Some checks failing, but threshold not met
  </Card>

  <Card title="Critical" icon="circle-xmark" color="#ef4444">
    Failure threshold exceeded, endpoint is down
  </Card>

  <Card title="Maintenance" icon="wrench" color="#3b82f6">
    Scheduled maintenance, monitoring paused
  </Card>
</CardGroup>

### Status Calculation

```javascript theme={null}
// Monitor status logic
if (consecutiveFailures >= failureThreshold) {
  status = 'CRITICAL'
} else if (consecutiveFailures > 0) {
  status = 'DEGRADED'
} else if (maintenanceMode) {
  status = 'MAINTENANCE'
} else {
  status = 'OPERATIONAL'
}
```

***

## Monitor Analytics

Each monitor provides detailed analytics:

### Uptime Metrics

* **Current Uptime** - Last 24 hours, 7 days, 30 days, 90 days
* **Uptime Percentage** - Historical uptime calculation
* **Incident Count** - Number of outages in period
* **MTTR** - Mean time to recovery

### Performance Metrics

* **Response Time** - Average, min, max response times
* **Performance Trends** - Response time over time
* **Slowest Checks** - Identify performance issues
* **Geographic Performance** - If checking from multiple regions

### Check History

* **Recent Checks** - Last 100 checks with timestamps
* **Failure Details** - Why checks failed (timeout, status code, etc.)
* **Recovery Timeline** - When services came back online
* **Status Change Log** - All status transitions

***

## Integration with Stacks

Monitors seamlessly integrate with Stacks:

### Adding Monitors to Stacks

<Tabs>
  <Tab title="During Creation">
    Select Stack(s) when creating the monitor:

    ```yaml theme={null}
    Monitor: Production API
    Stacks:
      - Production Infrastructure
      - Public Status Dashboard
    ```
  </Tab>

  <Tab title="After Creation">
    Edit the monitor and add/remove Stacks:

    1. Open monitor settings
    2. Go to "Stacks" section
    3. Select/deselect Stacks
    4. Save changes
  </Tab>
</Tabs>

### Stack Status Impact

Monitors contribute to Stack overall status:

* **Operational Monitor** → Stack can remain operational
* **Degraded Monitor** → Stack becomes degraded
* **Critical Monitor** → Stack becomes critical

***

## Notifications

Monitors trigger notifications when status changes:

### Notification Events

| Event                 | Description                      | Recommended Action      |
| --------------------- | -------------------------------- | ----------------------- |
| **Monitor Down**      | Failure threshold exceeded       | Immediate investigation |
| **Monitor Degraded**  | Some failures, not critical yet  | Monitor closely         |
| **Monitor Recovered** | Back to operational              | No action needed        |
| **SSL Expiring**      | Certificate expiring soon        | Renew certificate       |
| **Slow Response**     | Response time threshold exceeded | Investigate performance |

### Configuring Alerts

Create notification rules for monitors:

```yaml theme={null}
Notification Rule:
  Name: "Critical Monitor Alerts"
  Triggers:
    - Monitor becomes Critical
    - Monitor becomes Degraded
  Monitors:
    - Production API
    - Production Website
  Channels:
    - Slack: #alerts
    - PagerDuty: On-Call Team
    - Email: ops@company.com
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Check Interval Selection">
    **Critical Services** - 30-60 seconds

    * Production APIs
    * Payment processing endpoints
    * User-facing websites

    **Standard Services** - 5 minutes

    * Internal dashboards
    * Admin panels
    * Documentation sites

    **Less Critical** - 15-30 minutes

    * Development environments
    * Staging sites
    * Internal tools
  </Accordion>

  <Accordion title="Failure Threshold Configuration">
    **Recommended**: 3 consecutive failures

    * Prevents false positives from network blips
    * Balances detection speed with accuracy
    * Typically detects real outages within 2-3 minutes

    **Adjust based on criticality**:

    * Ultra-critical: 2 failures
    * Standard: 3 failures
    * Low priority: 5 failures
  </Accordion>

  <Accordion title="Timeout Settings">
    **API Endpoints**: 10 seconds

    * Most APIs respond in \< 1 second
    * 10 seconds catches legitimate slowdowns

    **Websites**: 15-30 seconds

    * Page load can be slower
    * Includes rendering time

    **Microservices**: 5 seconds

    * Should be fast
    * Detect performance issues quickly
  </Accordion>

  <Accordion title="Organizing Monitors">
    **Group by environment**:

    ```
    Production Stack
      ├─ Production API Monitor
      ├─ Production Website Monitor
      └─ Production Database Monitor

    Staging Stack
      ├─ Staging API Monitor
      └─ Staging Website Monitor
    ```

    **Group by service**:

    ```
    API Services Stack
      ├─ Auth API Monitor
      ├─ User API Monitor
      └─ Payment API Monitor
    ```
  </Accordion>
</AccordionGroup>

***

## Common Use Cases

### Scenario 1: Production API Monitoring

Monitor a production API with authentication:

```yaml theme={null}
Monitor Configuration:
  Name: Production API Health
  URL: https://api.yourservice.com/health
  Method: GET
  Headers:
    Authorization: Bearer your-api-key
  Expected Status: 200
  Expected Body Contains: "healthy"
  Check Interval: 60 seconds
  Failure Threshold: 3
  Timeout: 10 seconds
  Stacks:
    - Production Infrastructure
  Notifications:
    - Slack: #production-alerts
    - PagerDuty: On-Call
```

### Scenario 2: Website Uptime Monitoring

Monitor a public website:

```yaml theme={null}
Monitor Configuration:
  Name: Company Website
  URL: https://www.yourcompany.com
  Method: GET
  Expected Status: 200
  Check Interval: 5 minutes
  Failure Threshold: 3
  Verify SSL: Yes
  SSL Alert Threshold: 30 days
  Stacks:
    - Public Services
  Notifications:
    - Email: ops@company.com
```

### Scenario 3: Multi-Region Monitoring

Monitor from multiple regions (Enterprise feature):

```yaml theme={null}
Monitor Configuration:
  Name: Global API Endpoint
  URL: https://api.global-service.com/ping
  Regions:
    - US East
    - EU West
    - Asia Pacific
  Check Interval: 60 seconds
  Aggregate Results: Any region passing = Operational
```

***

## Troubleshooting

### Monitor Shows as Down but Site is Up

**Possible Causes:**

1. **Firewall blocking StatusStack IPs** - Whitelist our monitoring IPs
2. **Rate limiting** - Exclude monitoring user-agent from rate limits
3. **Authentication required** - Add proper headers/credentials
4. **Redirects** - Enable "Follow Redirects" option
5. **SSL certificate issues** - Check SSL validity

### False Positive Alerts

**Solutions:**

1. **Increase failure threshold** - From 3 to 5 consecutive failures
2. **Increase timeout** - From 10s to 15s or 30s
3. **Check network connectivity** - Verify endpoint is publicly accessible
4. **Review expected status codes** - May need to accept 201, 204, etc.

### Monitors Not Alerting

**Check:**

1. **Notification rules configured** - Ensure rules exist for monitors
2. **Notification channels working** - Test webhook/Slack/Discord integration
3. **Alert level thresholds** - Verify degraded vs critical thresholds
4. **Maintenance mode** - Ensure monitor isn't in maintenance window

***

## Monitor Limits by Plan

| Plan           | Max Monitors | Check Interval | Regions      |
| -------------- | ------------ | -------------- | ------------ |
| **Free**       | 1            | 5 minutes      | 1 region     |
| **Pro**        | 25           | 30 seconds     | 1 region     |
| **Enterprise** | Unlimited    | 30 seconds     | Multi-region |

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Your First Monitor" icon="rocket" href="/guides/custom-monitoring">
    Step-by-step guide to creating monitors
  </Card>

  <Card title="Notification Setup" icon="bell" href="/guides/notification-setup">
    Configure alerts for monitor changes
  </Card>

  <Card title="Stacks" icon="layer-group" href="/concepts/stacks">
    Learn how to organize monitors into Stacks
  </Card>

  <Card title="Dashboard Guide" icon="gauge" href="/guides/customer-dashboard">
    Master the monitoring dashboard
  </Card>
</CardGroup>