gds_metrics 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae59f4c6dcfbb57dc0ad51ee689ea926b8c58dc78684df7fc749fac81192e1d0
-  data.tar.gz: c3207917a94edd3fc16b59c7b8c0184f685fcf01e03de63ca6956f0210a5a27b
+  metadata.gz: 8fb3bcd923d980e4161d41cb573069239b3e6fdd711f3378ff1b1547e02669a7
+  data.tar.gz: 5e4500ebed2c9e26214d9d0784e82b66a18a58b9ea479b3436b3f5f8bff250d7
 SHA512:
-  metadata.gz: aabeeedaaf9d71aef66b729d8088bfff7d1516fa542efb6d0c2a749ece6e6a2e4ce267d7124642ea0ffb6f0cfcaf1377b4b7359e9833fbb2938e7a74f04d97ec
-  data.tar.gz: 55bb3cd96daa713840223d2c109787b73a6f94e12a52b299eafeb132b2a773c14dda90e6222256b7d3b8d11eaa17fadf6c37c4ab7b24c8f6a9bf188ae3f08dfe
+  metadata.gz: 7cebb8edb91fb588e5f8d4951087286699cc520818ff6ba49e5fd8da2bce4b968c56c872933a6027360695eab0d8a3fe6cb304aaf47f026dfa947ade1fd2384e
+  data.tar.gz: 4563e8671144d93a830115c0e16e4f35993793d8b5a9d30b1f71678767c3af6da3528d5a9a755e36ab8e209c561c651e34e6bafd1f552bd04f49c23a2f2c8c50

data/README.md

@@ -1,5 +1,65 @@
 ## GDS Metrics
 
-**This is under development.**
+Instrument your web app to export [Prometheus](https://prometheus.io/) metrics.
 
-Instrument your web app to export Prometheus metrics.
+### Overview
+
+This gem can be added to your web app to capture metrics about how it's
+performing. These metrics are served from an endpoint of your app and can be
+scraped by Prometheus and turned into Grafana dashboards.
+
+### Setup for Rails
+
+1. Add the [latest version of the gem](https://rubygems.org/gems/gds_metrics) to
+your Gemfile:
+
+```ruby
+gem 'gds_metrics', '~> x.x.x'
+```
+
+2. Install the gem: `bundle install`
+3. Set an environment variable: `export PROMETHEUS_METRICS_PATH=/metrics`
+4. Restart your rails server: `bundle exec rails server`
+5. Visit any page of your app, e.g. [the index page](http://localhost:3000/)
+6. Visit the metrics endpoint: [localhost:3000/metrics](http://localhost:3000/metrics)
+
+You should see a page containing metrics like `http_req_duration_seconds`.
+
+The gem is now set up correctly.
+
+### Non-Rails apps
+
+If you're not using Rails, before running your server, you'll also need to add
+`GDS::Metrics::Middleware` as a
+[Rack middleware](https://www.amberbit.com/blog/2011/07/13/introduction-to-rack-middleware/).
+Refer to your framework's documentation for how to do this, e.g.
+[Sinatra](http://sinatrarb.com/intro#Rack%20Middleware),
+[Grape](https://github.com/ruby-grape/grape#using-custom-middleware).
+
+### Running on the PaaS
+
+If your app runs on the [GOV.UK PaaS](https://www.cloud.service.gov.uk/), you'll
+need to set the environment variable with:
+
+```bash
+$ cf set-env your-app-name PROMETHEUS_METRICS_PATH /metrics
+```
+
+This command makes the metrics endpoint available in production, whereas the
+setup steps above only applied temporarily to the server on your local machine.
+
+In production, this endpoint is automatically protected with authentication.
+Citizens will not be able to see your metrics.
+
+### Adding custom metrics
+
+This step is optional.
+
+By default, common metrics will be recorded, but you can record your own
+metrics, too. You might want to capture how many users are signed up for your
+service or how many emails it's sent.
+
+The gem is built on top of the `prometheus_ruby_client`, so you can use the
+[interface it provides](https://github.com/prometheus/client_ruby#metrics) for
+this. There's more documentation on types of metric
+[here](https://prometheus.io/docs/concepts/metric_types/).

data/lib/gds_metrics/middleware.rb

@@ -8,7 +8,7 @@ module GDS
           use GDS::Metrics::Gzip
           use GDS::Metrics::Auth
 
-          use Prometheus::Client::Rack::Collector
+          use Prometheus::Client::Rack::Collector, registry: Proxy.new
           use Prometheus::Client::Rack::Exporter
 
           run app

data/lib/gds_metrics/mmap.rb

@@ -1,9 +1,28 @@
 module GDS
   module Metrics
     module Mmap
-      def self.setup
-        directory = Config.instance.mmap_directory
-        Prometheus::Client.configuration.multiprocess_files_dir = directory
+      class << self
+        def setup
+          directory = Config.instance.mmap_directory
+          Prometheus::Client.configuration.multiprocess_files_dir = directory
+        end
+
+        def clean
+          directory = Config.instance.mmap_directory
+
+          Dir.glob("#{directory}/*").each do |path|
+            next unless database_file?(path)
+            FileUtils.rm(path)
+          end
+        end
+
+      private
+
+        def database_file?(path)
+          path.end_with?(".db") && METRIC_TYPES.any? { |t| path.include?(t) }
+        end
+
+        METRIC_TYPES = %w(counter histogram summary).freeze
       end
     end
   end

data/lib/gds_metrics/proxy.rb

@@ -0,0 +1,35 @@
+module GDS
+  module Metrics
+    class Proxy
+      def initialize(registry = Prometheus::Client.registry)
+        @registry = registry
+      end
+
+      def counter(metric_name, *args)
+        @registry.counter(rename(metric_name), *args)
+      end
+
+      def histogram(metric_name, *args)
+        @registry.histogram(rename(metric_name), *args)
+      end
+
+      def summary(*)
+        NullSummary.new
+      end
+
+    private
+
+      def rename(metric_name)
+        {
+          http_requests_total: :http_server_requests_total,
+          http_exceptions_total: :http_server_exceptions_total,
+          http_req_duration_seconds: :http_server_request_duration_seconds,
+        }.fetch(metric_name, metric_name)
+      end
+
+      class NullSummary
+        def observe(*); end
+      end
+    end
+  end
+end

data/lib/gds_metrics/version.rb

@@ -1,5 +1,5 @@
 module GDS
   module Metrics
-    VERSION = "0.0.1".freeze
+    VERSION = "0.0.2".freeze
   end
 end

data/lib/gds_metrics.rb

@@ -7,6 +7,7 @@ require "prometheus/client/rack/exporter"
 require "gds_metrics/version"
 require "gds_metrics/mmap"
 require "gds_metrics/middleware"
+require "gds_metrics/proxy"
 require "gds_metrics/config"
 require "gds_metrics/auth"
 require "gds_metrics/gzip"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gds_metrics
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-13 00:00:00.000000000 Z
+date: 2018-02-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prometheus-client-mmap
@@ -121,6 +121,7 @@ files:
 - lib/gds_metrics/gzip.rb
 - lib/gds_metrics/middleware.rb
 - lib/gds_metrics/mmap.rb
+- lib/gds_metrics/proxy.rb
 - lib/gds_metrics/railtie.rb
 - lib/gds_metrics/version.rb
 homepage: https://github.com/alphagov/gds_metrics_ruby