GDS metrics for Ruby apps
GDS Metrics are in Alpha and these instructions are subject to change.
This gem is a thin wrapper around gitlab's prometheus-client-mmap that:
- 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 -
- protects your
/metricsendpoint with basic HTTP authentication for apps deployed to GOV.UK PaaS
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.
You can read more about the Reliability Engineering monitoring solution here.
Before using GDS metrics
Before using GDS metrics you should have:
How to install metrics for Rails apps
To use GDS metrics you must:
Add the latest version of the gem to your Gemfile, for example:
Run the following command to install the gem:
Restart your Rails server by running:
bundle exec rails server
Visit any page of your app (for example the index page) to generate some site traffic
Visit the metrics endpoint at
/metricsto check if the gem was set up correctly. If it's set up correctly, you will see a page containing some metrics (for example
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.
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
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
You can change the path for serving metrics (by default
/metrics) by setting the
PROMETHEUS_METRICS_PATH environment variable.
If you are running
blue-green deployments through a cf plugin like autopilot you should disable the basic auth on the
\metrics endpoint and use IP whitelisting by setting the
METRICS_BASIC_AUTH environment variable to
false. This will minimise gaps in metrics during deployment.
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.
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.
This project is licensed under the MIT License.