Skip to content

Latest commit

 

History

History
461 lines (409 loc) · 10.7 KB

configuration.md

File metadata and controls

461 lines (409 loc) · 10.7 KB

Configuration Guide

Sky Puppy uses a JSON configuration file to define all aspects of your monitoring setup. This guide covers all configuration options and provides practical examples.

Configuration File Location

By default, Sky Puppy looks for sky-puppy-config.json in the current working directory. You can specify a custom path using the SKY_PUPPY_CONFIG_PATH environment variable.

Configuration Structure

{
  "skypuppy": {
    // Sky Puppy application settings
  },
  "checkers": {
    // Global checker configurations
  },
  "alerters": {
    // Alert configurations
  },
  "services": {
    // Service monitoring configurations
  }
}

Complete Configuration Example

{
  "skypuppy": {
    "version": "1.3.8",
    "log": {
      "enable": true,
      "colors": true,
      "level": "info"
    }
  },
  "checkers": {
    "request": {},
    "sky-puppy-checker-template": {
      "foo": "bar",
      "code_messages": {
        "200": "Override me plz",
        "500": "Yikes its down"
      }
    }
  },
  "alerters": {
    "discord_down": {
      "uri": "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL",
      "json": true,
      "method": "POST",
      "body": {
        "embeds": [
          {
            "title": "{{service_name}} is {{alert_type}}!",
            "description": "This service was healthy for {{last_healthy_total_duration}} seconds! {{message}}",
            "color": 14828098,
            "footer": {
              "text": ""
            },
            "timestamp": "{{timestamp}}"
          }
        ],
        "username": "Sky Puppy",
        "avatar_url": "https://i.imgur.com/J5vIVSt.png"
      }
    }
  },
  "services": {
    "my-website": {
      "interval": 30,
      "start_delay": 0,
      "expected_response_time": 1000,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://httpbin.org/status/200",
          "timeout": 10
        },
        "code_messages": {
          "200": "Service is healthy",
          "500": "Service is down"
        }
      },
      "alerts": [
        {
          "type": "down",
          "alerter": "discord_down",
          "for": 2
        },
        {
          "type": "unhealthy_response_time",
          "for": 1,
          "alerter": "discord_down"
        },
        {
          "type": "unhealthy_status",
          "for": 4,
          "alerter": "discord_down"
        },
        {
          "type": "healthy",
          "alerter": "discord_down"
        }
      ]
    }
  }
}

Checkers Configuration

The checkers section defines global settings for health checkers that can be used across multiple services.

Global Checker Configuration

{
  "checkers": {
    "request": {
      "timeout": 60,
      "method": "GET"
    },
    "sky-puppy-checker-template": {
      "foo": "bar",
      "code_messages": {
        "200": "Override me plz",
        "500": "Yikes its down"
      }
    }
  }
}

Checker Configuration Options

Option Type Default Description
name string required Name of the checker to use
settings object {} Checker-specific settings
code_messages object {} Custom messages for different status codes

Services Configuration

The services section defines what you want to monitor. Each service has a unique name and configuration.

Basic Service Configuration

{
  "services": {
    "my-website": {
      "interval": 30,
      "start_delay": 5,
      "expected_status": 200,
      "expected_response_time": 1000,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://mywebsite.com/health",
          "timeout": 5,
          "method": "GET"
        },
        "code_messages": {
          "200": "Service is healthy",
          "500": "Service is down"
        }
      }
    }
  }
}

Service Configuration Options

Option Type Default Description
interval number 5 Check interval in seconds
start_delay number 0 Initial delay before first check (seconds)
expected_status number 200 Expected HTTP status code for success
expected_response_time number timeout Expected response time in milliseconds
checker object required Checker configuration
alerts array [] Alert configurations for this service

Advanced Service Configuration

{
  "services": {
    "api-service": {
      "interval": 15,
      "start_delay": 10,
      "expected_status": 200,
      "expected_response_time": 500,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://api.example.com/health",
          "timeout": 10,
          "method": "POST",
          "headers": {
            "Authorization": "Bearer your-token",
            "Content-Type": "application/json"
          },
          "body": {
            "check": "health",
            "timestamp": "{{timestamp}}"
          },
          "json": true
        },
        "code_messages": {
          "200": "API is healthy",
          "500": "API is experiencing errors",
          "503": "API is temporarily unavailable"
        }
      },
      "alerts": [
        {
          "type": "down",
          "alerter": "discord_critical",
          "for": 2
        },
        {
          "type": "unhealthy_response_time",
          "alerter": "slack_warning",
          "for": 3
        },
        {
          "type": "unhealthy_status",
          "alerter": "slack_warning",
          "for": 1
        },
        {
          "type": "unhealthy",
          "alerter": "slack_warning",
          "for": 1
        },
        {
          "type": "healthy",
          "alerter": "discord_recovery"
        }
      ]
    }
  }
}

Alerters Configuration

The alerters section defines how to send notifications when services change status.

Basic Discord Alerter

{
  "alerters": {
    "discord_down": {
      "uri": "https://discord.com/api/webhooks/YOUR_WEBHOOK_URL",
      "json": true,
      "method": "POST",
      "body": {
        "embeds": [
          {
            "title": "🚨 {{service_name}} is {{alert_type}}!",
            "description": "Service was healthy for {{last_healthy_total_duration}} seconds",
            "color": 14828098,
            "timestamp": "{{timestamp}}",
            "footer": {
              "text": "Sky Puppy Monitor"
            }
          }
        ],
        "username": "Sky Puppy",
        "avatar_url": "https://i.imgur.com/J5vIVSt.png"
      }
    }
  }
}

Slack Alerter

{
  "alerters": {
    "slack_alert": {
      "uri": "https://hooks.slack.com/services/YOUR/SLACK/WEBHOOK",
      "json": true,
      "method": "POST",
      "body": {
        "text": "🚨 {{service_name}} is {{alert_type}}!",
        "attachments": [
          {
            "color": "#ff0000",
            "fields": [
              {
                "title": "Service",
                "value": "{{service_name}}",
                "short": true
              },
              {
                "title": "Status",
                "value": "{{alert_type}}",
                "short": true
              },
              {
                "title": "Duration",
                "value": "{{last_healthy_total_duration}} seconds",
                "short": false
              }
            ],
            "timestamp": "{{timestamp}}"
          }
        ]
      }
    }
  }
}

Email Alerter (via SMTP)

{
  "alerters": {
    "email_alert": {
      "uri": "smtp://user:pass@smtp.gmail.com:587",
      "json": false,
      "method": "POST",
      "headers": {
        "From": "sky-puppy@yourdomain.com",
        "To": "admin@yourdomain.com",
        "Subject": "Alert: {{service_name}} is {{alert_type}}"
      },
      "body": "Service {{service_name}} is currently {{alert_type}}. It was healthy for {{last_healthy_total_duration}} seconds."
    }
  }
}

Alerter Template Variables

Sky Puppy provides several template variables for use in alert messages:

Variable Description
{{service_name}} Name of the service
{{alert_type}} Type of alert (down, unhealthy, healthy)
{{timestamp}} Current timestamp
{{last_healthy_total_duration}} Duration service was healthy (seconds)
{{last_unhealthy_total_duration}} Duration service was unhealthy (seconds)
{{response_time}} Last response time (milliseconds)
{{status_code}} Last HTTP status code

Checker Configuration

HTTP Request Checker

The built-in request checker monitors HTTP/HTTPS endpoints.

{
  "checker": {
    "name": "request",
    "settings": {
      "uri": "https://api.example.com/health",
      "timeout": 5,
      "method": "GET",
      "headers": {
        "User-Agent": "Sky-Puppy/1.0"
      },
      "body": {
        "test": "data"
      },
      "json": true,
      "followRedirect": true,
      "validateSSL": true
    }
  }
}

MongoDB Checker

Monitor MongoDB database connections.

{
  "checker": {
    "name": "sky-puppy-checker-mongodb",
    "settings": {
      "uri": "mongodb://localhost:27017",
      "database": "myapp",
      "timeout": 5000
    }
  }
}

Cloudflare Status Checker

Monitor Cloudflare service status.

{
  "checker": {
    "name": "sky-puppy-checker-cloudflare-status",
    "settings": {
      "services": ["cloudflare-dns", "cloudflare-cdn"]
    }
  }
}

Sky Puppy Application Configuration

The skypuppy section configures the application itself.

{
  "skypuppy": {
    "version": "1.0.0",
    "log": {
      "enable": true,
      "colors": true,
      "level": "info"
    }
  }
}

Logging Options

Option Type Default Description
enable boolean true Enable/disable logging
colors boolean true Enable colored output
level string "info" Log level (debug, info, warn, error)

Environment Variables

Sky Puppy supports several environment variables for configuration:

Variable Default Description
SKY_PUPPY_PORT 8069 Server port
SKY_PUPPY_IP 0.0.0.0 Server IP address
SKY_PUPPY_CONFIG_PATH ./sky-puppy-config.json Path to config file

Best Practices

  1. Start with simple configurations and add complexity gradually
  2. Use meaningful service names that reflect what you're monitoring
  3. Set appropriate intervals - don't check too frequently to avoid overwhelming your services
  4. Include timeouts to prevent hanging requests
  5. Test your alerters before deploying to production
  6. Use environment variables for sensitive information like webhook URLs
  7. Monitor the monitor - ensure Sky Puppy itself is running and healthy