Repository: govuk_app_config
Gem to configure GOV.UK Ruby applications
- GitHub
- govuk_app_config
- Ownership
- #govuk-platform-reliability-team
- Hosting
- N/A
- Category
- Gems
README
Adds the basics of a GOV.UK application:
- Unicorn as a web server
- Error reporting with Sentry
- Statsd client for reporting stats
- Rails logging
- Content Security Policy generation for frontend apps
- Prometheus monitoring for EKS
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
- e.g. “production”. Make sure it is configured to be active. -
GOVUK_STATSD_PREFIX
- a Statsd prefix likegovuk.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.
)
Active Sentry environments
GovukError will only send errors to Sentry if your SENTRY_CURRENT_ENV
matches one of the ‘active environments’ in the default configuration. This is to prevent temporary test environments from flooding our Sentry account with errors.
You can add your environment to the list of active Sentry environments like so:
GovukError.configure do |config|
config.enabled_environments << "my-test-environment"
end
Error configuration
You can exclude certain errors from being reported using this:
GovukError.configure do |config|
config.excluded_exceptions << "RetryableError"
end
And you can exclude errors from being reported if they occur during the nightly data sync (on integration and staging):
GovukError.configure do |config|
config.data_sync_excluded_exceptions << "PG::Error"
end
Finally, you can pass your own callback to evaluate whether or not to capture the exception.
Note that if an exception is on the excluded_exceptions
list, or on the data_sync_excluded_exceptions
and occurs at the time of a data sync, then it will be excluded even if the custom
before_send
callback doesn’t return nil
.
GovukError.configure do |config|
config.before_send = lambda do |event, hint|
hint[:exception].is_a?(ErrorWeWantToIgnore) ? nil : event
end
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
.
Content Security Policy generation
For frontend apps, configuration can be added to generate and serve a
content security policy header. The policy is report only when the
environment variable GOVUK_CSP_REPORT_ONLY
is set, and enforced otherwise.
To enable this feature, create a file at config/initializers/csp.rb
in the
app with the following content:
GovukContentSecurityPolicy.configure
i18n rules
Some frontend apps support languages that are not defined in the i18n gem. This provides them with our own custom rules for these languages.
Prometheus monitoring for EKS
Create a /config/initializers/prometheus.rb
file in the app and add the following
require "govuk_app_config/govuk_prometheus_exporter"
GovukPrometheusExporter.configure