{"id":20310824,"url":"https://github.com/progrium/skywatch","last_synced_at":"2025-04-11T16:03:58.242Z","repository":{"id":6028952,"uuid":"7253038","full_name":"progrium/skywatch","owner":"progrium","description":"Magic cloud alerting system in a self-contained command-line utility","archived":false,"fork":false,"pushed_at":"2012-12-20T19:14:45.000Z","size":146,"stargazers_count":37,"open_issues_count":2,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-03-25T12:06:48.310Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/progrium.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-12-20T06:11:11.000Z","updated_at":"2023-02-13T10:39:50.000Z","dependencies_parsed_at":"2022-09-12T13:12:41.908Z","dependency_job_id":null,"html_url":"https://github.com/progrium/skywatch","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progrium%2Fskywatch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progrium%2Fskywatch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progrium%2Fskywatch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/progrium%2Fskywatch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/progrium","download_url":"https://codeload.github.com/progrium/skywatch/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248438493,"owners_count":21103409,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T17:34:39.352Z","updated_at":"2025-04-11T16:03:58.203Z","avatar_url":"https://github.com/progrium.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Skywatch (alpha)\n\nA simple alerting system that lets you define checks and alerts in any\nlanguage that are then magically run on Heroku. Nagios can go cry in a\ncorner.\n\nNoOps! Polyglot! Free monitoring of anything!\n\n## Installation\n\n    $ gem install skywatch\n\n## Usage / Quickstart\n\nIt's a fairly powerful tool. Run `skywatch --help` to see a list of\nsubcommands. Here is the quickest way to something interesting:\n\n    $ mkdir demo \u0026\u0026 cd demo             # make a directory for your scripts\n    $ skywatch init                     # this will fail and require Heroku auth\n    $ skywatch init                     # run again, after logged in\n    $ skywatch enable check example     # enable the example check script\n    $ skywatch deploy                   # everything is shipped to Heroku\n    $ skywatch monitor                  # watch it run in the cloud\n\n## Features\n\n * Lets you monitor or assert anything at any frequency\n * Scriptable alerts (email, sms, tweet, etc)\n * Runs in the cloud on Heroku for free\n * Completely automated deployment\n * Easily monitor activity logs in real-time\n * Enable / disable checks or alerts\n * Unphased by flapping. You get alerted once.\n * Entire system is in self-contained CLI tool\n * Simple enough for personal use, powerful enough for commercial use\n * Can be used for building adaptive systems?\n\n## What the hell is this amazing thing??\n\n**tl;dr, skywatch is a tool to run repeating check scripts on\nHeroku. It's the simplest idea wrapped into a convenient utility.**\n\nSkywatch is a command-line utility that manages checking and alerting\nscripts used by a small (50 lines) watcher service. Skywatch deploys these\nscripts and the service on Heroku where they can run and monitor\nanything from the cloud for free.\n\nThe watcher service runs check scripts that can assert anything at any\nfrequency. If a check script returns a non-zero exit status, it will\nfire any enabled alert scripts, passing it the output of the check\nscript. Alert scripts can then act on this assertion failure, such as\nsend email, SMS, or webhook.\n\nThe check script will continue to run and potentially fail, but the\nalert script only runs once if it ran without error. Only until a reset signal\nis sent will it be ready to fire the alert again for any failed check\nscript. In this way, alerts work like [clip\nindicators](http://help.adobe.com/en_US/audition/cs/using/WS58a04a822e3e5010548241038980c2c5-7f93.html)\nin the audio recording world. They turn on once any clipping happens and\nremain on until you manually reset them.\n\nYou manage your scripts locally with the skywatch command, or by hand\nsince they're just files in directories. When you want to deploy script\nchanges, toggle enabled scripts, or reset the alert state, you can run a\nskywatch command and it will handle pushing changes to Heroku for you.\n\n## Using skywatch\n\nThe skywatch command manages a directory containing check scripts and\nalert scripts. You can make a new directory and let skywatch set this up\nfor you:\n\n    $ mkdir skywatch-demo\n    $ cd skywatch-demo\n    $ skywatch init\n\nIt will have you authenticate with your Heroku credentials if you\nhaven't already. [Grab a free account if you don't have\none.](https://api.heroku.com/signup) When you run `skywatch init`\nauthenticated it will create some example alerts and checks, then deploy\nan empty watcher to Heroku. None of the checks or alerts are enabled by\ndefault. See the scripts it set up by just running `skywatch` from the\ndirectory:\n\n    $ skywatch\n      Checks for fathomless-crag-3169\n        example                  every 30s        disabled\n        skywatch_watchers        every 3600s      disabled\n      Alerts for fathomless-crag-3169\n        email            disabled\n\nTake a look at all the files in the directory. Checks and alerts are nothing\nmore than scripts. Checks have a naming convention of `\u003cinterval\u003e.\u003cname\u003e`,\nand enabling and disabling is just setting the execute bit on the\nscripts. There's nothing the `skywatch` command does that you can't\neasily do by hand. It just happens to be terribly convenient.\n\n    $ skywatch edit alert email\n\nThis will open your editor and you can see the example email alert\nscript is using SendGrid. In fact, when you ran `skywatch init`, you\nwere set up with a free SendGrid starter addon for 600 emails a day. So\nlet's try it by putting your email address in the `TO` variable of the\nscript. Now enable the alert:\n\n    $ skywatch enable alert email\n\nLet's create a new check script in bash that fails so we can get the\nalert.\n\n    $ skywatch create check failure_test 30\n\nThe last argument is the interval. Intervals are always in seconds. All\nthis did was create a new file under the `checks` directory with a\nlittle bit of boiler plate. Let's replace its contents with this:\n\n    #!/usr/bin/env bash\n    echo \"Oh no, a failed check.\"\n    exit 255\n\nEnable the check and then deploy:\n\n    $ skywatch enable check failure_test\n    $ skywatch deploy\n\nIt's going to move some files around and then deploy to Heroku. It keeps\na staging directory called `.skywatch`, which is a Git repo used to push\nto Heroku. It automatically adds this to a `.gitignore` file, so you can\nversion your scripts with Git and not worry about this implementation\ndetail.\n\nOnce it's finished, you might want to run monitor to see how it went and\nwhat's going on. This is just tailing the Heroku logs of the watcher\nservice:\n\n    $ skywatch monitor\n\nYou can run this whenever to see what it's doing. You'll probably see\nthat it triggered the alert. Go check your email! That will be the only\nemail you get, regardless of whether the check starts to work again and\nthen fail again. No flapping. You have to manually reset:\n\n    $ skywatch reset\n\nThis should cause another alert email within 30 seconds. And of course,\nyou can tear everything down with destroy:\n  \n    $ skywatch destroy\n\nThis destroys the Heroku app and the `.skywatch` directory. It doesn't\ntouch your scripts at all. In fact, you can run `skywatch init` again if\nyou'd like. \n\nThe source code to all this is terribly simple. [The watcher service is\nonly about 50 lines of Ruby.](https://github.com/progrium/skywatch/blob/master/lib/skywatch/watcher/watcher.rb) Everything else is just file operations.\nIn fact, the little state it maintains is kept in file metadata. For how\nautomated it is, skywatch has to be one of the simplest monitoring services\never.\n\n## Writing Check Scripts\n\nCheck scripts are any executable script using the shebang to define the\ninterpreter. Heroku has most common languages built-in to its Cedar\nstack, so feel free to use Python, Perl, Ruby, whatever. I like bash.\n\nThe only conventions of check scripts are the interval-in-the-filename and that a non-zero exit status will fire the alerts. Any output of the check script will be piped into STDIN of the alert script, so try be verbose but not too\nverbose.\n\nIf you're using bash, it's a good idea to use `set -e` so any failed\nsubcommand will bubble up. Here's an example check script:\n\n    #!/usr/bin/env bash\n    set -e\n    curl --trace-ascii --silent --fail http://example.com\n\n## Writing Alert Scripts\n\nLike check scripts, alert scripts can be written in any language. Also,\nlike check scripts, the exit status is important. If an alert script\nexit status is non-zero, it will run again with the next failure of the check\nscript. \n\nThe alert script is given the output of the check script via STDIN. It's\nalso given 2 arguments. The first is the name of the check script. The\nsecond is the exit status of the failed check script. Here's an example\nalert script:\n\n    #!/usr/bin/env bash\n    TO=foobar@example.com\n    SUBJECT=\"[skywatch] $1\"\n    BODY=`echo -e \"Failure with status $2:\\n\\n$(cat)\"`\n    set -e\n    curl \\\n      -X 'POST' \\\n      -F \"api_user=$SENDGRID_USERNAME\" \\\n      -F \"api_key=$SENDGRID_PASSWORD\" \\\n      -F \"to=$TO\" \\\n      -F \"subject=$SUBJECT\" \\\n      -F \"text=$BODY\" \\\n      -F \"from=$TO\" \\\n      --silent --fail \"https://sendgrid.com/api/mail.send.json\"\n\nThe output of an alert script is ignored. It might be a good idea to log\nthe output of failed alert scripts. You'd then be able to see it via\n`skywatch monitor`. Sounds like a contribution idea.\n\n## Contributing\n\n1. Fork it\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create new Pull Request\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogrium%2Fskywatch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprogrium%2Fskywatch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprogrium%2Fskywatch/lists"}