Collect and display statistics via a lightweight Ruby daemon
MIT License
Mouth is a Ruby daemon that collects metrics via UDP and stores them in Mongo. It comes with a modern UI that allows you to view graphs and create dashboards of these statistics. Mouth is very similar to StatsD + Graphite + Graphene.
Why duplicate effort of the excellent StatsD / Graphite packages? I wanted a graphing and monitoring tool that offered:
There are two kinds of metrics currently: counters and timers. Both are stored in a time series with minute granularity.
Make sure you're using Ruby 1.9.2+ or compatible.
Install mouth:
gem install mouth
Install MongoDB if you haven't:
brew install mongodb
Start collector daemon:
mouth
Start web UI:
mouth-endoscope
Record a metric:
ruby -e 'require "mouth"; require "mouth/instrument"; Mouth.increment("gorets")'
To load the web UI, go to http://0.0.0.0:5678/ (or whatever port got chosen -- see the Terminal). Click 'Add Graph' in the lower right-hand corner.
You'll want to follow the general gist of what you did for OSX, but make sure to specify your hosts, ports, and log locations. NOTE: there is no config file -- all options are via command-line.
sudo gem install mouth
mouth --pidfile /path/to/log/mouth.pid --logfile /path/to/log/mouth.log -H x.x.x.x -P 8889 --mongohost y.y.y.y --verbosity 1
mouth-endoscope --mongohost x.x.x.x
There are many ways to instrument your application:
Mouth comes with a built-in facility to instrument your apps:
require 'mouth'
require 'mouth/instrument'
Mouth.daemon_hostport = "0.0.0.0:8889"
Mouth.increment('hello.world')
Mouth.measure('hello.happening') { happen! }
Mouth.gauge('hello.level', 1000)
mouth-instrument is a lightweight gem that doesn't have the baggage of the various gems that come with mouth. Its usage is nearly identical:
gem install mouth-instrument
require 'mouth-instrument'
Mouth.daemon_hostport = "0.0.0.0:8889"
Mouth.increment('hello.world')
Mouth.measure('hello.happening') { happen! }
Mouth.gauge('hello.level', 1000)
Mouth is StatsD compatible -- if you've instrumented your application to record StatsD metrics, it should work on Mouth. Just replace your StatsD server with a mouth process.
You can access and act on your metrics quite easily.
require 'mouth'
require 'mouth/sequence_query'
Mouth::SequenceQuery.new("exceptions.app", :kind => :counter).sequence
# => [4, 9, 0, ...]
Mouth::SequenceQuery.new("app.requests", :kind => :timer, :granularity_in_minutes => 15, :start_time => Time.now - 86400, :end_time => Time.now).sequence
# => [{:count => 3, :min => 1, :max => 30, :mean => 17.0, :sum => 51.0, :median => 20, :stddev => 12.02}, ...]
Additionally, you can insert metrics directly into the Mongo store, without sending UDP packets. You might want to do this if you need guarantees UDP can't provide.
require 'mouth'
require 'mouth/recorder'
Mouth::Recorder.increment("app.happening")
Mouth::Recorder.gauge("app.level", 10)
# Mouth::Recorder.measure("app.occurrence") { occur! } # Currently unsupported
You're interested in contributing to Mouth? AWESOME. Both bug reports and pull requests are welcome!
Fork Mouth from here: http://github.com/cypriss/mouth
Thanks to UserVoice.com for sponsoring this project. Thanks to the StatsD project for massive inspiration. Other contributors: https://github.com/cypriss/mouth/graphs/contributors