Gem to configure GOV.UK Ruby applications
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin Rename gem to govuk_app_config Aug 22, 2017
docs Add some documentation on naming checks Jul 12, 2018
lib Update version to 1.8.0 Aug 6, 2018
spec Handle a health check which raises an exception Jul 17, 2018
.gitignore Ignore examples.txt Aug 23, 2017
.rspec Add rspec Aug 16, 2017
.ruby-version
CHANGELOG.md Update version to 1.8.0 Aug 6, 2018
Gemfile Rename gem to govuk_app_config Aug 22, 2017
Jenkinsfile
LICENSE.md
README.md Move health checks docs into own file Jul 12, 2018
Rakefile Fix `rake spec` task Sep 19, 2017
govuk_app_config.gemspec

README.md

GOV.UK Config

Adds the basics of a GOV.UK application:

  • Unicorn as a web server
  • Error reporting with Sentry
  • Statsd client for reporting stats
  • Rails logging

Installation

Add this line to your application's Gemfile:

gem "govuk_app_config"

And then execute:

$ bundle

Unicorn

Configuration

Find or create a config/unicorn.rb in the app

At the start of the file insert:

require "govuk_app_config/govuk_unicorn"
GovukUnicorn.configure(self)

Usage

To serve an app with unicorn run:

$ bundle exec unicorn -c config/unicorn.rb

Error reporting

Automatic error reporting

If you include govuk_app_config in your Gemfile, Rails' autoloading mechanism will make sure that your application is configured to send errors to Sentry.

Your app will have to have the following environment variables set:

  • SENTRY_DSN - the Data Source Name (DSN) for Sentry
  • SENTRY_CURRENT_ENV - production, staging or integration
  • GOVUK_STATSD_PREFIX - a Statsd prefix like govuk.apps.application-name.hostname

Manual error reporting

Report something to Sentry manually:

GovukError.notify("Something went terribly wrong")
GovukError.notify(ArgumentError.new("Or some exception object"))

Extra parameters are:

GovukError.notify(
  "Oops",
  extra: { offending_content_id: "123" }, # Additional context for this event. Must be a hash. Children can be any native JSON type.
  level: "debug", # debug, info, warning, error, fatal
  tags: { key: "value" } # Tags to index with this event. Must be a mapping of strings.
)

Error configuration

You can exclude certain errors from being reported using this:

GovukError.configure do |config|
  config.excluded_exceptions << "RetryableError"
end

GovukError.configure has the same options as the Sentry client, Raven. See the Raven docs for all configuration options.

Statsd

Use GovukStatsd to send stats to graphite. It has the same interface as the Ruby Statsd client.

Examples:

GovukStatsd.increment "garets"
GovukStatsd.timing "glork", 320
GovukStatsd.gauge "bork", 100

# Use {#time} to time the execution of a block
GovukStatsd.time("account.activate") { @account.activate! }

Health Checks

This Gem provides a common "health check" framework for apps. See the health check docs for more information on how to use it.

Rails logging

In Rails applications, the application will be configured to send JSON-formatted logs to STDOUT and unstructed logs to STDERR.

License

MIT License