promenade 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6038eb3692025b959c4fac797615ad3f213cef7bf44aa2acc0c0fc8abf7abc9d
-  data.tar.gz: 68c502e34e147f24ed378ff236ae85f6abadd74eb24400393f980643e2aff25f
+  metadata.gz: 21e1b0da279e0be2d796defd5ba139262e5fcae5d9eb7bcc96a0e237ed2627e0
+  data.tar.gz: 265399012b1a27ef4b4f821a7fd4b860a8d714e3c210cf10da2311c0f5cba12e
 SHA512:
-  metadata.gz: 40cf77b605a494115bd4b43002ddeba06db5b6f37d8ea7dfd110230f1642d25af77f6e7673453d645711558d20693539c44a44c947156d6edda2315ada91fe6d
-  data.tar.gz: 924beb3ee617a96e5b3e356e689817e119852e6bcfd798a38bf27109b4a278d7df77cd9ad732b5cee24bc0808546fc2f400752376378e841cfcb09ac553be8ce
+  metadata.gz: 9d53dd6240a9b318550f2c94774e46e55a943a4d8bfda8f42b1339f2f7673d802b3fe7acd22d1efd0efcef0ab9ee513dfbc943a17fcb9b270c719ca7dac3be2b
+  data.tar.gz: c3d7acde8d85895a32a384c3428771b5ed792e6fbe9810d42a60cf1639e6f7fb60333d32209f30ca430ecbe73ec3dfb06be407ffbe35bd8c9ca005d20a476685

data/Gemfile

@@ -2,3 +2,5 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in promenade.gemspec
 gemspec
+
+gem "codecov"

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    promenade (0.1.5)
+    promenade (0.1.6)
       activesupport
       prometheus-client-mmap (~> 0.9.3)
       rack
@@ -15,6 +15,10 @@ GEM
       minitest (~> 5.1)
       tzinfo (~> 1.1)
     ast (2.4.0)
+    codecov (0.1.10)
+      json
+      simplecov
+      url
     concurrent-ruby (1.0.5)
     diff-lcs (1.3)
     docile (1.3.1)
@@ -62,12 +66,14 @@ GEM
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
     unicode-display_width (1.4.0)
+    url (0.3.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
   bundler (~> 1.16)
+  codecov
   promenade!
   rake (~> 10.0)
   rspec (~> 3.0)

data/README.md

@@ -2,11 +2,158 @@
 
 [![Build Status](https://travis-ci.org/errm/promenade.svg?branch=master)](https://travis-ci.org/errm/promenade)
 [![Gem Version](https://badge.fury.io/rb/promenade.svg)](https://badge.fury.io/rb/promenade)
+[![codecov](https://codecov.io/gh/errm/promenade/branch/master/graph/badge.svg)](https://codecov.io/gh/errm/promenade)
 
 Promenade is a libary to simplify instrumenting Ruby applications with prometheus.
 
 It is currently under development.
 
+## Usage
+
+Add promenade to your Gemfile:
+
+```
+gem "promenade"
+```
+
+### Built in instrumentation
+
+Promenade includes some built in instrumentation that can be used by requiring it (for example in an initializer).
+
+Currently there is just support for [ruby-kafka](https://github.com/zendesk/ruby-kafka), but I plan to support other things soon.
+
+```
+# Instrument the ruby-kafka libary
+require "promenade/kafka"
+```
+
+### Instrumentation DSL
+
+Promenade makes recording prometheus metrics from your own code a little simpler with a DSL of sorts.
+
+`Promenade::Helper` includes some class macros for defining your own metrics, and a metric method you can use to record metrics.
+
+#### Counter
+
+A counter is a metric that exposes a sum or tally of things.
+
+```ruby
+require "promenade/helper"
+
+class WidgetService
+  include ::Promenade::Helper
+
+  counter :widgets_created do
+    doc "Records how many widgets are created"
+  end
+
+  def create
+    # Widget creation code :)
+    metric(:widgets_created).increment
+
+    # You can also add extra labels as you set increment counters
+    metric(:widgets_created).increment({ type: "guinness" })
+  end
+
+  def batch_create
+    You can increment by more than 1 at a time if you need
+    metric(:widgets_created).increment({ type: "guinness" }, 100)
+  end
+end
+```
+
+#### Gauge
+
+A gauge is a metric that exposes an instantaneous value or some snapshot of a changing value.
+
+```ruby
+require "promenade/helper"
+
+class Thermometer
+  include ::Promenade::Helper
+
+  gauge :room_temperature_celsius do
+    doc "Records room temprature"
+  end
+
+  def take_mesurements
+    metric(:room_temperature_celsius).set({ room: "lounge" }, 22.3)
+    metric(:room_temperature_celsius).set({ room: "kitchen" }, 25.45)
+    metric(:room_temperature_celsius).set({ room: "broom_cupboard" }, 15.37)
+  end
+end
+```
+
+#### Histogram
+
+A histogram samples observations (usually things like request durations or
+response sizes) and counts them in configurable buckets. It also provides a sum
+of all observed values.
+
+```ruby
+require "promenade/helper"
+
+class Calculator
+  include ::Promenade::Helper
+
+  histogram :calculator_time_taken do
+    doc "Records how long it takes to do the adding"
+    # promenade also has some bucket presets like :network and :memory for common usecases
+    buckets [0.25, 0.5, 1, 2, 4]
+  end
+
+  def add_up
+    timing = Benchmark.realtime do
+      # Some time consuming addition
+    end
+
+    metric(:calculator_time_taken).observe({ operation: "addition"}, timing)
+  end
+end
+```
+
+#### Summary
+
+Summary is similar to a histogram, but for when you just care about percentile values. Often useful for timings.
+
+```ruby
+require "promenade/helper"
+
+class ApiClient
+  include ::Promenade::Helper
+
+  summary :api_client_http_timing do
+    doc "record how long requests to the api are taking"
+  end
+
+  def get_users
+    timing = Benchmark.realtime do
+      # Makes a network call
+    end
+
+    metric(:api_client_http_timing).observe({ method: "get", path: "/api/v1/users" }, timing)
+  end
+end
+```
+
+### Exporter
+
+Because promenade is based on prometheus-client you can add the `Prometheus::Client::Rack::Exporter` middleware to your rack middleware stack to expose metrics.
+
+There is also a stand alone exporter that can be run with the `promenade` command.
+
+This is ideal if you are worried about acidently exposing your metrics, are concerned about the performance impact prometheus scrapes might have on your application, or for applications without a webserver (like background processing jobs). It does mean that you have another process to manage on your server though 🤷.
+
+The exporter runs by default on port `9394` and the metrics are avaible at the standard path of `/metrics`, the standalone exporter is congfigured to use gzip.
+
+### Configuration
+
+In a typical development environment there should be nothing for you to do. Promenade stores its state files in `tmp/promenade` and will create that directory if it does not exist.
+
+In a production environment you should try to store the state files on tmpfs for performance, you can configure the path that promenade will write to by setting the `PROMETHEUS_MULTIPROC_DIR` environment variable.
+
+If you are running the standalone exporter, you may also set the `PORT` environment variable to bind to a port other than the default (`9394`).
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/promenade/setup.rb

@@ -7,10 +7,14 @@ module Promenade
   end
 
   def self.multiprocess_files_dir
-    ENV.fetch("PROMETHEUS_MULTIPROC_DIR", root_dir.join("tmp", "prometheus"))
+    ENV.fetch("PROMETHEUS_MULTIPROC_DIR", root_dir.join("tmp", "promenade"))
   end
 
   def self.setup
+    unless File.directory? multiprocess_files_dir
+      FileUtils.mkdir_p multiprocess_files_dir
+    end
+
     Prometheus::Client.configure do |config|
       config.multiprocess_files_dir = multiprocess_files_dir
       config.pid_provider = Prometheus::Client::Support::Unicorn.method(:worker_pid_provider)

data/lib/promenade/version.rb

@@ -1,3 +1,3 @@
 module Promenade
-  VERSION = "0.1.5".freeze
+  VERSION = "0.1.6".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: promenade
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Ed Robinson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-05 00:00:00.000000000 Z
+date: 2018-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport