yabeda-prometheus-mmap

Adapter for easy exporting your collected metrics from your application to the Prometheus! It is based on Prometheus Ruby Mmap Client, that uses mmap'ed files to share metrics from multiple processes. This allows efficient metrics processing for Ruby web apps running in multiprocess setups like Unicorn or Puma (clustered mode).

Installation

Add this line to your application's Gemfile:

gem 'yabeda-prometheus-mmap'

And then execute:

$ bundle

Usage

• Exporting from running web servers:

  Place following in your config.ru before running your application:

  require 'yabeda/prometheus/mmap'
  
  use Yabeda::Prometheus::Exporter
  

  Metrics will be available on /metrics path (configured by :path option).

  Also you can mount it in Rails application routes as standalone Rack application.

• Run web-server from long-running processes (delayed jobs, …):

  require 'yabeda/prometheus/mmap'
  
  Yabeda::Prometheus::Exporter.start_metrics_server!
  

  WEBrick will be launched in separate thread and will serve metrics on /metrics path.

  See yabeda-sidekiq for example.

  Listening address is configured via PROMETHEUS_EXPORTER_BIND env variable (default is 0.0.0.0).

  Port is configured by PROMETHEUS_EXPORTER_PORT or PORT variables (default is 9394).

Debugging metrics

• Time of already collected metrics rendering in response for Prometheus: yabeda_prometheus_mmap_render_duration.

These are only enabled in debug mode. See Yabeda debugging metrics on how to enable it (e.g. by specifying YABEDA_DEBUG=true in your environment variables).

Development with Docker

Get local development environment working and tests running is very easy with docker-compose:

docker-compose run app bundle
docker-compose run app bundle exec rspec

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yabeda-rb/yabeda-prometheus-mmap.

Releasing

• Bump version number in lib/yabeda/prometheus/mmap/version.rb

  In case of pre-releases keep in mind rubygems/rubygems#3086 and check version with command like Gem::Version.new(Yabeda::Prometheus::Mmap::VERSION).to_s

• Fill CHANGELOG.md with missing changes, add header with version and date.

• Make a commit:

  git add lib/yabeda/prometheus/mmap/version.rb CHANGELOG.md
  version=$(ruby -r ./lib/yabeda/prometheus/mmap/version.rb -e "puts Gem::Version.new(Yabeda::Prometheus::Mmap::VERSION)")
  git commit --message="${version}: " --edit
  

• Create annotated tag:

  git tag v${version} --annotate --message="${version}: " --edit --sign
  

• Fill version name into subject line and (optionally) some description (list of changes will be taken from changelog and appended automatically)

• Push it:

  git push --follow-tags
  

• GitHub Actions will create a new release, build and push gem into RubyGems! You're done!

License

The gem is available as open source under the terms of the MIT License.