cppforlife / checkman

Checkman runs your custom script(s) periodically and then updates system tray icon status.

Checkman

Checkman runs your custom script(s) periodically and then updates system tray icon. It could be used to check on CI build status, site http response, etc.

Installation

Install and open Checkman Mac app into /Applications (backslash is for overriding possible bash alias):

\curl https://raw.githubusercontent.com/cppforlife/checkman/master/bin/install | bash -s

If you ever need to kill Checkman:

killall Checkman

Configuring Checkman via Checkfile(s)

• Any number of config files in ~/Checkman directory

• Each config file can define any number of checks. Each check definition takes up a single line made of a name and a valid bash command separated by colon-space. Example checkfile with 3 checks:

  google.com: site.check http://www.google.com
  
  #-
  #- jenkins-ci.org builds
  jenkins_main_trunk: jenkins_build.check https://ci.jenkins-ci.org jenkins_main_trunk
  jenkins_lts_branch: jenkins_build.check https://ci.jenkins-ci.org jenkins_lts_branch
  

• Commands run relative to the containing checkfile.

• Symlinks are resolved. Suggested approach is to have per-project Checkfile with project specific checks and symlink to them from ~/Checkman directory. e.g. ln -s ~/workspace/my-project/Checkfile ~/Checkman/my-project

• Hidden config files (prefixed with .) are skipped.

• Config files are reloaded when changes are saved.

• # can be used to comment.

• #- is used as a separator.

• #- Some title is used as a title separator.

• Tip: works great with tee to keep check's history e.g. site.check http://site.com | tee -a tmp/site.log

Included check scripts

• site.check <URL>
  checks returned http response for 200 OK
  e.g. site.check http://www.google.com

• buildkite.check <ORG_SLUG> <PIPELINE_NAME> <BRANCH> <ACCESS_TOKEN>
  checks the status of a Buildkite pipeline ACCESS_TOKEN requires only read_builds authorization to org PIPELINE_NAME should be quoted if it contains spaces e.g. buildkite.check myorg 'My Pipeline' master abcde12345

• cctray.check https://user:pass@<CCTRAY_URL> <PIPELINE_NAME>
  checks the status of a GoCD pipeline
  e.g. cctray.check https://admin:badger@[your_go_server]/go/cctray.xml

• concourse.check <ATC_URL> [USERNAME] [PASSWORD] <PIPELINE_NAME> <JOB_NAME>
  checks status of a job in a Concourse pipelne e.g. concourse.check https://ci.concourse.ci admin passw0rd deploy

• jenkins_build.check <JENKINS_URL> <JOB_NAME>
  checks specific Jenkins build status
  e.g. jenkins_build.check https://user:[email protected] jenkins_main_trunk
  (Tip: Encode @ symbol as %40 in username)

• travis.check <REPO_OWNER> <REPO_NAME> [<REPO_BRANCH>] [<REPO_TOKEN>]
  checks specific Travis CI build status
  e.g. travis.check rails arel

• semaphore.check <PROJECT_API_ID> <BRANCH_ID> <AUTH_TOKEN>
  checks specific SemaphoreApp CI build status
  e.g. semaphore.check 0691ba134341d1baa978436535b6f2b79fec91 27680 1iGx6asGJHk6aMdsB4eu
  (Tip: open project's settings page, then find the "API" tab to get required ids)

• codeship.check <PROJECT_ID> <API_KEY> <REPO_BRANCH>
  checks specific Codeship CI build status
  e.g. codeship.check 12345 0ea7bbedf3340775cecee5f816d03bdfac69c81f816d03bdfac69c81fqw2 master
  (Tip: find the API_KEY under account settings)

• circleci.check <USERNAME> <PROJECT_NAME> <BRANCH_NAME> <API_TOKEN>
  checks specific Circle CI build status
  e.g. circleci.check myusername myproject master 73e86a18efba7df5cfc5e03c4b67ff06685c5a75
  (Tip: open project's setting page, then find the "API Tokens" tab to create an API token of type 'status' or 'all')

• circlecijson.check <USERNAME> <PROJECT_NAME> <BRANCH_NAME> <API_TOKEN>
  checks specific Circle CI build status using the JSON interface which provides build time data
  e.g. circlecijson.check myusername myproject master 6cadaa96f7c455a658e00dd4500adc8f654342cc
  (Tip: open project's setting page, then find the "API Tokens" tab to create an API token of type 'all')

• test.check <OPTION_0> ... <OPTION_N> returns predefined check result
  (options: url, info, fail, changing, slow, error, flapping)
  e.g. test.check fail slow

• airbrake.check <ACCOUNT_NAME> <API_TOKEN> <PROJECT_ID>
  checks for recent errors
  e.g. airbrake.check my-company 2a743rueigw87tegiofs7g 43878087

• github_issues.check <REPO_OWNER> <REPO_NAME>
  checks for issues in GitHub repo
  e.g. github_issues.check rails rails
  (Tip: Since GitHub rate limits api requests set GITHUB_ISSUES_CHECK_CLIENT_ID and GITHUB_ISSUES_CHECK_CLIENT_SECRET. See check's code on how to obtain client id/secret.)

• tracker.check <PROJECT_ID> <API_KEY> <FULL USER NAME>
  Checks for your owned story statuses in Tracker, requires the Pivotal Tracker Gem.
  e.g tracker.check 1234 ABC123 Trent Beatie

  • Green: You don't own any rejected stories
  • Red: You own a rejected story
  • Pending: You haven't started a story

• tddium.check <ORGANIZATION_TOKEN> <PROJECT_NAME> <BRANCH_NAME>
  Checks specific TDDium project build status.
  e.g. tddium.check 0691ba134341d1baa978436535b6f2b79fec91 project branch_name
  Hint: to get the token, log in to your TDDium dashboard, go to Organizations using the drop down in the top right corner. Then click on organization settings for the appropriate organization. Then click on "Chat Notifications"; CCmenu is at the bottom of the page. Extract the token from the URL, which looks like: https://api.tddium.com/cc/ORGANIZATION_TOKEN/cctray.xml

• snapci.check <URL TO CCTRAY FEED> "<PROJECT NAME>" "<STEP NAME>"
  Checks the build status of a specific step in Snap CI
  e.g. snapci.check https://snap-ci.com/some-random-hash/cctray.xml "my-github-org/my-repo (branch-name)" "MyStepInSnapCi"
  To get the PROJECT NAME, look at the CCTray XML and paste in the value before the :: from <Project name="">
  To get the STEP NAME, look at the CCTray XML and paste in the value after the :: from <Project name="">

Above scripts are located in /Applications/Checkman.app/Contents/Resources/. Checkman makes these scripts available by appending stated path to PATH env variable when running check commands.

Building custom check scripts

Each check is expected to output following JSON to stdout:

{
  // [Required]
  // Indicates whether check succeeded
  "result": <bool>,

  // [Optional]
  // Indicates whether result is in progress of being changed
  // e.g. CI build is in progress
  "changing": <bool>,

  // [Optional]
  // Url to open when check menu item is clicked
  "url": <string|null>,

  // [Optional]
  // List of additional details to show in the submenu
  "info": [
    [<string>, <string>] // Key-value pairs
  ]
}

You can print anything to stderr. Check out included scripts/ for examples.

Debugging

• Option + click check menu item - open check's debugging window. Shown command/stderr/stdout will be updated as time passes. Refer to Debugging Tips wiki page for more tips.

• Control + click check menu item - restart check run.

Stickies and notifications

• Stickies: mini alert per check appears in right bottom corner if check turns red. Alert disappear when check turns back to green. Stickies are enabled by default.

• Notifications: there are 3 supported notification transports: built-in, Growl and OS X Notification Center. See 'Custom user settings' section on how to enable notifications.

Custom user settings

Change run interval for all/single check(s) (where INTERVAL is integer > 0):

defaults write com.tomato.Checkman checkRunInterval -int <INTERVAL>
defaults write com.tomato.Checkman checks.<CHECKFILE>.<CHECK>.runInterval -int <INTERVAL>

Disable single check:

defaults write com.tomato.Checkman checks.<CHECKFILE>.<CHECK>.disabled -bool YES

Disable stickies:

defaults write com.tomato.Checkman stickies.disabled -bool YES

Enable notification transports:

defaults write com.tomato.Checkman notifications.custom.enabled -bool YES
defaults write com.tomato.Checkman notifications.growl.enabled -bool YES
defaults write com.tomato.Checkman notifications.center.enabled -bool YES

View all current customizations:

defaults read com.tomato.Checkman

Delete specific customization:

defaults delete com.tomato.Checkman <SETTING>

Note: CHECKFILE is checkfile name before symlinks are resolved.

Running check script specs

Script specs currently target Ruby 1.8.7, which doesn't build by default on Mojave. It's easiest to use Docker:

docker pull ruby:1.9-wheezy
docker run -v `pwd`:`pwd` -w `pwd` -it ruby:1.9-wheezy /bin/bash
cd script/specs
bundle
rspec .

Todos

• Audit CPU/memory usage
• Find permanent status images
• Run only single instance of the app
• Indicate when check info was last updated
• Limit number of checks running concurrently

Thanks to

• Doc Ritezel
• Aram Price
• James Bayer

checkman's Issues

Editing Checkfile while Checkman seems to be additive instead of replace

Using vi to edit a Checkfile while Checkman is running ends up increasing the counter in the system bar, but the UI only shows the updated values. Perhaps the old checks stay around?

Add a configuration via file

a JSON file in my Checkman directory instead of "defaults write" would be nice...

Data directory should be in ~/Library/Application Support

For an OS X application, the canonical place for this sort of data is in ~/Library/Application Support or ~/Documents, not in ~/Checkman

to install via brew cask

would be pretty sweet

https://github.com/caskroom/homebrew-cask

Please remove ci.jenkins-ci.org from default checks

The defaults included for checkman have been hammering the Jenkins project's Jenkins instance that I have long since inserted a custom redirect to this page

This traffic is abusive and fills our access logs with garbage requests. I would like to kindly ask that you remove our public Jenkins instance from the defaults for Checkman.

travis.check building? should check for state=finished

should be red and not building:

{
    "id":19198253,
    "repository_id":1377279,
    "number":"103",
    "state":"finished",
    "result":null,
    "started_at":"2014-02-19T17:27:23Z",
    "finished_at":"2014-02-19T17:28:29Z",
    "duration":66,
    "commit":"34d843180f451dc26c690b2b21c4e7243c2f2974",
    "branch":"master",
    "message":"update etcd to 0.3",
    "event_type":"push"
}

Need an Icon

Especially since I've moved my notifications to Notification center, seeing the "no icon" icon is a pain.

I'd make a pull request and give you one, but the Icon is the app's personality...

URL not escaped

If I use basic auth in the url for checking and it includes a quotation mark, it has to be manually escaped.

Support UTF-8 as is returned by jenkins

I'm seeing the below error in the checkman debugger window. It appears that the misbehaving character is the long dash thing — '\xE2'

/Users/mopub/.rvm/rubies/ruby-1.9.3-p392/lib/ruby/1.9.1/json/common.rb:148:in encode': "\xE2" on US-ASCII (Encoding::InvalidByteSequenceError) from /Users/mopub/.rvm/rubies/ruby-1.9.3-p392/lib/ruby/1.9.1/json/common.rb:148:ininitialize'
from /Users/mopub/.rvm/rubies/ruby-1.9.3-p392/lib/ruby/1.9.1/json/common.rb:148:in new' from /Users/mopub/.rvm/rubies/ruby-1.9.3-p392/lib/ruby/1.9.1/json/common.rb:148:inparse'
from /Applications/Checkman.app/Contents/Resources/jenkins_build.check:98:in initialize' from /Applications/Checkman.app/Contents/Resources/jenkins_build.check:156:innew'
from /Applications/Checkman.app/Contents/Resources/jenkins_build.check:156:in latest_status' from /Applications/Checkman.app/Contents/Resources/jenkins_build.check:171:in

'

This causes checkman to blow up on certain checks.

Might just need a line in the ruby app to support UTF-8?

Thanks.

Checkman doesn't seem to work with latest Semaphore project tokens

Semaphore has seemingly changed the structure of their project IDs from the style of "3c230d7617c3732dcccccccb1ddc89fc357cd83" to a newer "09e46d07-bbbb-aaaa-a1b0-483212809670" style. This seems to have broken Checkman for new semaphore projects.

Picking up incorrect project from GoCD

Spotted an oddity with checkman today - it's reporting that one of our builds, redis-release has failed, but when we go to the build server, it's passed.

Looking at what GoCD returns, for our project I see the following:

<Project name="redis-release :: <...>" activity="Sleeping" lastBuildStatus="Success" lastBuildLabel="<...>" lastBuildTime="2015-06-13T12:09:59" webUrl="<...>" />

However, there is another project with the following:

<Project name="cf-redis-release :: <...>" activity="Sleeping" lastBuildStatus="Failure" lastBuildLabel="<...>" lastBuildTime="2015-06-13T12:55:58" webUrl="<...>">

Looking at cctray.check, I guess it's the following code causing the problem:

projects = @feed.xpath('//Project').select do |proj|
  proj.attr('name').downcase.include?(name.downcase)
end

Does that need to be include? or would start_with? or == be OK too?

May also be showing up because cf-redis-release has a more recent build than redis-release.

Show reds before greys

Cloud Ops just redeployed Concourse, and the number of greys is off the screen, both in the webpage and the smaller popups. On both, it would be good to ensure visibility of the failed builds before the builds that haven't been run yet.

Xcode Tests aren't Runnable Beyond Xcode 8

Looks like Xcode iterations have deprecated things that we depend on. Mostly notably, Cedar doesn't seem to be compatible with the new build system.

Putting the build system into a legacy mode helps but Cedar's output is still missing after things run successfully.

Quit Checkman button as last menu item

FEATURE REQUEST: more flexible interval override

Currently, we use site checks as a "MVP CI" - e.g. we hit a "canary page" that indicates if a given site is working correctly.

However, we want these to be at a longer interval (e.g. 120 seconds), so they don't spam the server with requests.

The problem is when we add or change a site check name, all existing workstations don't have the local override for the new site name, they default to frequently checking it and spamming it.

This has a "viral" effect, of all workstations spamming as soon as they pull the new Checkfile, until the local interval override is made for the new sites.

Two possible solutions:

1. Make local interval overrides take wildcards/regex, e.g. so all site checks can be given a longer interval, regardless of their name
2. Allow interval to be overridden in the Checkfile itself, so the interval is set as soon as the new Checkfile (and new sites) are checked out.

Notify me that new version of Checkman is available

Add Donate button so I can give you money

during installation old checkman does not give up webui port fast enough for new checkman to start listening on

results in webui showing lost connection...

How do I know which Checkman is running?

Maybe an About menu item that shows version info? Could also be the place where you put a new version indicator?

Is there anyway to port checkman to linux environment?

We have developers both using OSX and linux environment.

What's the best way to port the checkman also on linux environment?

Is there any command line interfacoe for checkman?

Thanks, Shin

Support for codeship.io?

We are using the lovely CI in the cloud over at codeship.io. They have a JSON API: https://www.codeship.io/documentation/api-and-webhooks/api/

Checkman stops polling upon getting a 504

Checkman seems to stop polling when using the site script and the response is a 504 (I believe this happens with a 502 too, but didn't have logs to show it). This results in a red build until Checkman is restarted.

Example log output from Alt+clicking the build in question:

cd /Users/pivotal/Dropbox/front-end; /bin/bash "-lc" "PATH=$PATH:/Applications/Checkman.app/Contents/Resources site.check https://console.run.pivotal.io/heartbeat"

{"result":false,"changing":false,"url":"https://example.com/heartbeat","info":[["Url","https://example.com/heartbeat"],["Status","HTTP/1.1 504 Gateway Timeout"],["Content-length:0"]]}

stty: stdin isn't a terminal
stty: stdin isn't a terminal
curl -sIk -A "CheckmanSite (Hostname: $HOSTNAME)" 'https://example.com/heartbeat'
HTTP/1.1 504 Gateway Timeout

Content-length:0

Doesn't work with Ruby 2.2

Maybe we should use /usr/bin/ruby for all the scripts? The system ruby is more stable and boring.

Feature request: Support concourse CI builds

stty: stdin isn't a terminal

So there a couple of things that are wrong. The first is that I put a comma on the line, because I thought the config file was Ruby and Shell. My bad, perhaps documentation bad? Since comments are prefixed with hashes anyway, include the shebang on line 1 of the example file so we all know what type of file we're dealing with.

The error is because whatever is processing the config file is firing up an interactive shell, somehow.

$ cat mine
sample: test.check "true", "true"
$

{"result": false, "changing": true}

stty: stdin isn't a terminal

Airbrake.io script is broken (maybe because of new APIs)?

The URL used to check for project errors, http://my-project.airbrake.io/projects/{PROJET-ID}/errors.xml?auth_token={TOKEN}, now returns a 404.

Not sure where you got the original documentation for this, but according to the API overview:

To get the XML for the 30 most recently active errors:
http://your_account.airbrake.io/errors.xml?auth_token=TOKEN

I don't see how to specify a specific project in this URL, but I just skimmed through the docs.

r.

Notifications don't show up in Notification Center

I tried adding the config setting as described but I still just get custom notifications.

CircleCIJson check fails for one branch and not for another.

I am seeing a problem with the CircleCI JSON check where it fails to load status for one branch but is able to load the status for another branch. Using the CircleCI status only check works for this branch. I tried running the curl requests directly and saw that the sizes of the results differed dramatically (125KB for working check vs 263KB for the broken one). I don't see any error messages when I run Checkman in the terminal so that I can see its output (all I see is periodic FSChangesNotifier - didNoticeChangeToPath: /Users/username). If the size is the source of the problem, possibly limiting the count of pulled builds would solve the problem (the JSON endpoint supports a limit=10 parameter).

Web UI does not work in Firefox due to web socket connectivity problems

When trying to view the web UI in Firefox, calls to /check_updates fail with a "400 Bad Request".

When one build is queued and another is running on Travis, Checkman thinks the build has failed

We committed once, a build started, and then we pushed another commit. Checkman's information radiator marked the build as red even though it hadn't failed.

@ematpl and I saw this, happy to chat in person if required.