Sky Puppy

Lightning-fast, reliable health monitoring for your services with Prometheus metrics and smart alerting

Sky Puppy is a powerful, lightweight health monitoring service that keeps your applications running smoothly. Monitor HTTP endpoints, databases, and custom services with real-time alerts and Prometheus metrics export.

✨ Features

• 🚀 Lightning Fast: Built with Fastify for exceptional performance
• 🔍 Multiple Checkers: HTTP/HTTPS, MongoDB, Cloudflare Status, and custom checkers
• 📊 Prometheus Metrics: Built-in metrics export for monitoring dashboards
• 🔔 Smart Alerting: Discord, Slack, and custom webhook integrations
• ⚡ Real-time Monitoring: Configurable check intervals down to seconds
• 🛡️ Reliable: Robust error handling and automatic recovery
• 🔧 Easy Configuration: Simple JSON configuration
• 🌐 RESTful API: Full API for dynamic service management
• 📈 Health Status Tracking: Detailed uptime and performance metrics

🚀 Quick Start

Installation

npm install -g sky-puppy

Basic Usage

1. Create a configuration file (sky-puppy-config.json):

{
  "services": {
    "my-website": {
      "interval": 30,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://mywebsite.com/health",
          "timeout": 5,
          "method": "GET"
        }
      }
    }
  }
}

2. Run Sky Puppy:

sky-puppy

3. Check your service status:

curl http://localhost:8069/skypuppy/v1/service/my-website

📋 Configuration

Sky Puppy uses a JSON configuration file to define services, checkers, and alerters.

Service Configuration

{
  "services": {
    "service-name": {
      "interval": 30,                    // Check interval in seconds
      "start_delay": 5,                  // Initial delay before first check
      "expected_status": 200,            // Expected HTTP status code
      "checker": {
        "name": "request",               // Checker type
        "settings": {
          "uri": "https://api.example.com/health",
          "timeout": 5,                  // Request timeout in seconds
          "method": "GET",               // HTTP method
          "headers": {                   // Custom headers
            "Authorization": "Bearer token"
          },
          "body": {                      // Request body (for POST/PUT)
            "test": "data"
          }
        }
      },
      "alerts": [                        // Alert configurations
        {
          "type": "down",
          "alerter": "discord_down"
        },
        {
          "type": "healthy",
          "alerter": "discord_healthy"
        }
      ]
    }
  }
}

Alert Configuration

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

🔌 Available Checkers

Built-in Checkers

• request: HTTP/HTTPS endpoint monitoring
• mongodb: MongoDB connection health checks
• cloudflare-status: Cloudflare service status monitoring

Custom Checkers

Create your own checkers using the checker template:

npm install -g sky-puppy-checker-template

📊 Monitoring & Metrics

Health Endpoints

• GET /skypuppy/health - Service health status
• GET /skypuppy/metrics - Prometheus metrics export

API Endpoints

• GET /skypuppy/v1/service/{name} - Get service status
• POST /skypuppy/v1/service - Add new service
• PUT /skypuppy/v1/service/{name} - Update service
• DELETE /skypuppy/v1/service/{name} - Remove service

Prometheus Metrics

Sky Puppy exports the following metrics:

• sky_puppy_service_health_status - Service health status (0=down, 1=unhealthy, 2=healthy)
• sky_puppy_service_response_time - Service response time in milliseconds
• sky_puppy_service_check_count - Total number of checks performed

🎯 Use Cases

Web Application Monitoring

{
  "services": {
    "web-app": {
      "interval": 30,
      "checker": {
        "name": "request",
        "settings": {
          "uri": "https://myapp.com/api/health",
          "timeout": 10,
          "method": "GET"
        }
      }
    }
  }
}

Database Health Checks

{
  "services": {
    "mongodb": {
      "interval": 60,
      "checker": {
        "name": "sky-puppy-checker-mongodb",
        "settings": {
          "uri": "mongodb://localhost:27017",
          "database": "myapp"
        }
      }
    }
  }
}

External Service Monitoring

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

🔧 Advanced Configuration

Environment Variables

• SKY_PUPPY_PORT - Server port (default: 8069)
• SKY_PUPPY_IP - Server IP (default: 0.0.0.0)
• SKY_PUPPY_CONFIG_PATH - Custom config folder path

Logging Configuration

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

🚀 Deployment

Docker

FROM node:18-alpine
RUN npm install -g sky-puppy
COPY sky-puppy-config.json /app/
WORKDIR /app
EXPOSE 8069
CMD ["sky-puppy"]

Systemd Service

[Unit]
Description=Sky Puppy Health Monitor
After=network.target

[Service]
Type=simple
User=sky-puppy
WorkingDirectory=/opt/sky-puppy
ExecStart=/usr/bin/sky-puppy
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

Development Setup

git clone https://github.com/Phara0h/sky-puppy.git
cd sky-puppy
npm install
npm test

📚 Documentation

• API Reference
• Configuration Guide
• Checker Development
• Alerting Setup

📄 License

This project is licensed under the GPL-3.0-or-later License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Fastify for blazing fast performance
• Prometheus metrics powered by nstats
• Templating with the tiniest and fastest javascript templating engine nbars

Made with ❤️ by the Sky Puppy community

Report a Bug | Request a Feature | Star on GitHub

Changelog

All notable changes to this project will be documented in this file. Dates are displayed in UTC.

v1.5.5

a8d0908updated fastify which fixed routes

v1.5.4

29 December 2025

65a3deeupdated nstats

v1.5.3

29 December 2025

b2d23f6Update alerts.js

v1.5.2

29 December 2025

b43e29eUpdate alerts.js

v1.5.1

29 December 2025

63b8611Fixed "enabled" being set in config and being ignored

v1.5.0

29 December 2025

6fdef5fAdded json parsing to the messages for alerts

3423623siteupdates

92272cefixed a space

v1.4.1

10 July 2025

370545fupdate mdsquash

v1.4.0

10 July 2025

596e16dTons of documentation, new website and cleanup

v1.3.8

11 December 2020

628dc13FIxed some bugs, made sky puppy more crash safe and better logging

v1.3.7

18 November 2020

0cc7817Fixed a minor bug, dates should now work in prom.

v1.3.6

17 November 2020

61b2674Minor debug fix

v1.3.5

17 November 2020

ec30c55Few fixes

• Added date to each prom stats only when it was updated
• Fixed bug with version not showing in prom stats
• Fixed possible bug around alerts

v1.3.4

4 November 2020

e196e2bFixed bug Cannot find module package.json

v1.3.3

4 November 2020

9b1b3c0Fixed bin package bug

v1.3.2

4 November 2020

6197717ETIMEDOUT is now unhealthy instead of down

v1.3.1

4 November 2020

9712744Update changelog-template.hbs

v1.3.0

4 November 2020

bd98346Fixed bugs and added pretty console logs

• Fixed last_unhealthy_total_duration and last_healthy_total_duration bug reporting the wrong elapsed time.
• Fixed healthy status getting reported even when unhealthy/down has not yet been reported.
• Fixed bug relating to console title displaying config version instead of application version.
• Added new console logs (see sample config for details)
• Added 2 new test-server routes

v1.2.0

3 November 2020

6604d77Clean up and more

• Added skypuppy console log title
• Fixed eslint issues
• Fixed bug that altered on healthy status at start of sky puppy
• Fixed bug if settings field was left out of services checkers

v1.1.2

2 November 2020

6e251c0Added sky-puppy-checker-cloudflare-status to the list of checkers

d204255Added sky-puppy-checker-mongodb to list of checkers

v1.1.1

2 November 2020

4b1a2e4Fixed changelog to have full commit message

v1.1.0

2 November 2020

7f27201New feature: Messages

• Added the ability to add messages from checkers
• Messages can be accessed in alterters message / viewed in prom
• Added the ability to map codes to messages in a global setting via checkers settings EX:

"sky-puppy-checker-template": {
"foo": "bar",
"code_messages": {
"200": "Override me plz",
"500": "Yikes its down"
}
}

• Added the ability to override those code_messages inside each service as well EX:

"checker": {
"name": "sky-puppy-checker-template",
"settings": {
"bar": "test"
},
"code_messages": {
"200": "Yup its up"
}
}

v1.0.2

30 October 2020

a927cdfAdded sky-puppy-checker-template to tests and readme

v1.0.1

30 October 2020

7674805Fixed bug around checkers name

v1.0.0

30 October 2020

344b6f0Added module based checkers! Now you can write custom checkers to check any thing.

v0.3.0

30 October 2020

5d614ebAdded endpoints, Added postman docs, Fixed bugs and more!

f6f9a56added process tile

v0.2.1

14 September 2020

505209aUpdate README.nbs

v0.2.0

14 September 2020

b03ca2einit commit config based is done REST endpoints to come

b7535a3Initial commit