{"id":21871868,"url":"https://github.com/kcmerrill/spock","last_synced_at":"2026-05-15T23:34:13.396Z","repository":{"id":151120443,"uuid":"86757159","full_name":"kcmerrill/spock","owner":"kcmerrill","description":"Making sure your applications live long and prosper.","archived":false,"fork":false,"pushed_at":"2017-10-16T04:21:42.000Z","size":8282,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-01-26T17:11:21.304Z","etag":null,"topics":["customizable","extensible","monitoring","nagios","pingdom","simple"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kcmerrill.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-30T23:10:48.000Z","updated_at":"2017-04-09T21:19:13.000Z","dependencies_parsed_at":null,"dependency_job_id":"26fa0681-0f09-4ce6-8ba2-f983274e1de5","html_url":"https://github.com/kcmerrill/spock","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcmerrill%2Fspock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcmerrill%2Fspock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcmerrill%2Fspock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kcmerrill%2Fspock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kcmerrill","download_url":"https://codeload.github.com/kcmerrill/spock/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244877212,"owners_count":20524981,"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":["customizable","extensible","monitoring","nagios","pingdom","simple"],"created_at":"2024-11-28T06:15:40.167Z","updated_at":"2026-05-15T23:34:08.376Z","avatar_url":"https://github.com/kcmerrill.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spock\n\nMaking sure your applications live long and prosper.\n\n[![Build Status](https://travis-ci.org/kcmerrill/spock.svg?branch=master)](https://travis-ci.org/kcmerrill/spock) [![Join the chat at https://gitter.im/kcmerrill/spock](https://badges.gitter.im/kcmerrill/spock.svg)](https://gitter.im/kcmerrill/spock?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\n![Spock](assets/spock3.jpg \"Spock\")\n\n## Binaries || Installation\n\n[![MacOSX](https://raw.githubusercontent.com/kcmerrill/go-dist/master/assets/apple_logo.png \"Mac OSX\")](http://go-dist.kcmerrill.com/kcmerrill/spock/mac/amd64) [![Linux](https://raw.githubusercontent.com/kcmerrill/go-dist/master/assets/linux_logo.png \"Linux\")](http://go-dist.kcmerrill.com/kcmerrill/spock/linux/amd64)\n\nvia go:\n\n`$ go get -u github.com/kcmerrill/spock`\n\nvia docker:\n\n`$ docker run -ti -v $PWD/dir/to/root/channels/and/checks:/spock kcmerrill/spock`\n\n## GUI\nYou can see the status of your checks via the [spock gui](https://spock.kcmerrill.com).\n[![gui](assets/gui.png)](https://spock.kcmerrill.com)\n\nIt's just a simple single page application. Your standard webserver should be able to serve the files from the `gui` directory just fine. Or, you can use docker by running `docker run -d --restart always --name spock -P kcmerrill/spock-gui`\n\n## 4 minute(6 http checks) setup\n\n[![asciicast](assets/screenshot.png)](https://asciinema.org/a/112261)\n\n## About\n\nNot meant to be a nagios replacement per se, but if you're just a small shop with a few hundred checks, then `spock` is for you. I wanted a way to get simple and complex checks up and running without all the overhead that the bigger monitoring systems require. The simple ones, like `dead mans snitch` or `pingdom` are all great services, but they only have paid accounts and I didn't want to pay for something. Essentially `spock` is scratching an itch I've had for forever.\n\n## The idea\n\nThe concept behind `spock` makes it dead simple to get up and running. There are two aspects you should familiarize yourself with before continuing on. `checks` and `channels`. Essentially they are yaml file(s) located in their respective `checks` and `channels` folders.\n\n### Checks\n\nChecks are actions that `spock` does at regular intervals. You can use `cron` syntax, `every` syntax. You can [read more about it here](https://godoc.org/github.com/robfig/cron). What `spock` does at these intervals is completely up to you. Custom checks, url checks, disk space, etc ... it's up to you and what you need to check and alert on.\n\nA quick example of what checks would look like. Within the `checks` folder you create, you can have one or many yaml files, just be sure to keep the check names unique. The check name in the example below would be `kcmerrill.com` and `crush.kcmerrill.com`. \n\n```yaml\n\nkcmerrill.com:\n    url: http://kcmerrill.com\n    params: --status 200 --contains digital\n    every: 10s\n    try: 3\n    fails: slack \n\ngo-dist.kcmerrill.com:\n    url: http://go-dist.kcmerrill.com/kcmerrill/spock\n    fails: slack\n\ncrush.kcmerrill.com:\n    cron: \"*/30 * * * * *\"\n    shell: |\n        wget -qO- https://crush.kcmerrill.com/test/something || (echo \"Crush no longer accepting messages\" \u0026\u0026 false)\n    fails: slack\n   \ntmp.dir.exists:\n    every: 1h\n    dir.exists: /tmp\n    fails: slack\n\nmy.task:\n    every: 10s\n    heartbeat: 1h\n    fails: slack \n```\n\n* **cron** is simply the same cron syntax you're used of. You can [read more about it here](https://godoc.org/github.com/robfig/cron). \n\n* **every** can be a golang `time.Duration` or special strings such as `@hourly`, `@daily`, `@midnight`. You can [read more about it here](https://godoc.org/github.com/robfig/cron).\n\n* **shell**, **url**, **heartbeat** are custom `channels`. This can be anything you'd like so long as it has a corrisponding `channel`. `spock` has a few custom `channels` built in. `slack`, `shell`, `url`, `heartbeat`. We can add more, we can also add public github repofiles as channels too! \n\n* **params** is a string of parameters to send to your `channel`. So in this case, imagine you had an application in your `$PATH` called `url`(Don't worry if you don't, `url` is built into `spock`). What would be executed is `$ url http://kcmerrill.com --status 200 --contains digital`. By default, the `url` check looks for status code `200`. It only checks if the page `contains` a certain word if you supply it. So even though the page might be running, if it doesn't contain the word `digital` the check will fail.\n\n* **try** indicates the number of attempts `spock` should try and fail before notifying. Sometimes network connections can be finicky, scripts or whatever. By default, without `try` it will automatically alert upon it's first failure. \n\n* **fails** is a space separated string that describes the `channels` to send the check to. Currently, only `slack` is built in, but you can easily add `email`, `logging` or whatever suits your needs.\n\n* **dir.exists** is a custom channel that _does not_ exist ... yet. Lets take a peek at `channels` now and we'll walk through how to create the `dir.exists` channel. Contrived example to be sure, as you could've just done `shell: ls /tmp` but that's neither here nor there.\n\n### Channels\n\nThink of channels like a mix between a `topic` on a queue and a `lambda`. Because, behind the scenes, that's all they are! `channels` are just small bits of code, local applications you can run, or custom scripts(hosted locally or publicly on github) you create that perform actions. These actions can do whatever you want, but in the case of `checks` need to return a proper `exit` code. `0` for success. `1` for failure.\n\n`spock` sends in via stdin a json representation of what the `check` looks like at that moment in time. You don't need this, but it could be helpful for notifications as an example.\n\nSame thing with the `slack` channel. It takes information in regarding the check and depending on how you want to display it, sends it to slack. \n\nSame as `checks`, `channels` are stored under the `channels` folder you create. We will create the `dir.exists` as a custom channel along with a few other contrivied examples. A few things to note about the `slack` channel, in order to get slack working, you'll need to send in a `webhook` param with your webhook integration url. We'll do that here too to show what it should look like. By default, `template` is already set, but you customize it.\n\n```golang\n\nslack:\n    params: --webhook=http://your.slack.webhook.com/url/here\n    template: {{ .Name }} is down! Tried {{ .Attempts }} time(s) before letting you know!\n   \ndir.exists:\n    custom: ls\n    \nwhoami:\n    command: php\n    code: \u003e\n        \u003c?php \n            if(trim(`whoami`) != \"kcmerrill\") {\n                echo \"You're not who you say you are!\"; // anything sent to stdout is included in the error\n                exit(1);\n            }\n            exit(0);\n\nawesomely.extensible:\n    github.com: username/project/path/to/file.(extension: py|rb|php)\n```\n\nThe idea behind including `github` is just to increase the extensibility of `spock`. We can get a big collection of `channels` of scripts to test various things. This will be `spocks` version of plugins.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcmerrill%2Fspock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkcmerrill%2Fspock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkcmerrill%2Fspock/lists"}