Sensible Logging

A logging extension with sensible defaults for Sinatra apps.

• Add a request UUID (or use an existing one if present in the X-Request-Id HTTP header) for use in logs, your app or other middlewares

• Trim the request logs to the bare minimal (inspired by lograge):

  • method
  • path
  • requesting IP address
  • status
  • duration
  • params if a GET request

  Example log line:

  method=GET path=/contact client=192.168.1.254 status=200 duration=0.124 params={"category"=>"question"}
  

• Tagged logging, with some sensible defaults:

  • severity
  • subdomain
  • environment
  • request UUID

  Example log line:

  [INFO] [www.gb] [staging] [6004bb70-7b6d-43b6-a2cf-72d0336663ba] @todo tidy sql query
  

1. Add sensible_logging to your Gemfile and install with bundle install:

gem 'sensible_logging'

2. In your app.rb register the module and then define your logging configuration:

require 'sensible_logging'

class App < Sinatra::Base
  register Sinatra::SensibleLogging

  # Initialise Sensible Logging to add our middlewares.
  sensible_logging(
    logger: Logger.new($stdout)
    )

  # Configure the log level for different environments
  configure :production do
    set :log_level, Logger::INFO
  end

  # Requests will be logged in a minimal format
  get '/' do
    'Hello!'
  end

  get '/about' do
    # The standard Sinatra logger helper will use the Sensible Logging gem
    logger.info('About page')
  end

  get '/contact' do
    # In addition to the default tags, you can add additional ones by using the `tagged` block on the `logger` helper
    # [INFO] [localhost] [development] [a9d0183d-a3c3-4081-b502-38dcf4c3c4d7] [todo] Contact page
    logger.tagged('todo') do |logger|
      logger.info('Contact page')
    end
  end

# rest of code omitted

There are a number of options that you can pass into sensible_logging:

• logger: The logging object. Default: Logger.new($stdout)
• use_default_log_tags: Includes the subdomain, RACK_ENV and unique request ID in the log tags. Default: true
• tld_length: For example, if your domain was www.google.com this would result in www being tagged as your subdomain. If your domain is www.google.co.uk, set this value to 2 to correctly identify the subdomain as www rather than www.google. Default: 1.
• log_tags: An array of additional log tags to include. This can be strings, or you can include a lambda that will be evaluated. The lambda is passed a Rack Request object, and it must return an array of string values. Default: []
• exclude_params: An array of parameter names to be excluded from GET requests. By default, GET parameters are outputted in logs. If for example with the request http://google.com/?one=dog&two=cat you didn't want the one logged, you would set exclude_params to be ['one'] Default: []
• include_log_severity: Includes the log severity in the tagged output, such as INFO, DEBUG etc Default: true

Sensible Logger will also respect the following Sinatra settings:

• log_level: The level at which your logger object should respect logs. See above example. Default: Logger::DEBUG

There is an example Sinatra app included in this repo. Here's how to use it:

bundle install
cd examples
rackup

With the app running, run some curl commands against it:

curl 'localhost:9292/hello?one=two&two=three'

You should notice in the logs:

• Standard Sinatra logger helper works out of the box within apps with tags.
• Excluded parameters are not included, in this example two based on config.ru
• The request log is minimal compared to out of the box Sinatra.
• env['request_id'] is now available to group log lines from the same request together, or to use in additional services such as Sentry.

To quote lograge (which was the inspiration for this library):

The syntax is heavily inspired by the log output of the Heroku router. It doesn't include any timestamp by default, instead, it assumes you use a proper log formatter instead.

1. Update the version number lib/sensible_logging/version.rb
2. Create a git commit and tag with the new version number: git tag -a v0.4.2 -m "v0.4.2"
3. Create a new PR with this change and once approved, merge to main
4. Once approved and merged in, locally, run: bundle exec rake release which will build and push the new gem to Rubygems

By David Winter with contributions from Mark Sta Ana & Anthony King

MIT