gds_metrics 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fb3bcd923d980e4161d41cb573069239b3e6fdd711f3378ff1b1547e02669a7
-  data.tar.gz: 5e4500ebed2c9e26214d9d0784e82b66a18a58b9ea479b3436b3f5f8bff250d7
+  metadata.gz: 0ba99ea6af93f3dbd080c86097d2937a423b528599772066d43c58bd678d436b
+  data.tar.gz: 0cdf7fd8e318b815a91582683d9d566078d46f830539ac267d69a98e1c122995
 SHA512:
-  metadata.gz: 7cebb8edb91fb588e5f8d4951087286699cc520818ff6ba49e5fd8da2bce4b968c56c872933a6027360695eab0d8a3fe6cb304aaf47f026dfa947ade1fd2384e
-  data.tar.gz: 4563e8671144d93a830115c0e16e4f35993793d8b5a9d30b1f71678767c3af6da3528d5a9a755e36ab8e209c561c651e34e6bafd1f552bd04f49c23a2f2c8c50
+  metadata.gz: 8ea263c9680928bb3a22df92ca567ff13d8c641aa048428e26a04cde2c0092737e4459426c68123f35b0300deeecc576be86c58038b8cd57b32e8dde5e7ea3dc
+  data.tar.gz: fe71f518e8c9a15599321569b9a29af4dbe15efab8a0ff3d7b20d5029967d359093f483eeb3225a29d08511d309bd1f01a98fb0625213bda09c9119bcfaaba3f

data/README.md

@@ -1,65 +1,105 @@
-## GDS Metrics
+# GDS metrics for Ruby apps
 
-Instrument your web app to export [Prometheus](https://prometheus.io/) metrics.
+GDS Metrics are in Alpha and these instructions are subject to change.
 
-### Overview
+GDS Ruby metrics enable your [Ruby][] web app to export performance data to [Prometheus][], you can add metrics to your app using this [Ruby gem][].
 
-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.
+This gem is a thin wrapper around gitlab's [prometheus-client-mmap][] that:
 
-### Setup for Rails
+* adds a [railtie][] for easy configuration for [Rails][] apps
+* fixes label naming so it's consistent with the official [Prometheus Ruby Client][]
+* changes url path labels from unique paths to their Rails controller and action if the url path matches a route. For example - `blogs/8`, `blogs/9` => `blogs#view`
+* protects your `/metrics` endpoint with basic HTTP authentication for apps deployed to GOV.UK PaaS
 
-1. Add the [latest version of the gem](https://rubygems.org/gems/gds_metrics) to
-your Gemfile:
+Once you’ve added the gem, metrics data is served from your app's metrics endpoint and is scraped by Prometheus. This data can be turned into performance dashboards using [Grafana][].
 
-```ruby
-gem 'gds_metrics', '~> x.x.x'
-```
+You can read more about the Reliability Engineering monitoring solution [here][].
 
-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)
+## Before using GDS metrics
 
-You should see a page containing metrics like `http_req_duration_seconds`.
+Before using GDS metrics you should have:
 
-The gem is now set up correctly.
+* created a [Rails][] or [Rack][] app
+* deployed it to [GOV.UK Platform as a Service (PaaS)][]
 
-### Non-Rails apps
+## How to install metrics for 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).
+To use GDS metrics you must:
 
-### Running on the PaaS
+1. Add the [latest version of the gem](https://rubygems.org/gems/gds_metrics) to your Gemfile, for example:
 
-If your app runs on the [GOV.UK PaaS](https://www.cloud.service.gov.uk/), you'll
-need to set the environment variable with:
+    ```gem 'gds_metrics'```
 
-```bash
-$ cf set-env your-app-name PROMETHEUS_METRICS_PATH /metrics
-```
+2. Run the following command to install the gem:
 
-This command makes the metrics endpoint available in production, whereas the
-setup steps above only applied temporarily to the server on your local machine.
+    ```bundle install```
 
-In production, this endpoint is automatically protected with authentication.
-Citizens will not be able to see your metrics.
+3. Restart your Rails server by running:
 
-### Adding custom metrics
+    ```bundle exec rails server```
 
-This step is optional.
+4. Visit any page of your app (for example [the index page][]) to generate some site traffic
 
-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.
+5. Visit the metrics endpoint at `/metrics` to check if the gem was set up correctly. If it's set up correctly, you will see a page containing some metrics (for example `http_req_duration_seconds`).
 
-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/).
+If you're not using Rails, you'll also need to add GDS::Metrics::Middleware as [Rack middleware][] before running your Rails server. You’ll also need to refer to your framework's documentation, for example [Sinatra][] or [Grape][] middleware.
+
+## Running on GOV.UK Platform as a Service (PaaS)
+
+When running on PaaS, citizens won’t see your metrics in production as this endpoint is automatically protected with authentication.
+
+The PaaS documentation has information on how you can [deploy a basic Ruby on Rails app][]. You can also read the official Cloud Foundry guide which has detailed information on [deploying Ruby on Rails apps][].
+
+## Testing
+
+The test suite can be run in full using `bundle exec rake`, this includes unit and integration tests as well as a code style check using the [Govuk Linter][].
+
+Individual unit tests in `/spec/gds_metrics` can be run using `rspec path/to/test.rb`
+
+Because of the need to test the apps integration with rails there is a dummy Rails app within `/spec`. This app is run from within the test suite and integration tests are then executed against it. At the moment these tests cannot be run individually but can be run separately from the unit tests by running `pushd spec/dummy && bundle exec rake && popd`
+
+## Optional configuration
+
+You can change the path for serving metrics (by default `/metrics`) by setting the `PROMETHEUS_METRICS_PATH` [environment variable][].
+
+## How to setup extended metrics
+
+While common metrics are recorded by default, you can also:
+
+* record your own metrics such as how many users are signed up for your service, or how many emails it's sent
+* use the Prometheus interface to set your own metrics as the metrics Ruby gem is built on top of [prometheus-client-mmap][]
+
+You can read more about the different types of metrics available in the [Prometheus documentation][].
+
+## Contributing
+
+GDS Reliability Engineering welcome contributions. We'd appreciate it if you write tests with your changes and document them where appropriate, this will help us review them quickly.
+
+## Licence
+
+This project is licensed under the [MIT License][].
+
+
+
+[Ruby]: https://www.ruby-lang.org/en/
+[Rails]: http://rubyonrails.org/
+[railtie]: http://api.rubyonrails.org/classes/Rails/Railtie.html
+[Prometheus]: https://prometheus.io/
+[Ruby gem]: https://rubygems.org/gems/gds_metrics
+[Grafana]: https://grafana.com/
+[here]: https://reliability-engineering.cloudapps.digital/#reliability-engineering
+[Rack]: https://rack.github.io/
+[GOV.UK Platform as a Service (PaaS)]: https://www.cloud.service.gov.uk/
+[the index page]: http://localhost:3000/
+[Rack middleware]: https://www.amberbit.com/blog/2011/07/13/introduction-to-rack-middleware/
+[Sinatra]: http://sinatrarb.com/intro#Rack%20Middleware
+[Grape]: https://github.com/ruby-grape/grape#using-custom-middleware
+[PaaS]: https://www.cloud.service.gov.uk/
+[environment variable]: https://docs.cloud.service.gov.uk/#environment-variables
+[deploy a basic Ruby on Rails app]: https://docs.cloud.service.gov.uk/#deploy-a-ruby-on-rails-app
+[deploying Ruby on Rails apps]: http://docs.cloudfoundry.org/buildpacks/ruby/gsg-ror.html
+[Prometheus Ruby Client]: https://github.com/prometheus/client_ruby#metrics
+[prometheus-client-mmap]: https://gitlab.com/gitlab-org/prometheus-client-mmap
+[Prometheus documentation]: https://prometheus.io/docs/concepts/metric_types/
+[MIT License]: https://github.com/alphagov/gds_metrics_ruby/blob/master/LICENSE
+[Govuk Linter]: https://github.com/alphagov/govuk-lint

data/lib/gds_metrics.rb

@@ -12,6 +12,7 @@ require "gds_metrics/config"
 require "gds_metrics/auth"
 require "gds_metrics/gzip"
 require "gds_metrics/railtie" if defined?(Rails)
+require "gds_metrics/path_converter"
 
 GDS::Metrics::Config.instance.populate_from_env
 GDS::Metrics::Mmap.setup

data/lib/gds_metrics/middleware.rb

@@ -8,7 +8,19 @@ module GDS
           use GDS::Metrics::Gzip
           use GDS::Metrics::Auth
 
-          use Prometheus::Client::Rack::Collector, registry: Proxy.new
+          if defined?(Rails)
+            rails_label_builder = proc do |env|
+              {
+                method: env['REQUEST_METHOD'].downcase,
+                host:   env['HTTP_HOST'].to_s,
+                controller:   GDS::Metrics::PathConverter.convert_rails_path_to_route(env['PATH_INFO'].to_s),
+              }
+            end
+            use Prometheus::Client::Rack::Collector, registry: Proxy.new, &rails_label_builder
+          else
+            use Prometheus::Client::Rack::Collector, registry: Proxy.new
+          end
+
           use Prometheus::Client::Rack::Exporter
 
           run app

data/lib/gds_metrics/path_converter.rb

@@ -0,0 +1,14 @@
+module GDS
+  module Metrics
+    class PathConverter
+      def self.convert_rails_path_to_route(path)
+        # Convert a path to it's controller and action so we minimise the number of unique timeseries
+        # in the case of IDs/variables in paths. Fallback to path if no route found
+        route = Rails.application.routes.recognize_path(path)
+        "#{route[:controller]}\##{route[:action]}"
+      rescue ActionController::RoutingError
+        nil
+      end
+    end
+  end
+end

data/lib/gds_metrics/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gds_metrics
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.1.0
 platform: ruby
 authors:
 - Government Digital Service
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-19 00:00:00.000000000 Z
+date: 2018-04-30 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/path_converter.rb
 - lib/gds_metrics/proxy.rb
 - lib/gds_metrics/railtie.rb
 - lib/gds_metrics/version.rb
@@ -144,7 +145,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: GDS Metrics